diff --git a/.agents/skills/fix/SKILL.md b/.agents/skills/fix/SKILL.md index a6062c689b..2eee70cbea 100644 --- a/.agents/skills/fix/SKILL.md +++ b/.agents/skills/fix/SKILL.md @@ -1,19 +1,20 @@ --- name: fix -description: Diagnose a bug, update its behavioral spec, create reviewable fix plan and task files, then implement with TDD after user approval. +description: Diagnose a bug, update its behavioral spec, create reviewable fix plan and task files, then hand off for explicit implementation with TDD. --- # Fix Use the same durable, reviewable workflow as feature work. Diagnose first, then produce the spec amendment, fix plan, and task files before changing production -code. The user can review those artifacts, switch the main session to a cheaper -model, and explicitly authorize native subagents for parallel-safe tasks. +code. The user reviews those artifacts, switches the main session if desired, +and sends a later explicit implementation request. Native subagents still +require explicit authorization. ## Core Flow ```text -Evidence -> Root cause -> Spec amendment -> Fix plan + tasks -> User approval/model switch -> TDD implementation -> PR AI review +Evidence -> Root cause -> Spec amendment -> Fix plan + tasks -> Design-package handoff -> Explicit implementation request -> TDD implementation -> PR AI review ``` Do not patch production code before the planning checkpoint unless the user @@ -62,7 +63,7 @@ Follow the `/plan` structure, with these fix-specific requirements: - Keep `parallelism: sequential` by default in each task; waves are a human decision aid, not authorization to delegate. -## Phase 3: User Review And Model Switch +## Phase 3: Design-Package Handoff Before changing production or permanent test code, present: @@ -72,13 +73,17 @@ Before changing production or permanent test code, present: - task waves, parallel candidates, and exact validation commands; and - risks and out-of-scope work. -Pause for the user to approve. At that point the user may switch the main -session to a lower-cost implementation model and may explicitly ask to use -subagents. Do not infer subagent authorization from the plan. +End the turn after this handoff. Do not call `ask_user_question_kandev` (or an +equivalent approval prompt) to ask the user to approve the package or switch +models. The user reviews the files, switches the main session if desired, and +sends a later explicit implementation request. The files may remain +`draft`/`pending`; do not wait for a separate approval marker. Do not infer +subagent authorization from the plan. -## Phase 4: Implement With TDD +## Phase 4: Implement With TDD After Handoff -Execute approved tasks sequentially by default: +After the user explicitly asks to implement, execute the tasks sequentially by +default: 1. Mark the task `in_progress`. 2. Write and run the regression test; confirm it fails for the expected reason. @@ -93,7 +98,7 @@ runtime usage-metadata confirmation. Only launch tasks marked parallel-safe. ## Phase 5: PR Review -After all approved task checks pass, commit, push, and open the PR. Do not run +After all task checks pass, commit, push, and open the PR. Do not run automatic local simplify, QA, code/security review, or broad verification. The two configured PR AI reviewers are the semantic-review gate. Use `/pr-fixup` only for CI failures or actionable reviewer findings, rerunning only the @@ -107,6 +112,6 @@ disagree, or the same targeted check fails three times. ## Final Report -Report the root cause, spec/plan/task paths, approval and model-switch point, +Report the root cause, spec/plan/task paths, design-package handoff, subagents explicitly authorized (if any), changed files, tests run, and current PR-review status. diff --git a/.agents/skills/harness-improvement/references/agents.md b/.agents/skills/harness-improvement/references/agents.md index 7c48ace533..bfe3c27edc 100644 --- a/.agents/skills/harness-improvement/references/agents.md +++ b/.agents/skills/harness-improvement/references/agents.md @@ -11,8 +11,10 @@ not prohibited by this policy. 1. Use a strong model for discovery, specs, plans, task files, and high-risk design. -2. Pause at the completed-plan checkpoint and ask the user to switch the main - conversation to a lower-cost implementation/test model. +2. At the completed-plan checkpoint, return control with a concise handoff. Do + not call `ask_user_question_kandev` or ask the user to approve the package or + switch models. The user reviews the artifacts, changes the model if desired, + and sends a later explicit implementation request. 3. Execute task files sequentially by default. Plans may label parallel-safe waves, but launch native subagents only after the user explicitly asks. 4. Ask the user to switch back to a strong model only for an architectural, diff --git a/.agents/skills/plan/SKILL.md b/.agents/skills/plan/SKILL.md index 070249aa42..59cf724d71 100644 --- a/.agents/skills/plan/SKILL.md +++ b/.agents/skills/plan/SKILL.md @@ -6,8 +6,9 @@ description: Create a committed implementation plan from a feature spec. Explore # Create Implementation Plan This is a primary-session artifact skill. The user-started conversation creates -the plan and task files, then the user manually switches that same conversation -to an implementation model to execute them. +the plan and task files, then returns control with a handoff. The user reviews +the files, switches that same conversation to an implementation model if +desired, and sends the explicit request to execute them. Translate a feature spec into a concrete, phased implementation plan saved under `docs/plans//`. Plans and task files are committed implementation @@ -221,6 +222,15 @@ change `status` to `done`, update its `## Results`, and synchronize the corresponding checkbox/status and `## Verification Results` in `plan.md`. ``` +### 6. End the design turn + +After `plan.md` and every task file are written and validated, report their +paths, dependency order, exact checks, and open risks as a compact handoff, +then end the turn. Do not call `ask_user_question_kandev` (or an equivalent +approval prompt) to ask the user to approve the plan or switch models. The user +reviews the artifacts and controls the next implementation request and model +choice. + ### Style rules - **Be specific.** Name exact file paths, function signatures, SQL column names. The implementing agent should not need to re-explore the codebase. diff --git a/.agents/skills/planner-orchestration/SKILL.md b/.agents/skills/planner-orchestration/SKILL.md index c47b2a3a38..29d6105252 100644 --- a/.agents/skills/planner-orchestration/SKILL.md +++ b/.agents/skills/planner-orchestration/SKILL.md @@ -19,15 +19,17 @@ conversation so the active model, transcript, and costs are visible in one place 1. **Design checkpoint — strong model.** Use the user's strong model for clarification, codebase investigation, specs, plans, task decomposition, and high-risk design decisions. Default Codex guidance is GPT-5.6 Sol/high. -2. **Implementation checkpoint — user switch.** Once the spec, plan, and task - files are ready, summarize their paths and ask the user to switch the main - session to the lower-cost implementation model. Default Codex guidance is - GPT-5.6 Terra/medium. Do not silently continue on the strong model when the - user has asked for a cost-controlled workflow. -3. **Execution checkpoint — lower-cost model.** In the same conversation, read - the approved task file, mark it `in_progress`, implement with `/tdd`, run its - exact targeted checks, and mark it `done`. Work sequentially through the - plan by default. +2. **Design-package handoff.** Once the spec, plan, and task files are ready, + summarize their paths and end the turn. Do not call + `ask_user_question_kandev` (or an equivalent approval prompt) to ask the + user to approve the package or switch models. The user reviews the files, + switches the main session if desired, and sends a later explicit + implementation request. The files may remain `draft`/`pending`; do not wait + for a separate approval marker. +3. **Execution checkpoint.** After that explicit request, read the + task file, mark it `in_progress`, implement with `/tdd`, run its exact + targeted checks, and mark it `done`. Work sequentially through the plan by + default. The user, not the harness, chooses the active implementation model. 4. **Escalation checkpoint.** Stop and ask the user to switch back to a stronger model before an architectural redesign, a new public contract, a migration or persistence boundary, or a high-impact security decision. Record a durable @@ -113,8 +115,8 @@ Treat the OpenCode App as trusted semantic evidence only when `trusted_producer= when the user explicitly asks to manage persistent Kandev tasks or sessions. - Do not create worktrees solely to parallelize plan tasks unless the user has explicitly authorized subagents for parallel-safe tasks. -- Do not continue past a model checkpoint by assuming the user accepted the - cost. State the recommended switch and wait when the choice materially - affects cost or quality. +- Do not continue from the design-package handoff automatically or treat + artifact creation as implementation authorization. Wait for a later explicit + implementation request; the user controls any model switch between turns. - Do not replace durable specs, plans, task files, tests, or verification with chat-only summaries. diff --git a/.agents/skills/spec-driven-development/SKILL.md b/.agents/skills/spec-driven-development/SKILL.md index 2ecf71705f..3eb9aedc1d 100644 --- a/.agents/skills/spec-driven-development/SKILL.md +++ b/.agents/skills/spec-driven-development/SKILL.md @@ -1,6 +1,6 @@ --- name: spec-driven-development -description: "Single-session Kandev feature workflow: clarify intent, create durable specs, plans, and task files on a strong model, then implement and verify them after the user switches the main session to a lower-cost model." +description: "Single-session Kandev feature workflow: clarify intent, create durable specs, plans, and task files, then hand off for user-directed model selection before implementation and verification." --- # Spec-Driven Development @@ -13,7 +13,7 @@ authorizes them after selecting the implementation model. ## Core Flow ```text -Intent -> Spec -> Plan + task files -> User model switch -> Sequential TDD implementation -> PR AI review -> Report +Intent -> Spec -> Plan + task files -> Design-package handoff -> Explicit implementation request -> Sequential TDD implementation -> PR AI review -> Report ``` Do not replace the spec, plan, or task files with chat-only notes. Do not skip @@ -27,19 +27,24 @@ commit instructions as execution guidance for Phase 5, not as permission to skip Phases 1–4. Before editing production or permanent test files, verify one of these conditions: -1. The request references an approved spec, plan, and current task file; or -2. The user explicitly says to skip spec/plan/task creation. +1. A prior design turn produced the spec, plan, and current task file, and the + user now explicitly asks to implement them; or +2. The request references an existing reviewed spec, plan, and current task + file; or +3. The user explicitly says to skip spec/plan/task creation. If neither is true, create or update the spec, plan, and task files, record any -existing partial implementation as continuation context, and stop at the model -switch checkpoint. A phase label or generic "implement" directive generated by -a Kandev workflow is not an explicit opt-out. +existing partial implementation as continuation context, and stop at the +design-package handoff. Do not call `ask_user_question_kandev` or ask the user +to approve the package or switch models at that checkpoint. A phase label or +generic "implement" directive generated by a Kandev workflow is not an +explicit opt-out. When a user explicitly asks to proceed with feature planning, complete the whole -strong-model design package — spec, plan, and task files — before pausing for -review or a model switch. Pause after a standalone spec only when the user asks -to review that spec before planning, or when a material open question blocks a -safe plan. +strong-model design package — spec, plan, and task files — before returning +control. Do not add an approval/model-switch question at the handoff. Pause +after a standalone spec only when the user asks to review that spec before +planning, or when a material open question blocks a safe plan. ## Phase 0: Track The Work @@ -49,7 +54,7 @@ Keep a visible task list and mark each phase as it completes: 2. Create or update the spec 3. Create the implementation plan 4. Decompose it into task files -5. Pause for the user to switch the main model +5. End the design turn and wait for the user's explicit implementation request 6. Execute tasks with TDD and targeted checks (sequential by default) 7. Open PR, address CI/review findings, record, and summarize @@ -80,11 +85,17 @@ dependency waves and label parallel-safe candidates, but those labels are a human decision aid: the primary session executes sequentially unless the user explicitly asks to use subagents. -## Model-Switch Checkpoint +## Design-Package Handoff Before any implementation, report the spec path, plan path, task-file list, -planned test commands, and any open risks. Ask the user to manually switch the -main conversation to the lower-cost implementation model. +planned test commands, and any open risks. + +After reporting the handoff, end the turn. Do not call +`ask_user_question_kandev` (or an equivalent approval prompt), and do not ask +the user to approve the artifacts or switch models. The user reviews the files, +switches the model if desired, and sends a later explicit implementation +request. The files may remain `draft`/`pending`; do not wait for a separate +approval marker. Recommended Codex route: @@ -93,9 +104,9 @@ Recommended Codex route: - GPT-5.6 Terra/medium for implementation, TDD, targeted tests, and integration. - GPT-5.6 Luna/low only for short, mechanical, read-only status work. -Resume only after approval or an explicit instruction to continue at the -current model. Never infer a successful switch from a model's prose; inspect -runtime model-usage metadata when confirmation is required. +Begin implementation only after that explicit implementation request. Never +infer a successful model switch from a model's prose; the user's runtime model +choice is authoritative when model confirmation is required. ## Phase 5: Execute Tasks diff --git a/.agents/skills/spec/SKILL.md b/.agents/skills/spec/SKILL.md index 5777fbf176..078eba0023 100644 --- a/.agents/skills/spec/SKILL.md +++ b/.agents/skills/spec/SKILL.md @@ -218,4 +218,9 @@ A padded spec is worse than a short one — it hides the requirements behind cer - **Present tense, active voice.** "The agent resumes the turn" — not "the turn will be resumed by the agent". - **Concrete over abstract.** "Wakeups fire at most once per 60s per agent" is testable; "wakeups are rate-limited appropriately" is not. - **Assumptions visible.** If you infer behavior from current code, name the assumption and keep it in Open questions until confirmed. -- **Approval gate.** Do not proceed to `/plan` or implementation until the user has approved the spec or explicitly asked to continue with named open questions. +- **Review boundary.** When `/spec` is a standalone request, finish the spec + and return control without calling `ask_user_question_kandev` (or an + equivalent prompt) solely to request approval. When `/spec` is part of + `/spec-driven-development` or `/fix` planning, continue through the plan and + task files before the design-package handoff. A material open question that + prevents a safe plan is still a valid reason to ask for clarification. diff --git a/.claude/commands/spec-driven-development.md b/.claude/commands/spec-driven-development.md index 997af3b335..fea9157257 100644 --- a/.claude/commands/spec-driven-development.md +++ b/.claude/commands/spec-driven-development.md @@ -8,9 +8,11 @@ effort: high Use `.agents/skills/spec-driven-development/SKILL.md` for the full flow; the root `AGENTS.md`/`CLAUDE.md` single-session model workflow applies. Create the -durable artifacts on the strong model, pause for the user's manual switch, then -implement and run the task-defined tests in the same conversation. The PR AI -reviewers provide the semantic gate after PR creation; do not add local QA, -review, simplify, security, or broad verification gates by default. +durable artifacts, return a design-package handoff, and end the turn. Do not +ask for approval or a model switch; the user reviews the files, changes the +model if desired, and later asks to implement and run the task-defined tests in +the same conversation. The PR AI reviewers provide the semantic gate after PR +creation; do not add local QA, review, simplify, security, or broad verification +gates by default. Plans may label parallel-safe waves, but use subagents only when the user explicitly authorizes them after selecting the implementation model. diff --git a/.cursor/rules/kandev-harness.mdc b/.cursor/rules/kandev-harness.mdc index 7960b536a4..19fd66f828 100644 --- a/.cursor/rules/kandev-harness.mdc +++ b/.cursor/rules/kandev-harness.mdc @@ -14,8 +14,10 @@ Use the shared Kandev harness as the source of truth: For harness edits, load `.agents/skills/harness-improvement/SKILL.md` and the relevant bundled references under `.agents/skills/harness-improvement/references/`. Use `references/platforms/` before external docs. -Use strong models for specs/plans and pause for the user's manual switch to a -lower-cost model before implementation. Plans may mark parallel-safe waves; the -feature and fix skills define task validation and any user-authorized -implementation delegation. Do not create project custom-agent files merely to -route model tiers. Platform-provided explorers remain available. +Use the strongest available model for specs/plans, then return +a design-package handoff and end the turn. Do not ask for approval or a model +switch; the user reviews the files, changes the model if desired, and later +asks to implement. Plans may mark parallel-safe waves; the feature and fix +skills define task validation and any user-authorized implementation delegation. +Do not create project custom-agent files merely to route model tiers. +Platform-provided explorers remain available. diff --git a/AGENTS.md b/AGENTS.md index 7951cc9842..c17e6d0f60 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -137,20 +137,24 @@ Use the user's strong model for specs, plans, task files, and high-risk design. When the user asks to proceed with feature planning, produce the spec, plan, and task files as one design package; pause after a spec only when the user explicitly requests spec review or a material open question prevents planning. -At the completed-plan checkpoint, ask the user to manually switch the main -session to a lower-cost implementation model. Detailed feature, fix, -validation, and delegation routing lives in the relevant skills, especially -`planner-orchestration`. +At the completed-plan checkpoint, return control with a concise handoff. Do not +call `ask_user_question_kandev` (or an equivalent approval prompt) to ask the +user to approve the package or switch models. The user reviews the files, +switches the main session if desired, and sends a later explicit implementation +request. Detailed feature, fix, validation, and delegation routing lives in the +relevant skills, especially `planner-orchestration`. Workflow-generated phase text such as `[IMPROVE PHASE]`, "implement the requested change", TDD checklists, verification commands, or commit steps does not opt a feature or behavior-changing fix out of spec-driven development. If -the request does not reference an approved spec, plan, and task file, run +the request neither references an existing reviewed package nor explicitly asks +to implement a package created during a prior design turn, run `spec-driven-development` through the plan/task checkpoint and stop before -production or permanent test changes. Continue directly to implementation only -when approved task artifacts already exist, or when the user explicitly says -to skip planning; a generic implementation envelope is not that explicit -opt-out. +production or permanent test changes. End that turn at the design-package +handoff; do not ask for approval or a model switch. A generic implementation +envelope is not an explicit opt-out; the user must either explicitly ask to +implement the created package in a later turn or explicitly say to skip +planning. ### Kandev Task Creation @@ -207,4 +211,4 @@ For developing in ephemeral cloud VMs (Cursor Cloud, Codex, GitHub Codespaces, e --- -**Last Updated**: 2026-08-01 +**Last Updated**: 2026-08-02