Spec Coder

Structured spec-first development workflow with multi-role expert review gates: clarify requirements, author spec documents (requirements/design/tasks), generate code from spec, verify with real tests, and iterate while keeping spec and code in sync. Use when user wants to build a feature or system with a spec-first approach, mentions "spec coding", "spec-driven development", or asks to write specs before coding.

# Spec Coding Workflow

Write specs first, then generate code. 5 phases, each producing artifacts that feed the next. Expert review gates between phases catch issues early.

## Session Start

On every new session:

1. **Read `specs/status.md`** to identify current phase, active changes, and deferred items.
2. **Read phase-relevant spec files** — see Quick Reference table below for which artifacts each phase produces/consumes.
3. **Confirm with the user** which phase/gate to continue from. If mid-phase, summarize progress so far.
4. **No `specs/status.md`?** This is a new project — start from Phase 0 (existing codebase) or Phase 1 (greenfield).

## Workflow Overview

```
Phase 0 ──→ Phase 1 ──→ ║Gate 1║ ──→ Phase 2a ──→ Phase 2b ──→ ║Gate 2║
(scan)      (clarify)    (req.)       (design)      (preview)     (design)
                                                                     │
    ┌────────────────────────────────────────────────────────────────┘
    ▼
Phase 2c ──→ Phase 2d ──→ ║Gate 3║ ──→ Phase 3 ──→ ║Gate 4║ ──→ Phase 4 ──→ Phase 5
(tasks)      (specs)       (plan)       (code)       (code)       (verify)    (iterate)
                                                                                  │
                                                                    ┌─────────────┘
                                                                    ▼
                                                              Re-trigger Gate
                                                              2 / 3 / 4 based
                                                              on change scope
```

Gates auto-approve when no Critical/Major issues. See [Expert Review Protocol](references/expert-review-protocol.md) for details.

### Quick Reference

| Phase | Input | Output | Gate | Next |
|-------|-------|--------|------|------|
| 0. Codebase Scan | codebase files | `status.md` § Codebase Context | — | Phase 1 |
| 1. Clarify & Scope | user requirements + Phase 0 context | `requirements.md` | Gate 1 (req.) | Phase 2a |
| 2a. Technical Design | `requirements.md` | `design.md` | — | Phase 2b |
| 2b. Design Preview | `design.md` | `design-preview/` | Gate 2 (design) | Phase 2c |
| 2c. Task Breakdown | `design.md` + `requirements.md` | `tasks.md` | — | Phase 2d |
| 2d. Feature Specs | `tasks.md` + `design.md` | `spec_xxx.md` | Gate 3 (plan) | Phase 3 |
| 3. Generate | `tasks.md` + `spec_xxx.md` | code + tests | Gate 4 (code) | Phase 4 |
| 4. Verify | code + tests + `spec_xxx.md` | test results, Implementation Map | — | Phase 5 or done |
| 5. Evolve | trunk specs + user request | `changes/` | scoped gate | → Phase 1–4 |

## When to Use

**Trigger conditions:**
- User mentions "spec coding", "spec-first", "spec-driven development"
- User asks to write specs / requirements / design docs before implementation
- User mentions phase keywords: "clarify requirements", "write a spec", "generate from spec"

**When NOT to use:** Pure bug fixes, one-line config changes, dependency updates, or tasks completable in < 15 minutes without design decisions.

**Complexity triage — choose the right track:**

| Track | When | Phases | Artifacts | Review Depth |
|-------|------|--------|-----------|-------------|
| **Small** | Single endpoint, field addition, < 1 hr | Spec (lite) → Generate → Verify | `spec_xxx.md` only | Lite (1–2 roles, skip if trivial) |
| **Medium** | Single feature, 1–4 hrs, 1–3 modules | Clarify (brief) → Spec → Generate → Verify | `spec_xxx.md` + `tasks.md` | Standard (2–3 roles) |
| **Large** | Multi-module, > 4 hrs, or new system | Full 5-phase workflow | All spec files | Full (all roles) |

Ask the user which track fits, or infer from the scope of their request.

**Small track shortcut:**
Skip Phase 1. Write a single `spec_xxx.md` (Interface + Business Rules + Test Points only), then go straight to Generate → Verify.

**Medium track shortcut:**
Phase 1 is a brief bullet-point confirmation (no full `requirements.md`). Phase 2 produces `tasks.md` + `spec_xxx.md` only (skip `design.md` and `design-preview/` unless architecture decisions are needed).

**Mid-project entry:**
If the user already has spec files or an existing codebase, read them first. Validate existing artifacts against the expected format, then confirm which phase to start from.

## File Organization

Two-layer structure: **trunk** (current system truth) + **changes** (incremental work).

```
specs/
├── index.md                    ← navigation hub: all features & recent changes
├── requirements.md             ← project-level requirements (grows incrementally)
├── design.md                   ← system-level architecture (grows incrementally)
├── design-preview/
├── tasks.md                    ← active tasks only
├── status.md
├── spec_<feature_name>.md      ← feature specs (current truth, one per feature)
└── changes/                    ← all incremental work
    ├── FEAT-NNN-name/          ← new feature (full spec lifecycle)
    │   ├── spec.md
    │   ├── design.md
    │   ├── tasks.md
    │   └── delta.md            ← merge instructions for trunk
    ├── CHG-NNN-name/           ← change/enhancement (delta only)
    │   ├── spec.md             ← ADDED / MODIFIED / REMOVED sections
    │   ├── tasks.md
    │   └── delta.md
    └── archive/                ← completed & merged changes
```

**First-time projects:** Start with trunk only (no `changes/` needed). The changes layer is introduced when the first post-v1 feature or modification begins.

For full lifecycle management details, see [Spec Lifecycle Management](references/spec-lifecycle.md).

## Phase 0 (Optional): Codebase Scan

For existing codebases, run before Phase 1: read dependency files to detect tech stack, list directory tree, identify existing interfaces/models/conventions, and summarize findings.

**Output:** Write results to `specs/status.md` under `## Codebase Context` (tech stack, key conventions, existing interfaces, directory structure summary). This persists the scan across sessions. Phase 1 references this for requirements scoping; Phase 2a references it for architecture decisions.

## Phase 1: Clarify & Scope

**Goal:** Turn informal requirements into a confirmed, structured `requirements.md`.

**Constraints:** Do NOT write any code. Only ask questions and produce documents.

1. **Interactive Clarification** — Ask user for raw requirements. Summarize goals (3–5 bullets), list ambiguities with options, suggest unconsidered constraints. Iterate until confirmed.
2. **Structured Requirements** — Produce `specs/requirements.md` (see [template](references/templates.md#requirementsmd-template)): Background & Objectives, User Roles & Use Cases, Functional Requirements (FR-001...), Non-Functional Requirements, Out of Scope. If Phase 0 ran, populate the "Existing Architecture" section with requirement-relevant context from `status.md` § Codebase Context.

### → Gate 1: Requirements Review

Per [Expert Review Protocol — Gate 1](references/expert-review-protocol.md#gate-1-requirements-review-after-phase-1). **Exit:** User approves (or auto-approved).

## Phase 2: Spec

**Goal:** Produce spec documents that directly drive code generation.

### 2a: Technical Design → `specs/design.md`

Based on `requirements.md`, produce `specs/design.md` (see [template](references/templates.md#designmd-template)):
1. Architecture overview (tech stack, layers, services)
2. Core module breakdown with responsibilities and dependency directions
3. Key data models, interfaces & interaction flows
4. Cross-cutting concerns (error handling, auth, observability, deployment) — skip on Small track
5. NFR fulfillment matrix + key architecture decisions (ADR format) — skip on Small/Medium track

For existing codebases: populate "Existing Architecture" section with architecture-relevant context from `status.md` § Codebase Context (what's new vs. modified).

### 2b: Design Preview → `specs/design-preview/`

Self-contained HTML prototype visualizing architecture, m