chore: defer planning approval to next turn (#2170)

.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
+code. The user reviews those artifacts, switches the main session if desired,
-model, and explicitly authorize native subagents for parallel-safe tasks.
+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
+End the turn after this handoff. Do not call `ask_user_question_kandev` (or an
-session to a lower-cost implementation model and may explicitly ask to use
+equivalent approval prompt) to ask the user to approve the package or switch
-subagents. Do not infer subagent authorization from the plan.
+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.

.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
+2. At the completed-plan checkpoint, return control with a concise handoff. Do
-   conversation to a lower-cost implementation/test model.
+   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,

.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
+the plan and task files, then returns control with a handoff. The user reviews
-to an implementation model to execute them.
+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/<feature>/`. 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.

.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
+2. **Design-package handoff.** Once the spec, plan, and task files are ready,
-   files are ready, summarize their paths and ask the user to switch the main
+   summarize their paths and end the turn. Do not call
-   session to the lower-cost implementation model. Default Codex guidance is
+   `ask_user_question_kandev` (or an equivalent approval prompt) to ask the
-   GPT-5.6 Terra/medium. Do not silently continue on the strong model when the
+   user to approve the package or switch models. The user reviews the files,
-   user has asked for a cost-controlled workflow.
+   switches the main session if desired, and sends a later explicit
-3. **Execution checkpoint — lower-cost model.** In the same conversation, read
+   implementation request. The files may remain `draft`/`pending`; do not wait
-   the approved task file, mark it `in_progress`, implement with `/tdd`, run its
+   for a separate approval marker.
-   exact targeted checks, and mark it `done`. Work sequentially through the
+3. **Execution checkpoint.** After that explicit request, read the
-   plan by default.
+   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
+- Do not continue from the design-package handoff automatically or treat
-  cost. State the recommended switch and wait when the choice materially
+  artifact creation as implementation authorization. Wait for a later explicit
-  affects cost or quality.
+  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.

.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
+1. A prior design turn produced the spec, plan, and current task file, and the
-2. The user explicitly says to skip spec/plan/task creation.
+   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
+existing partial implementation as continuation context, and stop at the
-switch checkpoint. A phase label or generic "implement" directive generated by
+design-package handoff. Do not call `ask_user_question_kandev` or ask the user
-a Kandev workflow is not an explicit opt-out.
+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
+strong-model design package — spec, plan, and task files — before returning
-review or a model switch. Pause after a standalone spec only when the user asks
+control. Do not add an approval/model-switch question at the handoff. Pause
-to review that spec before planning, or when a material open question blocks a
+after a standalone spec only when the user asks to review that spec before
-safe plan.
+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
+planned test commands, and any open risks.
-main conversation to the lower-cost implementation model.
+
+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
+Begin implementation only after that explicit implementation request. Never
-current model. Never infer a successful switch from a model's prose; inspect
+infer a successful model switch from a model's prose; the user's runtime model
-runtime model-usage metadata when confirmation is required.
+choice is authoritative when model confirmation is required.
 
 ## Phase 5: Execute Tasks
 

.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.

.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
+durable artifacts, return a design-package handoff, and end the turn. Do not
-implement and run the task-defined tests in the same conversation. The PR AI
+ask for approval or a model switch; the user reviews the files, changes the
-reviewers provide the semantic gate after PR creation; do not add local QA,
+model if desired, and later asks to implement and run the task-defined tests in
-review, simplify, security, or broad verification gates by default.
+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.

.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
+Use the strongest available model for specs/plans, then return
-lower-cost model before implementation. Plans may mark parallel-safe waves; the
+a design-package handoff and end the turn. Do not ask for approval or a model
-feature and fix skills define task validation and any user-authorized
+switch; the user reviews the files, changes the model if desired, and later
-implementation delegation. Do not create project custom-agent files merely to
+asks to implement. Plans may mark parallel-safe waves; the feature and fix
-route model tiers. Platform-provided explorers remain available.
+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.

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
+At the completed-plan checkpoint, return control with a concise handoff. Do not
-session to a lower-cost implementation model. Detailed feature, fix,
+call `ask_user_question_kandev` (or an equivalent approval prompt) to ask the
-validation, and delegation routing lives in the relevant skills, especially
+user to approve the package or switch models. The user reviews the files,
-`planner-orchestration`.
+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
+production or permanent test changes. End that turn at the design-package
-when approved task artifacts already exist, or when the user explicitly says
+handoff; do not ask for approval or a model switch. A generic implementation
-to skip planning; a generic implementation envelope is not that explicit
+envelope is not an explicit opt-out; the user must either explicitly ask to
-opt-out.
+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