| name | spec-driven-dev |
| description | Guides Claude to follow the spec-driven development pattern — reading from spec/, context/, and CLAUDE.md — when working inside a repository scaffolded with the spec-starter commands. |
Skill: Spec-Driven Development
When working inside a repository that uses the spec-starter layout, follow this pattern at the start of every session.
Repository Layout
project-root/
├── spec/ # Development specifications
├── context/ # User preferences and domain context
├── decisions/ # Architectural decision records
├── iterations/ # Spec version snapshots
├── archive/ # Processed prompt files
└── CLAUDE.md # Project summary and instructions
Reading the Spec
- Look in
spec/ for the latest specification:
- If only
spec/starter.md exists, use that
- If versioned files exist (
v2.md, v3.md, …), use the highest-numbered version
- If unsure, ask the user which version is current
Reading Context
Read all files in context/:
context/index.md is the primary context file- Additional files (e.g.,
context/technology-stack.md) may be present — read them all
Context informs your choices about tools, languages, style, and constraints. It is supplementary; do not surface it unless it is directly relevant to the current task.
Speech-to-Text Awareness
The user's original prompt was likely captured via speech-to-text. When the user provides new input by voice, be alert for:
- Homophones (their/there, to/too, its/it's)
- Misheard technical terms ("Postgres" → "post grace", "OAuth" → "oh auth")
- Missing or incorrect punctuation
Infer the likely intended meaning when obvious; ask for clarification when ambiguous.
Spec Versioning
- Minor clarifications: edit the current spec in place
- Major direction changes: create a new versioned file (
spec/v2.md, spec/v3.md, …)
- Claude Code automatically prefers the highest version number
Decision Tracking
When a significant architectural or technical decision is made, create a record in decisions/ using a date-prefixed filename: YYYY-MM-DD-description.md.
Iteration Snapshots
Before large refactors, snapshot the current spec by copying it to iterations/ with a descriptive name and timestamp, so the project's evolution is traceable.
