chore: defer planning approval to next turn (#2170)
This commit is contained in:
Carlos Florêncio
+17
-12
@@ -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.
|
||||
|
||||
@@ -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,
|
||||
|
||||
@@ -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/<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.
|
||||
|
||||
@@ -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.
|
||||
|
||||
@@ -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
|
||||
|
||||
|
||||
@@ -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.
|
||||
|
||||
@@ -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.
|
||||
|
||||
@@ -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.
|
||||
|
||||
@@ -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
|
||||
|
||||
Reference in New Issue
Block a user