spec-driven-dev

Spec-Driven Development

A structured workflow that takes features from idea to implementation through four phases: Specify → Plan → Review → Build.

When to Activate

• User wants to build a new feature or significant change
• User says /spec-dev or "let's build this properly"
• User wants a structured approach to development
• A task is complex enough to benefit from upfront planning

Why This Workflow

Most AI coding goes wrong in the same way: jumping straight to code without understanding what to build, then burning context fixing design mistakes that planning would have caught.

This workflow prevents that by:

1. Specifying what to build before writing any code
2. Planning the implementation as testable stories
3. Reviewing the plan with a fresh perspective (catches 80% of design issues)
4. Building test-first so you know when you're done

Instructions

Phase 1: Specify (/spec-dev spec)

Create a clear specification document.

Gather requirements:

• What problem does this solve?
• Who uses it and how?
• What are the inputs, outputs, and edge cases?
• What are the constraints (performance, compatibility, security)?
• What does "done" look like?

Write the spec:

Create specs/{feature-name}.md:

# Feature: {Name}

## Problem
[What problem does this solve and why does it matter?]

## Solution
[High-level description of the approach]

## Requirements

### Functional
- [ ] [Specific, testable requirement]
- [ ] [Another requirement]

### Non-Functional
- [ ] [Performance target, if any]
- [ ] [Security constraints, if any]

## User Stories
- As a [role], I want [action] so that [benefit]

## Edge Cases
- [What happens when X?]
- [What about empty/null/concurrent inputs?]

## Out of Scope
- [Explicitly list what this does NOT include]

## Open Questions
- [Anything that needs clarification before building]

Output: Confirm the spec with the user. Resolve any open questions before proceeding.

Phase 2: Plan (/spec-dev plan)