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. Skip specs/changes/archive/ — archived changes represent completed/merged work and must not be read or referenced.
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#

text

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 for details.

Quick Reference#

PhaseInputOutputGateNext0. Codebase Scancodebase filesstatus.md § Codebase Context—Phase 11. Clarify & Scopeuser requirements + Phase 0 contextrequirements.mdGate 1 (req.)Phase 2a2a. Technical Designrequirements.md``design.md—Phase 2b2b. Design Previewdesign.md``design-preview/Gate 2 (design)Phase 2c2c. Task Breakdowndesign.md + requirements.md``tasks.md—Phase 2d2d. Feature Specstasks.md + design.md``spec_xxx.mdGate 3 (plan)Phase 33. Generatetasks.md + spec_xxx.mdcode + testsGate 4 (code)Phase 44. Verifycode + tests + spec_xxx.mdtest results, Implementation Map—Phase 5 or done5. Evolvetrunk specs + user requestchanges/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:

TrackWhenPhasesArtifactsReview DepthSmallSingle endpoint, field addition, < 1 hrSpec (lite) → Generate → Verifyspec_xxx.md onlyLite (1–2 roles, skip if trivial)MediumSingle feature, 1–4 hrs, 1–3 modulesClarify (brief) → Spec → Generate → Verifyspec_xxx.md + tasks.mdStandard (2–3 roles)LargeMulti-module, > 4 hrs, or new systemFull 5-phase workflowAll spec filesFull (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).

text

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.

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): 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. 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):

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, module layout, UI screens or API flows, and data models.

Constraints:

• Single HTML file per page/screen (inline CSS + JS, no external dependencies) — must open in any browser without a build step.
• Target: validate information architecture and user flow, not pixel-perfect design. Lo-fi is acceptable.
• Limit to ≤ 5 key screens/pages. Prioritize primary user workflow.
• For non-UI projects: Architecture Diagram Preview only (module relationships + data flow as a single HTML page).

UI projects: All generated UI must follow the UI Design Guidelines to avoid AI-template aesthetics.

→ Gate 2: Design Review (2a + 2b combined)#

Per Expert Review Protocol — Gate 2. Exit: User approves (or auto-approved).

2c: Task Breakdown → specs/tasks.md#

Task table (see template). Target granularity: 30–90 min per task.

2d: Feature Spec → specs/spec_<feature>.md#

Per feature (see template): Feature Description & Use Cases, Interface Definition, Data Model, Business Rules & Edge Cases, Test Points (≥ 5 per feature, complex: 10–20; categories: Normal / Error / Boundary / Combination).

→ Gate 3: Implementation Plan Review (2c + 2d combined)#

Per Expert Review Protocol — Gate 3. Exit: User approves (or auto-approved).

Spec Quality Checklist#

Before leaving Phase 2: every interface has explicit I/O types; every business rule has ≥ 1 test point; specs describe what not how; each spec is self-contained for code generation; edge cases are explicit, not implied.

Phase 3: Generate#

Goal: Produce implementation code + tests strictly based on the spec.

Spec adherence — tiered rules:

TierScopeRuleStrictInterfaces, data models, business rulesFollow spec exactly. Do not change signatures, field names, or behavior.FlexibleInternal implementation (function names, code organization, logging, error messages)AI decides, but must note deviations in Human-review points.SPEC-GAPScenarios the spec doesn't cover (discovered during coding)Implement a reasonable solution, tag it [SPEC-GAP], and continue. Collect all gaps for batch review in Phase 4.

Never silently deviate from Strict-tier items. If a Strict item is wrong or incomplete, flag it and ask the user — but do not block on every minor gap.

Execution Strategy#

1. Order: Sort tasks by dependency graph (topological order). Infrastructure/setup tasks first.
2. Parallelism: Tasks with no mutual dependencies may be executed in parallel (e.g., via subagents). Tasks sharing the same module should be sequential to avoid merge conflicts.
3. Commit cadence: One commit per task, tagged with task ID: feat(TASK-001): ...
4. Failure handling: If a task fails to generate or test correctly after 2 attempts, mark it Blocked in tasks.md, log the reason, and continue with non-dependent tasks. Return to blocked tasks after unblocked tasks complete.
5. Progress tracking: Update tasks.md Status column ( Pending → In Progress → Done / Blocked) as each task progresses.

Steps#

1. Scan project structure and tech stack (or use Phase 0 results).
2. For each task in tasks.md (per execution strategy above), take its linked spec_xxx.md as input.
3. Output per task:
   • File list (create vs. modify, with paths)
   • Implementation code
   • Tests derived from spec Test Points (TP-001 → test function)
   • Human-review points — Flexible-tier deviations + all [SPEC-GAP] items
4. Add spec traceability comments at module/class level: // SPEC: spec_auth.md | TASK-002 — enables reverse lookup from code to spec.

For existing codebases: clearly distinguish "new file" vs. "modify existing file" and show diffs for modifications.

→ Gate 4: Code Review#

Per Expert Review Protocol — Gate 4. Exit: User approves (or auto-approved). Proceed to Phase 4.

Phase 4: Verify#

Goal: Confirm generated code satisfies the spec through execution (static compliance is already covered by Gate 4).

4a: Dynamic Verification#

Run the following checks in order. Stop and fix if any step fails.

1. Build — Project compiles / bundles without errors.
2. Lint & Type Check — Run linter and type checker (if available). Zero errors required; warnings acceptable.
3. Unit Tests — Execute test suite ( pytest, npm test, go test, etc.). Map each TP-ID to pass/fail.
4. Integration Tests — Run integration / E2E tests if defined in tasks.md.
5. Coverage Check — Report test coverage. Flag spec Test Points that have no corresponding test execution.
6. NFR Verification — If requirements.md defines measurable NFRs (response time, throughput), run benchmarks and compare. Log results even if not blocking.
7. Manual Test Checklist — For tasks marked AI-Auto: No in tasks.md, generate a manual test checklist with steps and expected results for the user to execute.

4b: SPEC-GAP Resolution#

For each [SPEC-GAP] from Phase 3: Accept (update spec) / Reject (fix code) / Defer (add to backlog).

4c: Implementation Map Update#

After all tests pass, update the ## Implementation Map section in each spec_xxx.md with the actual code file paths and function/class names. This enables reverse lookup from spec to code.

Output & Transitions#

• Passed — items satisfying the spec; Failed — items deviating (recommend: fix spec or fix code)
• All passed → Phase 5 or next task. Failed → fix in Phase 2 or 3 → re-verify.

Exit condition: All items pass, or user acknowledges remaining gaps.

Workflow completion (initial build): If this is the initial build and no further changes are planned, update status.md: mark all phases complete, remove the Initial Build Progress table, and present a summary to the user (features built, test pass rate, deferred items count).

Phase 5: Evolve — New Features & Changes#

Goal: Add new capabilities or modify existing ones while keeping all specs in sync.

Key rule: Always update the spec BEFORE updating the code. Every change goes through specs/changes/.

Step 1: Classify the Work#

TypeCriteriaActionNew FeatureIndependent business value, new interfaces/modelsCreate specs/changes/FEAT-NNN-name/, run full Phase 1–4 within itChange / EnhancementModifies existing feature behaviorCreate specs/changes/CHG-NNN-name/, write delta spec, run Phase 2d–4Trivial FixSingle spec file, single section, no interface/model changeUpdate trunk spec directly with changelog entry, skip change dir

Step 2: Overlap Check#

Before creating the change directory, run Overlap Check against all In-Progress changes listed in specs/index.md. If overlapping Target Specs are found, warn the user and agree on a resolution strategy before proceeding.

Step 3: Work Within the Change Directory#

For Features: run the full workflow (Phase 1–4) inside specs/changes/FEAT-NNN/. For Changes: write a delta-format spec.md (ADDED / MODIFIED / REMOVED), then run Phase 2d–4. For Changes that add/remove screens, modify navigation structure, or alter primary interaction patterns (e.g., forms → tables): also run Phase 2b to update design-preview/.

Path rule: All Phase 1–4 outputs go into the change directory, not the trunk. For example, Phase 2a produces specs/changes/FEAT-NNN/design.md, not specs/design.md. The trunk is only updated during Step 4 (Merge to Trunk).

Nesting rule: Changes are always flat — never create a change inside another change directory. If FEAT-NNN's implementation reveals the need for an additional feature, create a sibling FEAT-NNN+1 at the top level ( specs/changes/FEAT-NNN+1-name/) and add a dependency note in both tasks.md files.

Apply the same review gates as the main workflow, scoped to the change:

• Interface/architecture change → Gate 2 | Business rule change → Gate 3 | Implementation-only → Gate 4

Step 4: Cross-Feature Impact Analysis#

Before generating code, analyze impact across ALL trunk specs:

• Direct: Specs explicitly modified by this change.
• Indirect: Specs that depend on modified interfaces or data models.
• Test: Test points in other specs that may need updating.

Present impact analysis to the user for confirmation.

Step 5: Merge to Trunk#

After code is verified (Phase 4 passed):

1. (Features only) Copy changes/FEAT-NNN/spec.md to specs/spec_<feature>.md.
2. Generate delta.md — merge instructions listing every trunk file/section to update.
3. Apply delta to trunk specs ( specs/*.md): insert ADDED content, replace MODIFIED sections, remove REMOVED items.
4. Add changelog entries to every modified trunk file.
5. Update specs/index.md with the change reference.
6. Commit all trunk updates atomically: spec: merge FEAT/CHG-NNN to trunk.
7. Move change directory to specs/changes/archive/.

For full lifecycle details, merge rules, and scaling guidance, see Spec Lifecycle Management.

Cross-Phase Guidelines#

• No phase skipping: Do not generate code without a confirmed spec. Ask user for confirmation before advancing phases.
• Spec-code traceability: Every code change traces to a spec item (TASK-ID + TP-ID); every spec item has corresponding code and tests.
• Status tracking: Maintain specs/status.md (see template). Update at each phase end with current phase, gate results, and deferred item counts. On session start, read specs/status.md first to restore context.
• Context management: Keep each spec file under ~300 lines. In Phase 3, feed only the relevant spec_xxx.md + related design.md sections — not all spec files at once.
• Expert review: All review gates follow the Expert Review Protocol. Key points: auto-approve when no Critical/Major issues; max 3 rounds per gate; track prior issues across rounds; deferred items logged in spec files. Users can set review preferences in specs/status.md.
• UI de-AI aesthetic: All user-facing UI must follow the UI Design Guidelines to avoid AI-template aesthetics. Gate 2 and Gate 4 reviewers check UI against the de-AI checklist.

Error Recovery#

ScenarioRecovery ActionPhase 3: Task fails after 2 attemptsMark task Blocked in tasks.md, log root cause, continue with non-dependent tasks. After all other tasks complete, revisit blocked tasks — may require spec revision (back to Phase 2d).Phase 4: Tests failCategorize: spec bug (fix spec then re-generate) vs. code bug (fix code, re-run tests). Do not loop more than 3 fix-verify cycles per task — escalate to user.Phase 4: Test environment unavailableGenerate manual test checklist, document expected setup, and mark verification as Pending-Env in status.md. Proceed with remaining phases that don't require the environment.SPEC-GAP: Cannot decide autonomouslyTag as [SPEC-GAP-BLOCKED], implement a safe no-op or error response as placeholder, and batch all blocked gaps for user decision before Phase 4 verification.Phase 5: Delta merge conflictFollow conflict handling in spec-lifecycle.md. Never force-overwrite trunk — always present both versions to the user.Cross-session context lossRead specs/status.md + last completed artifacts (see Session Start). If status.md is missing or stale, scan specs/ directory structure and tasks.md status to reconstruct state.Phase 1: Requirements deadlockIf the user cannot decide after 3 clarification rounds, present a default recommendation with rationale. Ask for explicit approval or override. Do not loop indefinitely.Phase 2: Design deadlockIf two design options are equally viable, document both in ADR format (pros/cons/consequences), provide a recommended option, and ask the user to decide. Limit to 2 discussion rounds, then adopt the recommendation if no response.

Templates#

For spec file templates, see templates.md (core) and templates-lifecycle.md (lifecycle & review).