| name | spec-driven-development |
| 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
Use this workflow for non-trivial features and behavior-changing fixes. The
user-started primary conversation performs every phase by default. Plans may
describe parallel work, but subagents are used only when the user explicitly
authorizes them after selecting the implementation model.
Core Flow
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
from intent to code unless the user explicitly opts out of this workflow.
Prompt-Precedence Gate
Treat workflow-generated envelopes such as [IMPROVE PHASE], "implement the
requested change", Red-Green-Refactor checklists, verification commands, and
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:
- A prior design turn produced the spec, plan, and current task file, and the
user now explicitly asks to implement them; or
- The request references an existing reviewed spec, plan, and current task
file; or
- 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
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 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
Keep a visible task list and mark each phase as it completes:
- Clarify intent
- Create or update the spec
- Create the implementation plan
- Decompose it into task files
- End the design turn and wait for the user's explicit implementation request
- Execute tasks with TDD and targeted checks (sequential by default)
- Open PR, address CI/review findings, record, and summarize
Phases 1–4: Design On The Strong Model
Use /interview-me only when the request is underspecified. Create or update:
docs/specs/<slug>/spec.md through /spec for the durable product behavior.docs/plans/<slug>/plan.md through /plan for the technical sequence.docs/plans/<slug>/task-<NN>-<short-slug>.md for each independently
actionable implementation step.
The spec must cover relevant scenarios, contracts, permissions, failures, and
persistence guarantees. The plan must name likely files, dependency order,
tests, E2E coverage where applicable, risks, and exact verification commands.
Task files are the handoff between model tiers. Each must contain:
- frontmatter:
id, title, status: pending, wave, depends_on, plan,
and spec;
- 1–3 concrete acceptance conditions;
- exact targeted verification command(s);
- specific likely files and relevant spec/plan inputs;
- dependencies and risks.
Task files must not name a worker role or model tier. They may be grouped into
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.
Design-Package Handoff
Before any implementation, report the spec path, plan path, task-file list,
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:
- GPT-5.6 Sol/high for clarification, codebase investigation, specs, plans, and
high-risk design.
- 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.
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
For each task, in dependency order:
- Read the task, relevant spec and plan sections, and scoped
AGENTS.md.
- Change only that task's status to
in_progress.
- Implement with
/tdd; use /e2e and /mobile-parity when applicable.
- Run the task's exact targeted verification command.
- Update its status to
done and update the corresponding plan.md status.
If the user explicitly asks to implement with subagents, launch only
parallel-safe tasks in the requested wave. Use native delegation with no
full-history context fork, give each child the task-file path plus its owned
files and exact check, and keep shared-plan status updates in the main session.
The children use the implementation model active in the user-selected main
session; confirm that through runtime usage metadata before accepting results.
If work reveals a new architecture, public contract, migration/persistence
boundary, or high-impact security decision, stop and ask the user whether to
switch back to the strong model before proceeding. Use /record if the decision
is durable.
Phase 6: Open The PR And Use Its Review Gates
After all tasks pass their exact targeted checks, commit through /commit,
push, and open the PR. Do not automatically run /simplify, /qa,
/code-review, security review, or broad /verify before opening it.
The two configured PR AI reviewers are the semantic-review gate. Use
/pr-fixup only for a CI failure or actionable reviewer finding. A fix reruns
the task's relevant targeted check and updates its task/plan status; do not run
a broad local suite unless the user explicitly asks.
Stop Conditions
Stop and ask the user when the spec and codebase disagree, a task needs a
materially new design, a model-tier escalation is required, or the same
verification failure repeats after three focused attempts.
Final Report
Report the spec and plan paths, task statuses, model checkpoints used, changed
files, commands and results, user-authorized subagents (if any), semantic-review
evidence, and known risks.
