spec-driven-development

Spec-Driven Development

Overview

Write the implementation spec before writing code. The spec is the shared source of truth between the engineer, the command flow, and the reviewers. Code without a spec is guessing.

Tool discipline (phase-locked): spec authoring is a read + spec-artifact phase. Write only the spec artifacts (docs/specs/<date>-<slug>.md and its .json sidecar) — never source or test code. Code starts at Phase 3, after the approval gate; a source edit here is a scope violation. (Not toolset-locked to read-only because it must write its spec files.)

Supplied spec/plan (adoption, not authoring): when the engineer hands in a complete spec or plan as the input (e.g. docs/specs/…md or docs/plans/…md already on disk), implement's Phase 0.7 adopts it as the source of truth. In that case this skill validates the supplied artifact against the schema and reconciles it against the current code (see prior-work-check's existing-plan reconciliation) rather than re-authoring to a fresh path — never overwrite or version-bump the engineer's input. See implement/SKILL.md Phase 0.7.

When To Use

• New endpoints, handlers, routes, or views
• Database changes or migrations
• Multi-file work
• Breaking changes
• Any task where approval should happen before coding
• Any task likely to take more than a short focused session

When NOT To Use

• Typo fixes
• One-line config updates with no behavior impact
• Small bug fixes that clearly stay within quick-fix scope

Workflow

Decision Graph

This graph drives the two questions models get wrong most often: "do I need a spec at all?" and "can I start coding after writing one?" The red node is the hard stop — implementation never begins inside this skill.

digraph spec_flow {
  rankdir=TB;
  node [shape=box, style=rounded, fontname="Helvetica"];
  edge [fontname="Helvetica", fontsize=10];

  start    [label="task arrived"];
  trivial  [label="typo / 1-line config /\nclear quick fix?", shape=diamond];
  skip     [label="skip spec\n(use fix workflow)", style="rounded,filled", fillcolor="#e0f0e0"];
  multi    [label="multi-file OR new endpoint /\nhandler / migration OR\nbreaking change?", shape=diamond];
  long     [label="longer than a short\nfocused session?", shape=diamond];

  load     [label="load standards:\nCLAUDE.md, coding guidelines,\nsecurity, testing, architecture,\nrelevant lessons"];
  assume   [label="surface assumptions\n(runtime, arch, storage,\nauth, boundaries)"];
  classify [label="classify scope:\ninternal-refactoring /\nnew-feature / breaking-change"];
  pattern  [label="read 2-3 nearby files\nfor local pattern"];
  ambig    [label="ambiguity present?\n(≥2 plausible designs OR\nundefined scope edge OR\nunresolved arch choice)", shape=diamond];
  ask      [label="ask via AskUserQuestion\nBEFORE drafting\n(batched ≤2 / interview ≥3)"];
  draft    [label="draft spec sections:\nsummary · success criteria ·\narch · security impact ·\nchange manifest · test manifest ·\nbatches · risks · open Qs"];
  elegance [label="elegance check:\nfewer files? fewer\nabstractions? fewer\nmoving parts?"];
  sec      [label="security_impact\nhonest?", shape=diamond];
  fixsec   [label="upgrade security_impact\n(spec-drift will catch lies)",
            style="rounded,filled", fillcolor="#fff8d0"];
  persist  [label="write to disk:\ndocs/specs/<date>-<slug>.md\n+ <date>-<slug>.json sidecar\n(version-suffix if exists)"];
  approve  [label="STOP — hand to approval gate.\nDo NOT implement.\nDo NOT merge into batch 1.",
            style="rounded,filled", fillcolor="#ff9090"];

  start -> trivial;
  trivial -> skip  [label="yes"];
  trivial -> multi [label="no"];
  multi   -> load  [label="yes"];
  multi   -> long  [label="no"];
  long    -> load  [label="yes"];
  long    -> skip  [label="no"];

  load -> assume -> classify -> pattern -> ambig;
  ambig -> ask   [label="yes"];
  ambig -> draft [label="no"];
  ask   -> draft;
  draft -> elegance -> sec;
  sec  -> fixsec  [label="no — auth/payments/\naudit/secrets/PII/IAM\nbut marked 'none'"];
  fixsec -> persist;
  sec  -> persist [label="yes"];
  persist -> approve;
}