spec-driven-dev

# Spec-Driven Development

Manage complex tasks through structured specifications that persist across sessions.

## Quick Start

```
NEW SPEC:   spec new {name} → edit spec.md → plan.md → tasks.yaml
RESUME:     spec status → spec context {spec} --level min → implement
BLOCKED:    AskUserQuestion (decisions) | Explore agent (context)
COMPLETE:   spec status → spec archive {spec}
```

## Session Entry

| Situation | Action |
|-----------|--------|
| First time on spec | `spec context {spec} --level full` |
| Familiar, continuing | `spec context {spec} --level min` |
| Multiple specs active | `spec status` → pick one |
| Spec 100% complete | `spec archive {spec}` |

## Directory Structure

```
.specs/
├── project.md           # Project conventions, stack
├── active/{spec}/       # Active specifications
│   ├── spec.md          # Requirements (WHAT)
│   ├── plan.md          # Technical approach (HOW)
│   ├── tasks.yaml       # Task breakdown (WHEN)
│   └── checkpoint.md    # Session progress (optional)
└── archived/{spec}/     # Completed specs
```

## Workflow Phases

### Phase 1: Specification
Create `.specs/active/{spec}/spec.md`:
- [ ] Purpose (1 line)
- [ ] User Stories (AS/WANT/SO THAT + acceptance criteria)
- [ ] Requirements (SHALL/MUST/SHOULD per RFC 2119)
- [ ] Out of Scope (explicit boundaries)

Use `AskUserQuestion` to clarify ambiguities before writing.
Template: `references/spec-template.md`

### Phase 2: Planning
Create `.specs/active/{spec}/plan.md`:
- [ ] Explore codebase first (`Task` with `subagent_type=Explore`)
- [ ] Technical approach + rationale
- [ ] Stack/dependencies
- [ ] Implementation phases with checkpoints

Template: `references/plan-template.md`

### Phase 3: Task Breakdown
Create `.specs/active/{spec}/tasks.yaml`:
- [ ] Break into phases with checkpoints
- [ ] Each task: 1-2 files, <100 lines, clear done criteria
- [ ] Mark dependencies explicitly
- [ ] Include file paths for context loading

Template: `references/tasks-template.md`

###