Spec-Driven Development

Spec-Driven Development

Overview

Write a structured specification before writing any code. The spec is the shared source of truth between you and the human engineer — it defines what we're building, why, and how we'll know it's done. Code without a spec is guessing.

When to Use

• Starting a new project or feature
• Requirements are ambiguous or incomplete
• The change touches multiple files or modules
• You're about to make an architectural decision
• The task would take more than 30 minutes to implement

When NOT to use: Single-line fixes, typo corrections, or changes where requirements are unambiguous and self-contained.

The Gated Workflow

Spec-driven development has four phases, preceded by a scope check (Phase 0) that activates only when one request bundles several independently testable capabilities. Do not advance to the next phase until the current one is validated.

SPECIFY ──→ PLAN ──→ TASKS ──→ IMPLEMENT
   │          │        │          │
   ▼          ▼        ▼          ▼
 Human      Human    Human      Human
 reviews    reviews  reviews    reviews

Phase 0: Scope Check

Most requests describe one capability. If this one does, skip this phase and go straight to Specify — Phase 0 exists for the exception, not the rule, and it puts no hierarchy on single-capability features.

Detection. Decompose before specifying when a single requirement bundles several independently testable capabilities:

• The requirement names distinct capabilities with their own consumers or data (e.g. identity, billing, notifications, reporting)
• Acceptance criteria cluster into groups that could ship and be verified separately
• One capability could be cut or replaced without rewriting the others' requirements

Propose a capability map before writing any spec. Small and reviewable — a module table plus a build order, not a project plan:

# Capability Map: [Initiative Name]

| Module id | Responsibility | Depends on |
|---|---|---|
| identity | Accounts, sessions, SSO | — |
| billing | Plans, invoices, payments | identity |
| notifications | Email and webhook fan-out | identity |
| reporting | Usage dashboards | billing, notifications |

Build order: identity → billing, notifications → reporting

• Stable module ids. Kebab-case, chosen once, never renamed mid-initiative. Specs, plans, and downstream commands select work by these ids instead of guessing which spec is active.
• Dependency direction, no cycles. Arrows point one way. If two modules each need the other, they are one module.
• Interfaces live at the boundary. The map records that billing depends on identity; the contract between them belongs in the provider module's spec (see api-and-interface-design for designing it).

The map is gated like every phase. The human reviews module boundaries, dependency direction, and build order before any module spec is written. Getting the map wrong is expensive; reviewing ten lines is not.

Then recurse per module. Run Specify → Plan → Tasks → Implement for each module in dependency order. Each module gets its own spec, scoped to that module's objective, boundaries, and success criteria. Save the approved map at the project root and each module's spec alongside it, named by module id (SPEC-identity.md, SPEC-billing.md) — the map, not filename guessing, is the index of what exists.

Phase 1: Specify

Start with a high-level vision. Ask the human clarifying questions until requirements are concrete.

Surface assumptions immediately. Before writing any spec content, list what you're assuming:

ASSUMPTIONS I'M MAKING:
1. This is a web application (not native mobile)
2. Authentication uses session-based cookies (not JWT)
3. The database is PostgreSQL (based on existing Prisma schema)
4. We're targeting modern browsers only (no IE11)
→ Correct me now or I'll proceed with these.

Don't silently fill in ambiguous requirements. The spec's entire purpose is to surface misunderstandings before code gets written — assumptions are the most dangerous form of misunderstanding.

Write a spec document covering these six core areas:

1. Objective — What are we building and why? Who is the user? What does success look like?

2. Commands — Full executable commands with flags, not just tool names.

   Build: npm run build
   Test: npm test -- --coverage
   Lint: npm run lint --fix
   Dev: npm run dev

3. Project Structure — Where source code lives, where tests go, where docs belong.

   src/           → Application source code
   src/components → React components
   src/lib        → Shared utilities
   tests/         → Unit and integration tests
   e2e/           → End-to-end tests
   docs/          → Documentation

4. Code Style — One real code snippet showing your style beats three paragraphs describing it. Include naming conventions, formatting rules, and examples of good output.

5. Testing Strategy — What framework, where tests live, coverage expectations, which test levels for which concerns.

6. Boundaries — Three-tier system:

   • Always do: Run tests before commits, follow naming conventions, validate inputs
   • Ask first: Database schema changes, adding dependencies, changing CI config
   • Never do: Commit secrets, edit vendor directories, remove failing tests without approval

Spec template:

# Spec: [Project/Feature Name]

## Objective
[What we're building and why. User stories or acceptance criteria.]

## Tech Stack
[Framework, language, key dependencies with versions]

## Commands
[Build, test, lint, dev — full commands]

## Project Structure
[Directory layout with descriptions]

## Code Style
[Example snippet + key conventions]

## Testing Strategy
[Framework, test locations, coverage requirements, test levels]

## Boundaries
- Always: [...]
- Ask first: [...]
- Never: [...]

## Success Criteria
[How we'll know this is done — specific, testable conditions]

## Open Questions
[Anything unresolved that needs human input]

External spec tools: This workflow is format-agnostic. If the project already uses OpenSpec or another specification system, keep that system's artifact format and storage conventions instead of creating a duplicate SPEC.md. This skill owns the clarification, content, and approval gates; the external tool owns how the approved spec is represented.

Reframe instructions as success criteria. When receiving vague requirements, translate them into concrete conditions:

REQUIREMENT: "Make the dashboard faster"

REFRAMED SUCCESS CRITERIA:
- Dashboard LCP < 2.5s on 4G connection
- Initial data load completes in < 500ms
- No layout shift during load (CLS < 0.1)
→ Are these the right targets?

This lets you loop, retry, and problem-solve toward a clear goal rather than guessing what "faster" means.

Stop after writing the spec (CRITICAL). Once the spec is saved:

1. Summarize it and list any Open Questions.
2. Ask the human to approve it or request changes.
3. STOP YOUR TURN IMMEDIATELY. Do NOT start Phase 2, invoke planning-and-task-breakdown, or write code in this turn. Planning starts only after the human approves the spec in a later turn.

Phase 2: Plan

With the validated spec, generate a technical implementation plan:

1. Identify the major components and their dependencies
2. Determine the implementation order (what must be built first)
3. Note risks and mitigation strategies
4. Identify what can be built in parallel vs. what must be sequential
5. Define verification checkpoints between phases

Follow planning-and-task-breakdown for the dependency-graph mapping and vertical-slicing mechanics behind these steps; it is the canonical source. The bullets above are a lightweight summary; if they ever diverge, planning-and-task-breakdown takes precedence.

Output convention: Save the plan to tasks/plan.md and record the task list in the task list target defined by planning-and-task-breakdown (default tasks/todo.md; projects may designate an external tracker instead). Create tasks/ if it does not exist. Downstream commands (/build, etc.) expect these defaults.

The plan should be reviewable: the human should be able to read it and say "yes, that's the right approach" or "no, change X."