Spec-Driven Development

Name: spec-driven
Rating: 78
Author: adeonir

Structured development workflow: Initialize -> Plan -> Tasks -> Implement+Validate.

Workflow

code

initialize --> plan --> tasks --> implement --> validate --> archive

Project Structure

code

.specs/
├── project/
│   ├── PROJECT.md          # Vision, goals, constraints
│   ├── ROADMAP.md          # Planned features, milestones
│   ├── CHANGELOG.md        # Feature implementation history
│   └── STATE.md            # Persistent memory (decisions, blockers)
├── codebase/               # Brownfield analysis (optional)
│   ├── STACK.md
│   ├── ARCHITECTURE.md
│   ├── CONVENTIONS.md
│   ├── STRUCTURE.md
│   ├── TESTING.md
│   └── INTEGRATIONS.md
├── research/               # Research cache (optional)
│   └── {topic}.md
└── features/
    └── {ID}-{name}/
        ├── spec.md         # WHAT: Requirements
        ├── plan.md         # HOW: Architecture
        └── tasks.md        # WHEN: Tasks

docs/
└── features/
    └── {name}.md           # Consolidated implementation

Context Loading Strategy

Base load (~15k tokens):

•PROJECT.md (context)
•STATE.md (persistent memory)
•Current feature spec.md

On-demand:

•codebase/*.md (brownfield)
•plan.md (implementing)
•tasks.md (executing)
•research/*.md (new technologies)

Never simultaneous:

•Multiple feature specs
•Archived features

Triggers

Project-Level

Trigger Pattern	Reference
Initialize project, setup project	project-init.md
Create roadmap, plan features	roadmap.md
Map codebase, analyze codebase	codebase-mapping.md
Record decision, log blocker	session-state.md

Feature-Level

Trigger Pattern	Reference
Create new feature, new feature	initialize.md (greenfield)
Modify feature, improve feature	initialize.md (brownfield)
Create technical plan	plan.md
Research technology, cache research	research.md
Create tasks	tasks.md
Implement task	implement.md
Validate	validate.md
Archive	archive.md
List features, show status	status-specs.md

Guidelines

Trigger Pattern	Reference
How to write specs	spec-writing.md
How to decompose tasks	task-decomposition.md
Codebase exploration	codebase-exploration.md
Research patterns	research.md
Baseline discovery	baseline-discovery.md
Extract from PRD/docs	doc-extraction.md
Coding principles	coding-principles.md

Cross-References

code

project-init.md ----> roadmap.md
project-init.md ----> codebase-mapping.md
initialize.md ------> plan.md (when spec complete)
plan.md ------------> tasks.md
plan.md ------------> research.md (if new tech)
tasks.md -----------> implement.md
implement.md -------> coding-principles.md (loaded before coding)
implement.md -------> validate.md
validate.md --------> implement.md (if issues)
validate.md --------> archive.md (if passed)

Guidelines

•Content separation: spec=WHAT, plan=HOW, tasks=WHEN
•Status flow: draft -> ready -> in-progress -> to-review -> done -> archived
•Feature IDs: sequential (001, 002), never reused
•Research cache: Reusable across features in .specs/research/
•STATE.md: Populated from persistent storage if available
•Archive generates: docs/features/{name}.md (no ID)

Error Handling

•No .specs/: Suggest initialize project first
•Spec not found: List available features
•Open questions blocking architecture: Resolve before planning
•Plan not found: Suggest plan before tasks
•Tasks not found: Suggest tasks before implement