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:

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

1. Clarify intent
2. Create or update the spec
3. Create the implementation plan
4. Decompose it into task files
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

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:

1. Read the task, relevant spec and plan sections, and scoped AGENTS.md.
2. Change only that task's status to in_progress.
3. Implement with /tdd; use /e2e and /mobile-parity when applicable.
4. Run the task's exact targeted verification command.
5. 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.