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

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

Feature-Level

Guidelines

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

• 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 .artifacts/research/
• Archive generates: docs/features/{name}.md (no ID)

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