spec-driven-development

# Spec-Driven Development

A structured workflow where specifications are the source of truth. Implementation follows from specs, not the other way around.

**Always read [RULES.md](RULES.md) first** - it contains immutable principles that apply at all times.

## Workflow Overview

```
Analysis  →  Design → Plan → Execute → (Critique)
    │           │        │        │          │
    ▼           ▼        ▼        ▼          ▼
requirements  design  tasks    code    verdict
              (opt)            (on-demand)
```

Each phase produces a specification artifact. `notes/` can be created during any phase when there's information worth recording (research, exploration findings, incidental insights, failed approaches).

## When to Use This Workflow

SDD is valuable for complex, multi-session, or collaborative work. For trivial changes (single-line fixes, routine refactors, obvious implementations), skip SDD and implement directly. See **RULES.md > When to Use Spec-Driven Development** for detailed guidance.

## Agency Modes

**Interactive mode** (default): Use AskUserQuestion at each phase to gather input and confirm decisions.

**High agency mode**: When the user requests autonomous operation (e.g., "work on this until done", "implement this end-to-end", "full autopilot"), iterate through phases without prompting:
1. Analyze the problem and draft requirements
2. **Invoke spec-critic agent** (`intra-spec` mode) to validate requirements
3. Design the solution (if non-trivial)
4. Plan implementation with clear checkpoints
5. **Invoke spec-critic agent** (`intra-spec` + `spec-code` modes) to validate plan
6. Execute, looping back to earlier phases if snags arise
7. Verify against all acceptance criteria
8. **Invoke spec-critic agent** (`all` modes) before marking complete

In high agency mode, only pause for user input when hitting a genuine ambiguity that cannot be resolved through reasoning, or when the critic escalates after 5 rounds.

## Spec Directory Structure

``