Spec Driven Development

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.