Spec-Driven Development

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

Workflow

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

Project Structure

.artifacts/
├── features/
│   └── {ID}-{name}/
│       ├── spec.md         # WHAT: Requirements
│       ├── plan.md         # HOW: Architecture
│       ├── tasks.md        # WHEN: Tasks
│       └── designs/        # Visual references (screenshots, mockups, wireframes)
└── research/               # Research cache (lazy)
    └── {topic}.md

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

Optional context (generated by project-index skill):

.agents/
├── project.md              # Project context
└── codebase/               # Codebase analysis

Note: .agents/ is optional. If it exists, spec-driven uses and updates it. If not, all context stays within the feature artifacts.

Templates

Context	Template
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):

• .agents/project.md (context, if exists)
• Current feature spec.md

On-demand:

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

Never simultaneous:

• Multiple feature specs
• Archived features

Triggers

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

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)
• Consume .agents/ for project context and codebase info (optional - use if exists)
• Update .agents/codebase/ with new discoveries during plan phase (if it exists)

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/
• Generate .agents/ content (that's project-index's responsibility)

Error Handling

• No .artifacts/: Create it (features/ and research/ are created on demand)
• 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