Spec-Driven Development

Use this workflow for non-trivial features and behavior-changing fixes. The user-started primary conversation performs every phase by default. Subagents require explicit user authorization.

Core flow

Intent -> Requirements -> System design -> Plan + work orders -> Design-package handoff -> Explicit implementation request -> TDD implementation -> PR review -> Report

Do not replace durable artifacts with chat-only notes. Do not skip from intent to code unless the user explicitly opts out.

Prompt-precedence gate

Before you edit production or permanent test files, make sure that one condition is true:

1. A prior design turn produced the requirements, system design, plan, and current work order. The user now explicitly asks to implement them.
2. The request references existing reviewed specifications, a plan, and the current work order.
3. The user explicitly says to skip specification, plan, and work-order creation.

Workflow envelopes, phase labels, TDD lists, and generic implementation prompts do not satisfy this gate.

If no condition is true, create or update the design package. Record any partial implementation as continuation context. Stop at the design-package handoff.

When the user asks for feature planning, complete the full design package before you return control. Stop after requirements only when the user requests a requirements review or a material question blocks safe design.

Phase 0: Track the work

Keep a visible task list:

1. Clarify intent.
2. Create or update requirements.
3. Create or update the system design.
4. Create the plan and work orders.
5. End the design turn.
6. Execute work orders with TDD after an explicit implementation request.
7. Open the PR, address valid findings, record changes, and report.

When task-plan MCP tools are available, use the Kandev task plan for live phase progress and update it after each completed design phase. Keep docs/plans/<initiative>/plan.md and its work orders as the durable implementation package; neither plan replaces the other.

Phases 1 to 4: Design

Run the /interview-me assumption check before drafting the package. Reuse confirmed choices across phases; ask only about material unresolved decisions. For large uncertain initiatives, use its optional decision-mapping reference before creating detailed work orders. Continue the package once blockers resolve.

Run the /spec ownership gate before you choose paths. Search adjacent systems for the same capability. Choose the owner from the durable contract, not from backend or frontend implementation layers. If a feature has a UI, include its observable UI outcomes and frontend design in the feature owner's artifacts. Create a separate UI artifact only for an independent reusable UI contract.

Create or update:

• docs/specs/<system>/requirements/<capability>.md through /spec.
• docs/specs/<system>/system-design/<capability>.md through /spec.
• docs/plans/<initiative>/plan.md through /plan.
• docs/plans/<initiative>/task-<NN>-<short-slug>.md through /plan.

During migration, use a legacy specification only when no new requirement or system design replaces it.

Requirements define stable REQ-* and AC-* IDs. System designs map technical behavior to those IDs. Plans define delivery order. Work orders define one implementation result and its verification.

Keep one vertical requirement/design pair for one cohesive outcome. Work orders can separate implementation boundaries after the specification has one owner.

Each work order must contain:

• Frontmatter with id, title, status, wave, depends_on, plan, requirements, acceptance_criteria, and system_design.
• A summary, scope, and exclusions.
• One to three implementation acceptance conditions.
• Exact targeted verification commands.
• Specific likely files, dependencies, and risks.

Work orders do not name a worker role or model tier. Waves can identify parallel-safe candidates. They do not authorize subagents.

For rendered UI changes, include ASCII previews in the plan and relevant UI work orders through /plan. Follow the shared contract in docs/specs/guide/plans-and-work-orders.md#ascii-ui-previews.

Design-package handoff

Before implementation, report:

• Requirement documents and IDs.
• System-design paths.
• The plan and work-order paths.
• Dependency order and exact verification commands.
• Open risks and exclusions.
• For UI changes, a compact inline ASCII preview of the proposed UI, with a distinct phone view when composition differs, plus links to the full previews.

Then end the turn. Do not ask the user to approve the package or switch models. The user reviews the files and sends a later implementation request.

Recommended Codex route:

• GPT-5.6 Sol/high for intent, investigation, specifications, plans, and high-risk design.
• GPT-5.6 Terra/medium for implementation, TDD, and integration.
• GPT-5.6 Luna/low for short and mechanical read-only work.

The user controls model selection. Do not infer a model change from prose.

Phase 5: Execute work orders

For each work order, in dependency order:

1. Read the work order, requirements, system design, plan, and scoped AGENTS.md.
2. Change only that work order to in_progress.
3. Implement with /tdd. Use /e2e and /mobile-parity when applicable.
4. Run the exact targeted verification commands.
5. After implementation and targeted checks pass, change only the current work order to done.
6. After every linked work order passes, verify the implementation still matches each paired requirement and system design. If it does, promote each paired draft requirement to active and each paired draft system design to current, then change the plan to implemented. Record spec lifecycle in spec frontmatter and delivery status in plans and work orders; docs/specs/INDEX.md is a static entry page, not a per-spec delivery catalog. Update a system README only when its boundary or migration record changed. If implementation diverged or an open design issue remains, do not promote unresolved draft specs or mark the plan implemented; report the mismatch.

If the user authorizes subagents, launch only parallel-safe work orders in the requested wave. Use native delegation with no full-history fork. Give each child the work-order path, owned files, dependencies, and exact command.

If work needs a new architecture, public contract, persistence boundary, or high-impact security decision, stop and request a strong-model design pass. Use /record for a durable decision.

Phase 6: Open the PR

After all work-order checks pass, request explicit user authorization before running /commit, /push, or /pr. Run only the operations the user authorizes. Do not add automatic local simplify, QA, broad review, security review, or /verify work.

The configured PR reviewers are the semantic-review gate. Use /pr-fixup only for a CI error or an actionable reviewer finding. Run the affected work-order checks after a correction.

Stop conditions

Stop and ask the user when specifications and code disagree, implementation needs a material new design, a model escalation is necessary, or the same check fails after three focused attempts.

Final report

Report requirement IDs, system-design and plan paths, work-order statuses, model checkpoints, changed files, commands and results, user-authorized subagents, PR-review evidence, and known risks.