Spec-Driven Development

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

Workflow

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

Project Structure

.artifacts/
├── project/
│   ├── PROJECT.md          # Vision, goals, constraints
│   ├── ROADMAP.md          # Planned features, milestones
│   └── CHANGELOG.md        # Feature implementation history
├── 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

Templates

Context	Template
Project initialization	PROJECT.md
Roadmap	ROADMAP.md
Feature changelog	CHANGELOG.md
Feature spec	spec.md
Technical plan	plan.md
Task breakdown	tasks.md
Archive document	archive.md
Codebase exploration	exploration.md
Research cache	research.md

Context Loading Strategy

Base load (~15k tokens):

• PROJECT.md (context)
• 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

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	tasks.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
Status workflow, when to update status	status-workflow.md

Cross-References

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

DO:

• Separate content by purpose: spec=WHAT, plan=HOW, tasks=WHEN
• Follow status flow: draft -> ready -> in-progress -> to-review -> done -> archived
• Use sequential Feature IDs (001, 002)
• Reuse research cache across features (.artifacts/research/)
• Archive to docs/features/{name}.md (without ID prefix)

DON'T:

• Reuse Feature IDs from previous features
• Mix spec, plan, and task content in a single file
• Skip status transitions (e.g., jumping from draft to done)
• Create feature-specific research files outside .artifacts/research/

Error Handling

• No .artifacts/: 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