name

spec-driven-dev

description

Spec-driven development methodology that transforms feature requests into structured documentation before coding. Use when users want to (1) plan a new software project or feature, (2) create requirements/design/tasks documentation, (3) follow a structured development workflow, (4) break down complex features into trackable tasks. Triggers include phrases like "let's plan this properly", "spec-driven", "create requirements", "design document", "task breakdown", "before we start coding".

Spec-Driven Development

Transform high-level goals into structured, traceable documentation before writing code.

Workflow Overview

Feature Request → Requirements → Design → Tasks → Implementation
                     ↓              ↓        ↓
              requirements.md  design.md  tasks.md

Three-Phase Process

Phase 1: Requirements Analysis

Convert goals into user stories with EARS acceptance criteria.

Output: requirements.md

Product overview (vision, constraints, target users)
User stories grouped by Epic
Acceptance criteria using EARS notation
Non-functional requirements
Out of scope items

Phase 2: Technical Design

Create architecture based on approved requirements.

Output: design.md

System architecture diagram
Technology stack decisions
Data models and schemas
API specifications
Component designs
Security and deployment considerations

Phase 3: Task Implementation

Generate ordered, dependency-aware tasks linked to requirements.

Output: tasks.md

Tasks grouped by phase
Each task linked to requirement IDs
Time estimates
Status tracking (🔴🟡🟢🔵)
Critical path identification
Dependency mapping

EARS Notation Reference

Type	Pattern	Example
Ubiquitous	The system SHALL...	The system SHALL encrypt all data at rest
Event-Driven	WHEN [trigger], THEN...	WHEN user clicks Save, THEN system SHALL persist data
State-Driven	WHILE [state], the system SHALL...	WHILE in offline mode, the system SHALL queue requests
Optional	IF [condition], THEN...	IF user has premium, THEN system SHALL enable feature X
Unwanted	IF [condition], THEN... SHALL NOT	IF input invalid, THEN system SHALL NOT proceed

Execution Guidelines

Start with requirements - Never skip to design without clear requirements
Validate before proceeding - Get user confirmation at each phase
Link everything - Tasks → Requirements → User Stories
Keep documents separate - Don't merge into single monolithic PRD
Iterate - Documents evolve as understanding deepens

Templates

Detailed templates for each document:

references/requirements-template.md - Full requirements structure
references/design-template.md - Architecture and API patterns
references/tasks-template.md - Task breakdown format

Quick Start

When user requests a new feature/project:

Ask clarifying questions about scope and constraints
Read references/requirements-template.md
Draft requirements.md with user stories
Review with user, iterate
Read references/design-template.md
Draft design.md with architecture
Review with user, iterate
Read references/tasks-template.md
Generate tasks.md with ordered implementation plan
Begin implementation phase by phase. When work at the phase level is completed, make sure to verify that all tasks for that item have been perfectly executed and test them