Spec Driven Development

---
name: spec-driven-development
description: Creates specs before coding. Use when starting a new project, feature, or significant change and no specification exists yet. Use when requirements are unclear, ambiguous, or only exist as a vague idea.
---

# 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. 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 1: Specify

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

**Ask with a tool, not with text.** When a clarifying question or an open question boils down to a small set of distinct answers (pick-one-of-N, yes/no, "which of these approaches"), ask it with the AskUserQuestion tool so the human can select an answer directly, rather than printing a numbered list and waiting for a freeform reply. This applies to the Phase 1 clarifying questions and to the final "Open Questions" checkpoint before implementation starts. Reserve plain text for questions that genuinely need a freeform answer (e.g. "what should this be called").

**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. Before writing this section, actually read `references/coding-patterns.md` — its five structural patterns (clear main path, external systems behind a boundary, unrepresentable invalid states, decisions separated from actions, useful errors) aren't optional background: check each one against what this feature actually touches, and name the ones that apply as concrete style expectations here, not a footnote to check later.

Also read `references/library-reuse.md` before finalizing Tech Stack and Code Style — it's language-agnostic, naming the idiomatic library per category (date/time, validation, HTTP, auth, ORM, forms, background jobs, and the rest) for whichever language/framework this spec is actually targeting (Node/TS, Python, C#/.NET, Go, and more), not a JS/TS default applied out of habit. Where the feature needs logic in one of that reference's categories, name the specific library for this project's real stack in Tech Stack rather than leaving it to be hand-written during implementation — this is what keeps a senior engineer's default choices visible in the spec instead of silently deferred.

5. **Testing Strategy** — What framework, where tests live, coverage expectations, which test levels for which concerns. **Unit tests are always in scope, non-negotiably** — state the unit-testing framework and where unit tests live even when integration/e2e coverage is lighter; a spec that only discusses higher-level test levels is incomplete.

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

**Naming the spec file.** Save every spec under `specs/<feature-slug>/SPEC.md` in the project's external output location (see `references/external-output-paths.md`) — outside the project's own repo, never a path git in this project tracks or even just ignores. Create the folder if it doesn't exist. A generic root-level `SPEC.md` collides the moment a second feature gets spec'd. Before writing, check whether a spec folder for this feature already exists; if so, confirm with the human whether to update it in place or start a new one (e.g. `specs/<feature-slug>-2/SPEC.md`).

**Spec template:**

```markdown
# 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
[Unit test framework and location (always required), plus any integration/e2e frameworks, 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]
```

**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.

### 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

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."

### Phase 3: Tasks

Break the plan into discrete, implementable tasks:

- Each task should be completable in a single focused session
- Each task has explicit acceptance criteria
- Each task includes a verification step (test, build, manual check)
- Tasks are ordered by dependency, not by perceived importance
- No task should require changing more than ~5 files

**Task template:**
```markdown
- [ ] Task: [Description]
  - Acceptance: [What must be true when done]
  - Verify: [How to confirm — test command, build, manual check]
  - Files: [Which files will be touched]
```

### Phase 4: Implement

Execute tasks one at a time following `skills/incremental-implementation/SKILL.md` (`incremental-implementation`) and `skills/test-driven-development/SKILL.md` (`test-driven-development`). Use `skills/context-engineering/SKILL.md` (`context-engineering`) to load the right spec sections and source files at each step rather than flooding the agent with the entire spec.

## Keeping the Spec Alive

The spec is a living document, not a one-time artifact:

- **Update when decisions change** — If you discover the data model needs to change, update the spec first, then implement.
- **Update when scope changes** — Features added or cut should be reflected in the spec.
- **Keep it at its external path** — the spec lives outside the project's repo (see `references/external-output-paths.md`), not in version control alongside the code.
- **Reference the spec in PRs** — Link back to the spec section that each PR implements.

## Common Rationalizations

| Rationalization | Reality |
|---|---|
| "This is simple, I don't need a spec" | Simple tasks don't need *long* specs, but they still need acceptance criteria. A two-line spec is fine. |
| "I'll write the spec after I code it" | That's documentation, not specification. The spec's value is in forcing clarity *before* code. |
| "The spec will slow us down" | A 15-minute spec prevents hours of rework. Waterfall in 15 minutes beats debugging in 15 hours. |
| "Requirements will change anyway" | That's why the spec is a living document. An outdated spec is still better than no spec. |
| "The user knows what they want" | Even clear requests have implicit assumptions. The spec surfaces those assumptions. |
| "`references/coding-patterns.md` is just background reading for Code Style" | It's what Code Style is supposed to apply, not optional context — read it and name which patterns this feature's boundaries/decisions actually need. |
| "Tech Stack just needs the framework, libraries are an implementation detail" | Naming the validation/date/HTTP/auth library in Tech Stack is exactly what `references/library-reuse.md` is for — it's a design decision, not a detail to leave for whoever writes the code. |

## Red Flags

- Starting to write code without any written requirements
- Asking "should I just start building?" before clarifying what "done" means
- Implementing features not mentioned in any spec or task list
- Making architectural decisions without documenting them
- Skipping the spec because "it's obvious what to build"
- Code Style written without reading `references/coding-patterns.md`, or none of its patterns named even when the feature clearly touches an external system, a decision-heavy flow, or error handling
- Tech Stack describing logic in prose for a category `references/library-reuse.md` covers (date math, validation, auth, HTTP retries, etc.) with no library named
- A library recommended from the wrong ecosystem (e.g. a JS/TS default named for a Python or C# spec) instead of the one idiomatic to this project's actual language/framework

## Verification

Before proceeding to implementation, confirm:

- [ ] The spec covers all six core areas
- [ ] The human has reviewed and approved the spec
- [ ] Success criteria are specific and testable
- [ ] Boundaries (Always/Ask First/Never) are defined
- [ ] `references/coding-patterns.md` was actually read, with the patterns that genuinely apply to this feature named in Code Style
- [ ] `references/library-reuse.md` was actually read, with a specific library named in Tech Stack for every category it covers that this feature touches
- [ ] The spec is saved to `specs/<feature-slug>/SPEC.md` in the project's external output location (see `references/external-output-paths.md`), not a path inside the project's own repo