Spec-Driven Development (SDD)

A methodology and Cursor-powered workflow for building software specification-first — ensuring every line of code traces back to a documented requirement.

Why Spec-Driven Development?

• Clarity precedes code — Define goals, requirements, and architecture before implementation
• Traceability — Every feature and task maps to PRD requirements
• Context efficiency — Lightweight indexes keep AI sessions focused and token-efficient
• Plan-first implementation — Mandatory planning before coding catches issues early

---

Quick Start

# 1. Initialize your project (5–10 questions about goals, users, constraints)
/init-project

# 2. Generate specifications (PRD + architecture)
/create-spec

# 3. Plan features
/create-plan

# 4. Create feature folders
/create-features

# 5. Create tasks for a feature
/create-tasks F1.1

# 6. Implement (plan → approve → code)
/execute-task T1.1.1

---

Workflow Overview

Phase	Command	Output
Discovery	/init-project	spec/discovery.md
Personas (optional)	/create-persona	spec/personas.md
Specification	/create-spec	spec/PRD.md, spec/architecture.md
Planning	/create-plan	spec/plan.md
Features	/create-features	spec/features/
Tasks	/create-tasks	spec/features/F[x.y]-[slug]/tasks.md
Implementation	/execute-task	Code + updated tasks.md
Session end	/sync-state	spec/progress.md

Anytime:

• /revise — Update any artifact with cascading changes
• /verify — Audit specification integrity

---

Command Reference

Command	Purpose
/init-project	Define project goals and context
/create-persona	Define reusable user personas
/create-spec	Generate PRD and architecture
/create-plan	Plan features before building
/create-features	Create feature folders (all or selective)
/create-tasks	Create tasks for one feature
/execute-task	Plan and execute tasks (plan mode mandatory)
/revise	Update any artifact with change propagation
/verify	Check specification integrity
/add-rule	Create custom AI rules
/add-skill	Create reusable skills
/sync-state	Save session progress

---

Workflow Diagram

/init-project ──► discovery.md
       │
       └──► /create-spec ──► PRD.md + architecture.md
                  │
                  ├──► /create-plan ──► plan.md
                  │
                  └──► /create-features ──► spec/features/
                           │
                           └──► /create-tasks ──► tasks.md
                                    │
                                    └──► /execute-task ──► Implementation

---

Implementation Flow: /execute-task

/execute-task enforces a plan-first approach — you cannot skip ahead to coding:

1. Select target — Single task, feature, or "next"
2. Load context — _index.md → target feature only (minimal context)
3. Plan mode — Execution plan, approach, acceptance criteria, risks
4. Approval — Approve, revise, or cancel
5. Act mode — Implement per approved plan
6. Report — Update tasks.md, suggest next task

---

The _index.md Pattern

The framework uses lightweight index files to minimize token usage:

• Always read spec/features/_index.md first
• Identify the relevant feature from the registry
• Load only that feature's folder (feature.md + tasks.md)
• Never load all feature folders at once

Question	Load
"What features exist?"	_index.md only
"Work on login"	_index.md → F1.2-user-login/
"Task T1.2.3?"	_index.md → F1.2-[slug]/tasks.md

---

Project Structure (Generated)

spec/
├── discovery.md          # From /init-project
├── personas.md           # From /create-persona (optional)
├── PRD.md                # From /create-spec
├── architecture.md       # From /create-spec
├── plan.md               # From /create-plan
├── progress.md           # From /sync-state
├── references/           # Shared mockups, diagrams (optional)
└── features/
    ├── _index.md         # Feature registry (read first!)
    ├── F1.1-user-registration/
    │   ├── feature.md
    │   ├── tasks.md
    │   └── references/
    └── ...

---

Framework vs Project Files

Copy these to start new projects:

• Agent.md
• workflow.md
• .cursor/ (commands, rules, skills)

Generated per-project:

• spec/ folder (all specification documents)

---

Best Practices

1. Always start with specs — Run /init-project and /create-spec before coding
2. Use /execute-task for implementation — Enforces plan mode before act mode
3. Keep tasks updated — Mark complete immediately in tasks.md
4. Verify periodically — Run /verify after major changes
5. Sync regularly — Run /sync-state at natural breakpoints

---

Full Documentation

See workflow.md for the complete step-by-step guide, including:

• Phase-by-phase walkthrough
• Auto-generated rules and skills
• Change propagation with /revise
• Integrity checks with /verify
• Troubleshooting
• Reference materials

---

Using This Framework

Copy this entire project (or clone it) as a starting template for new work. The .cursor/ folder contains commands and rules that enforce the spec-driven workflow. Run /init-project in your new project to begin.