Spec-Driven Development

Overview

SDD makes specifications the source of truth — code serves specs, not the other way around. Instead of prompting an AI with vague descriptions and hoping for the right output, you define precise specifications first, then let AI generate code strictly constrained by those specs.

Core principle: "When specifications drive implementation, pivots become systematic regenerations rather than manual rewrites."

Why it works: without a spec, AI makes thousands of micro-decisions silently. With a spec, those decisions are made by you — explicitly, before any code is written.

Spec Levels

Start with spec-first. Move to spec-anchored when the feature stabilizes.

Quick Start

New to SDD? Four steps to your first spec-driven feature:

1. Create your constitution (once per project): /sdd:init — run this first, before any feature specs

2. Surface AI assumptions (before specifying): Ask the AI to list its implicit assumptions about roles, permissions, error behavior, and scope — then correct them before any AC is written

3. Specify your first feature: /sdd:specify [brief description] — generates spec.md with MoSCoW-prioritized ACs

4. Follow the gates: Clarify → Plan → Tasks → Implement → Validate Human approval required at each gate before the next phase

For detailed step-by-step instructions, see references/workflow-phases.md.

When to Use

Symptoms that signal SDD is needed:

• AI ignores constraints or generates code that doesn't match requirements
• Same prompt produces different implementations across sessions
• Requirements are complex with multiple stakeholders or cross-cutting concerns
• Team needs shared technical understanding before writing code
• Previous "just build it" attempts produced wrong architecture
• Feature touches auth, data model, API contracts, or database schema

Skip SDD for:

• One-line fixes, typos, trivial bugs
• Disposable prototypes where requirements will immediately change
• Solo exploration spikes lasting less than a day

Key Practice: Reframe Vague Requirements

Before writing any AC, convert vague requirements into measurable targets:

If you cannot write a passing test for an AC, the AC is not concrete enough.

Directory Structure

constitution.md              # Project-level: immutable principles (one per project)

specs/
  [feature-branch-name]/
    spec.md              # Requirements — WHAT and WHY (MoSCoW prioritized)
    plan.md              # Implementation strategy — HOW
    data-model.md        # Data entities, relationships, schemas
    contracts/           # API endpoints, events, interface definitions (LOCKED after Phase 2 approval)
    tasks.md             # Atomic executable task list
    research.md          # Optional: context and alternatives considered
    decision_log.md      # Optional: rationale for key decisions
  archive/               # Completed feature specs (move here after feature ships)

Phase 0 — Constitution (one-time per project)

Invoke: /sdd:init

Creates constitution.md at the project root — a versioned document of immutable constraints that applies to every feature. AI agents are strictly forbidden from violating it.

Contains:

• Coding standards and architecture principles
• Technology stack decisions (languages, frameworks, libraries)
• Security constraints (authentication model, input validation rules, CWE baseline)
• Naming conventions, file structure rules
• Explicit anti-patterns banned from this codebase

When to update: Only when a fundamental project decision changes. Not per-feature.

See references/artifact-templates.md for the constitution.md template.

5-Phase Workflow (per feature)

Phase 1 — Specify

Invoke: /sdd:specify [feature description]

Surface assumptions first — before generating spec.md, run the Assumptions Surface Prompt (see references/prompt-patterns.md). This forces the AI to make its implicit assumptions about roles, permissions, error behavior, and scope explicit for human review before they get baked into acceptance criteria.

Creates specs/[feature]/spec.md containing:

• Feature overview (1–2 sentences, non-technical)
• User stories: As a [role] I want [goal] so that [benefit]
• Feature-level AI behavior constraints (Boundaries: Always do / Ask first / Never do)
• Acceptance criteria (Given/When/Then) with MoSCoW priority: [MUST] / [SHOULD] / [COULD] / [WONT]
• Explicit out-of-scope boundaries
• Open questions marked [NEEDS CLARIFICATION]

Clarify step — before Gate 1, run the clarify prompts (see references/prompt-patterns.md):

• Resolve every [NEEDS CLARIFICATION] item
• Add ACs for all identified edge cases and error scenarios
• Run automated spec validation (vague terms, missing error coverage, untestable ACs)

Human gate — review before Phase 2:

• Every [MUST] AC is independently testable
• No implementation details in the spec (no "use PostgreSQL", no function names)
• No [NEEDS CLARIFICATION] items remain open
• Scope boundaries explicitly listed
• Error and edge case ACs exist (not just happy path)
• Spec passes automated validation (no vague terms like "fast", "secure", "works correctly")

See references/artifact-templates.md for the spec.md template.

Phase 2 — Plan

Invoke: /sdd:plan (reads spec.md + constitution.md)

Creates in specs/[feature]/:

• plan.md — Technical architecture, component breakdown, technology choices, tradeoffs, risks
• data-model.md — Entities, fields, relationships, constraints, indexes
• contracts/ — API endpoint definitions, request/response schemas, error codes, events

If a research.md exists (pre-generated via parallel subagents before Phase 1), /sdd:plan reads it as additional context. It is not generated by this command.

Human gate — review before Phase 3:

• Plan is traceable: every [MUST] AC maps to at least one component
• Plan respects all constraints in constitution.md
• Data model covers all entities mentioned in spec
• API contracts are complete (inputs, outputs, all error codes)
• Migrations defined for any database schema changes (in data-model.md)
• Risks identified with mitigations for each High-impact item
• No unnecessary abstractions (use framework features directly)
• Technology choices use existing stack unless justified

See references/artifact-templates.md for templates.

Phase 3 — Tasks

Invoke: /sdd:tasks (reads plan.md + contracts/)

Creates specs/[feature]/tasks.md:

• Atomic tasks — each corresponds to a single PR or commit
• Explicit dependencies between tasks
• Parallelizable tasks marked [P]
• Each implementation task paired with a test task (test-first)
• Complexity estimate per task: S / M / L

Human gate — review before Phase 4:

• Tasks are small enough for a single AI session (~30–60 min of work)
• Test tasks appear before their implementation counterparts
• No task modifies more than 3 files (split if so)
• Dependencies form a valid DAG (no cy