Skip to content

Spec-driven development

The big picture: Blueprint turns a written spec into tracker work in a fixed sequence, and a script decides whether the spec is complete enough to start. You write (or let /spec new write) one Markdown file under docs/specs/, the completeness gate scripts/check-spec-completeness.py checks its shape, and /spec import turns a spec that passed into one milestone per phase and one issue per feature. One skill, /spec, covers every step, and bare /spec does the next one for the spec’s status.

Why it matters: An issue made from a half-finished spec inherits its gaps: missing acceptance criteria, features that depend on an undecided choice, personas nobody serves. Those gaps surface in code review, where they cost the most. The gate surfaces them before any issue exists, names the rule and the section, and a green result is evidence that the spec has all its parts.

How it works:

  1. /spec new <slug> elicits a spec one template section at a time, writing the file after each stage so an interrupted session resumes where it stopped; /spec <path> audits one you already wrote. Both loop the gate until it passes.
  2. You say yes, and status moves from draft to ready.
  3. /spec import refuses a draft, FAIL or INCOMPLETE spec (an imported spec whose only failures are S-19 is let through, see below), then creates milestones and issues and stamps each feature with Issue: #N. --dry-run shows the plan and stops.
  4. /dotplanning reads the imported milestone.
  5. /spec revise makes the next version, and a re-import brings its changes to the existing issues, one confirmed diff at a time.

The whole sequence (the gate, the spec-check job and /spec) ships in 0.8. /spec-intake and /import-spec are deprecated aliases of /spec new or /spec <path>, and /spec import, removed after the next minor release.

Step Command What it does Never does
1 /spec new <slug> or /spec docs/specs/x.md Asks only for what is missing, in template order, for at most three loops; runs spec-review at most twice, and only once the gate passes Create issues, commit, write “Decided” for a choice you did not call decided, or set status: ready without your yes
2 python3 scripts/check-spec-completeness.py (or make check-specs) Prints one derivation line per finding and an overall verdict Judge whether the spec is right
3 /spec import docs/specs/x.md Creates a milestone per phase and an issue per feature, each with Spec: and Spec-version: lines; --dry-run prints the plan only Run on a draft, FAIL or INCOMPLETE spec, unless overridden or re-importing
4 /dotplanning <milestone> Plans the imported milestone
5 /spec revise docs/specs/x.md The next version: supersedes:, a Changes in v… table, removed ids marked withdrawn Renumber an id, or edit an issue without your yes on re-import

/spec is a skill, so it runs with your permissions. It is user-invoked only, because import creates issues.

Each authoring run (/spec new or the audit) writes one intake: front matter line. Authoring never creates an issue and never writes history; its only glab calls are the read-only lookups that verify a “reuse X from repo Y” claim, and at the hand-off it prints the /spec import command for you to run. /spec import is the verb that runs glab to create milestones and issues, and only after your yes.

They look alike and do different jobs.

/kickoff /spec
Describes The project, once: name, stack, commands A product area, and recurs: one spec per area
Writes AGENTS.md and project files docs/specs/<slug>.md
Runs At setup Whenever you plan a new area

/spec new pre-fills Stack and Users from what /kickoff wrote (AGENTS.md, .claude/personas.md), and treats a value that still reads as a placeholder as unverified.

Already have a spec? Put it in docs/specs/ before /kickoff: kickoff prefills Round 1 from it, and Round 3’s project path when the spec has a valid GitLab project path section. On GitLab it creates no seed issues and leaves issue creation to /spec import, which needs glab and refuses a draft, so the order is /kickoff, then /spec <path> until the spec is ready, then /spec import <path>. On GitHub kickoff still creates the seed issues (Start a project, step 4).

Pick one source of issues. Seed issues and /spec import both create issues for the first milestone, and a reworded title slips past both duplicate checks, so running both duplicates the backlog. Use the seed issues when there is no spec for the first milestone, let /spec import create them when there is, and if both ran, close the duplicates (/tracker-hygiene flags likely ones). The three cases are in Start a project, step 9.

The gate has thirty-one rules, S-01 to S-31. Each has a severity: FAIL, INCOMPLETE, or WARN. The full table, the section aliases and the front matter keys are in docs/specs/README.md, and python3 scripts/check-spec-completeness.py --rules prints it. A few worth knowing:

Rule Checks Severity
S-02 Placeholder text (TBD, TODO, template tokens) WARN under draft; FAIL under ready and imported
S-04 At least 3 users, each with a goal and a frustration INCOMPLETE
S-09 At least 2 acceptance criteria per feature INCOMPLETE; WARN on vague words
S-11 Every Depends on: resolves to a feature or decision in the spec FAIL
S-19 An imported spec has Issue: #N on every feature FAIL
S-20 Escaped Markdown or smart quotes left by a document export WARN; --fix repairs it
S-21 Depends on: edges form a cycle FAIL

A spec pasted from a document export arrives with escaped Markdown (backslashes before -, [ and ]) and smart quotes in the front matter. python3 scripts/check-spec-completeness.py --fix docs/specs/<slug>.md unescapes them and prints each change. It never changes content, a second run changes nothing, and it needs explicit paths.

The gate checks that the parts exist and are well formed, not that they are good. Whether a criterion is testable, or a dependency is the true one, is for you and the spec-review agent.

Each finding is one stable, greppable line:

S-09 · F-07 "trueproof map" · acceptance criteria: 1 found, 2 required → INCOMPLETE
S-11 · F-13 · depends on D-99: no such decision → FAIL

Read it left to right: the rule, the feature or section, what it found against what it needs, and the severity. A tally and one overall verdict follow. The verdict is the worst severity found, and it sets the exit code:

Verdict Exit code
PASS, PASS WITH WARNINGS 0
INCOMPLETE 1
FAIL 2
Unreadable (no front matter, unclosed block, untracked or out-of-repo path) 3

--json prints the same findings as spec-verdict/1, one object per line.

/spec import refuses a spec that is draft, FAIL or INCOMPLETE. To proceed anyway:

/spec import docs/specs/x.md --allow-incomplete "reason in one line"

The reason is required (an empty one is rejected). It is written as Override: <reason> into every issue the run creates and as an override: line in the spec’s front matter, so the shortcut stays visible. An override run leaves status unchanged unless the final verdict is exit 0 and the status was ready. A file with no front matter is not a spec and has no override; write it with /spec new.

An override does not make the spec pass. spec-check runs on every tracked file under docs/specs/, so fix the spec with /spec <path> before you commit, or the spec-check job goes red.

When an imported spec gains a feature, the new feature has no Issue: line, so S-19 fails. That is the prompt, not a bug:

  1. Run /spec revise docs/specs/x.md: add the feature, and it bumps version, records the change in a Changes in v… table and sets status: draft. Say yes to ready once the gate passes.
  2. Run /spec import docs/specs/x.md again (--dry-run first to see the plan). It creates only the missing issue and stamps it; features that already have Issue: #N are not created twice.
  3. Commit the spec.

The same re-import compares each existing issue with the revised spec. Only an issue whose body carries this spec’s exact Spec: line is offered an update, and only after your yes for that issue: you see the title, acceptance-criteria and Spec-version: diff first, criteria you ticked stay ticked when their text is unchanged, new ones are added unticked, and removed ones are dropped. A withdrawn feature is reported and its issue is never closed; a backlog feature gets an issue with no milestone.

Do not write the Issue: #N line by hand.

  • make check-specs runs the gate’s self-test, then the scan, and is part of make pre-push-checks.
  • The spec-check CI job runs on merge requests that touch docs/specs/ or the gate, and always on main.
  • A tracked draft that still fails the gate turns main red, so keep unfinished drafts untracked or on a local branch.
  • Start a project, step 9 shows the commands in order.
  • Commands describes /spec and its verbs.
  • Harness gates lists the gate and explains why every gate has a --self-test.
  • docs/specs/README.md holds the rule table, statuses, section aliases and front matter keys.