Spec Driven Development

Spec-Driven Development

Spec-Driven Development (SDD) treats the specification as the primary artifact. Instead of jumping from a vague idea straight to code, you express intent in product terms, let the workflow turn that intent into structured and reviewable documents, and only then plan, decompose, and implement. The spec and its supporting artifacts live in source control next to the code they describe.

This page documents the loop exactly as it was used to build this repository.

The loop

flowchart TD
    C[Constitution\n.specify/memory/constitution.md] --> S
    S[/speckit.specify\nspec.md/] --> CL[/speckit.clarify\nresolve open questions/]
    CL --> P[/speckit.plan\nplan.md + research + data-model + contracts + quickstart/]
    P --> T[/speckit.tasks\ntasks.md/]
    T --> I[/speckit.implement\napplication code/]
    I --> IT{Iterate?}
    IT -->|new feature or change| S
    IT -->|done| DONE[Validated static site]

Loading

Step by step

0. Constitution

The constitution captures the rules that no feature is allowed to break. It is written once and amended deliberately. Every later phase is checked against it, including an explicit Constitution Check gate inside the plan. See Project Constitution.

1. Specify

/speckit.specify Describe the feature in product terms

Output: specs/<feature>/spec.md. The spec is written for a reader who cares about what and why, not how. For this project it captures three prioritized user stories (featured episode, episode catalog, about and FAQ), seventeen functional requirements, measurable success criteria, edge cases, and explicit assumptions.

A good spec is testable. Note how the requirements read as checkable statements: "the episodes page MUST display exactly 20 mocked episodes", "the featured episode MUST be included in the 20 and marked as featured".

2. Clarify

/speckit.clarify

Resolve open questions directly when the reasonable default is clear, and record the decision. This is where ambiguity is removed before it becomes expensive. The requirements checklist is updated so the spec is ready for planning.

3. Plan

/speckit.plan Describe the technical approach and constraints

Output: a set of design documents under specs/<feature>/:

Artifact	Purpose
plan.md	Technical context, constitution check, and project structure
research.md	Technology choices and the rationale behind them
data-model.md	Entities and their fields (Episode, FAQ Item, Podcast Profile)
contracts/	Route or API contracts (here, the four static routes)
quickstart.md	The exact commands to build, run, and verify

The plan begins with a Constitution Check gate that must pass before design proceeds, and is re-checked after the design is fleshed out.

4. Tasks

/speckit.tasks

Output: tasks.md, a dependency-ordered checklist grouped by user story so work can proceed in small, independently testable slices. This project produced 48 tasks across six phases: setup, foundational shell, three user-story phases, and a polish and validation phase. Tasks marked [P] can run in parallel because they touch different files.

5. Implement

/speckit.implement

The agent works through tasks.md, marking each task complete as it goes, and validates each slice against the plan and constitution. The implementation for this site produced the App Router routes, shared components, typed content modules, the CSS design system, and the Playwright test suites, with the static build and accessibility checks passing.

6. Iterate

Repeat the loop for new features or significant changes. The rule is simple: update the spec and plan before changing implementation behavior. The spec stays the source of truth, not the code.

What makes this different from "just writing a design doc"

• The artifacts are structured and executable, not prose that rots in a wiki. tasks.md is consumed directly by the implementation step.
• The artifacts are versioned with the code. A pull request can change the spec, the plan, and the implementation together and review them as one unit.
• A constitution gate enforces guardrails automatically at planning time.
• The AI agent does the heavy lifting of expanding intent into a plan and tasks, while the human stays in control of intent and review.

See also

• Why Spec-Driven Development for the motivation
• Methodology Comparison for how SDD compares to classic Azure DevOps planning and the HVE-core RPI flow