Skip to content

borghei/Claude-Skills / engineering/spec-driven-workflow

spec-driven-workflow

Verified

Run development from an executable specification with traceable requirement IDs and merge-time coverage gates. Use when starting a greenfield feature, reviving a stale spec, or gating merges on requirement coverage.

Spec-Driven Workflow

Development where the specification is the source of truth and the code is its implementation, rather than a document that was true at kickoff and fiction by week three. The mechanism is unglamorous: every normative statement gets a stable ID, every ID appears in a test, and the merge gate fails when the two drift apart. Without that mechanical link a spec is a memo, and memos do not survive contact with a sprint.

When to use this skill

  • Starting a greenfield feature where the interface is contested and the cost of building the wrong thing is high
  • Reviving a stale spec that no longer matches shipped behaviour and needs reconciling before the next change
  • Gating merges on coverage so a PR that implements two of five committed requirements cannot silently land
  • Auditing what actually shipped ahead of a stakeholder review or a compliance obligation
  • Handing a feature to another team who need the intent, not just the code
  • Generating an implementation from a spec — which only works if the spec is precise enough that two engineers would build the same thing
  • Capturing a spec from a conversation — a chat thread, design call or agent session where the decisions already exist but nobody wrote them down
  • Implementing ticket by ticket from an approved spec, test-first, with a review and a commit per ticket

Inputs the skill expects

  • A specification document in markdown, with normative statements using must/shall/should/may
  • Acceptance criteria per requirement, ideally in given/when/then form
  • The source tree and test suite where implementations will be annotated
  • The coverage bar the merge gate enforces (mandatory-requirement coverage, typically 1.0)
  • The previous requirements snapshot, when checking for drift against a baseline
  • Which requirements are explicitly out of scope for the current milestone

Clarify First

Before writing or auditing a spec, settle the inputs below. When one is missing or vague and would change the result, ask about it; when it wouldn't, use a sensible default and say which one you used.

  • What must be true for this to be "done": becomes the acceptance criteria; without it the spec is a wish list and nothing is verifiable.
  • Which constraints are hard vs preferences: decides must/shall versus should, which in turn decides what the merge gate blocks on.
  • Who consumes the spec: an implementing engineer, a generating model, and an auditor need different precision; the generating case needs the most.
  • Scope boundary for this milestone: requirements outside it must be marked, or coverage reports will show permanent false gaps.

Ask about the two or three inputs that matter most for this request, not the whole list. If the user wants a result straight away, produce it and state your assumptions at the top.

Quick Start

# Lint the spec, freeze IDs, then gate on coverage (lint and coverage exit 1 on the samples' deliberate flaws;
# every tool exits 2 on bad input such as a missing file or invalid JSON)
python3 engineering/spec-driven-workflow/scripts/spec_lint.py --spec engineering/spec-driven-workflow/assets/sample_spec.md
python3 engineering/spec-driven-workflow/scripts/spec_parse.py --spec engineering/spec-driven-workflow/assets/sample_spec.md --format text
python3 engineering/spec-driven-workflow/scripts/trace_coverage.py --requirements engineering/spec-driven-workflow/assets/sample_requirements.json --index engineering/spec-driven-workflow/assets/sample_trace_index.json

Workflows

Workflow 0 — Capture the spec from a conversation [RECOMMENDED]

Use when the decisions were made in a discussion — a chat thread, a call, a long session with a coding agent — and need to become a spec without being re-litigated. Detail and worked rules: references/conversation-capture-and-implementation-loop.md, Part 1.

  1. Read the whole conversation once before writing. Sort every substantive statement into decision, constraint, example, deferred, or open. Discussion that fits no bin stays out.
  2. Write each decision as one normative statement with a modality keyword, keeping the numbers people actually said. A decision the agent made alone and the user never confirmed is open, not decided.
  3. Turn the examples people walked through into given/when/then acceptance criteria.
  4. Quote deferrals word for word in the out-of-scope list, and put open questions in their own section with an owner — never as TBD inside a requirement.
  5. Ask only about gaps that would change a requirement, in one batch. Then read the requirement and out-of-scope lists back and ask what is on them that was not decided.
  6. Run Workflow 1's linter. Captured specs usually fail first on unquantified adjectives.

— Write the spec, then prove it is precise

  1. Draft requirements one statement at a time, each with exactly one obligation and a modality keyword. Two obligations in one sentence become two requirements.
  2. Attach given/when/then acceptance criteria directly beneath each requirement.
  3. Run the ambiguity linter. Fix every error before circulating the draft; errors are statements no engineer could implement without guessing.
  4. Re-run until the precision ratio clears 0.85. Below that, review meetings will be spent discovering ambiguity rather than discussing design.
python3 engineering/spec-driven-workflow/scripts/spec_lint.py \
  --spec engineering/spec-driven-workflow/assets/sample_spec.md \
  --max-findings 0 --min-precision 0.85 --format text

The shipped sample scores 0.46 on purpose — it contains the exact failures the linter is built to catch, so you can see each rule fire before pointing it at real work.

Workflow 2 — Extract requirement IDs and freeze the baseline

  1. Parse the spec into requirements. IDs are derived from section and ordinal (REQ-ROTATION-02), so they are stable across unrelated edits elsewhere in the file.
  2. Commit the emitted JSON alongside the spec. This is the baseline.
  3. On every subsequent parse, diff against the baseline. A DRIFT line means a requirement's text changed while its ID stayed the same — its tests now verify something the spec no longer says, which is the most dangerous state in the workflow.
python3 engineering/spec-driven-workflow/scripts/spec_parse.py \
  --spec engineering/spec-driven-workflow/assets/sample_spec.md \
  --baseline engineering/spec-driven-workflow/assets/sample_requirements.json \
  --require-acceptance --format text

Exit code is 1 when a mandatory requirement lacks acceptance criteria or when any requirement has drifted, which makes this the first half of the CI gate.

Workflow 3 — Gate the merge on bidirectional coverage

  1. Annotate implementations and tests with their requirement IDs in comments or test names (def test_rotation_marks_pending_revocation(): # REQ-ROTATION-01).
  2. Run coverage against the source tree. Read both directions: requirements with no implementation, and annotations naming IDs the spec no longer contains.
  3. Fail the build below the mandatory coverage floor, or on any orphan annotation.
python3 engineering/spec-driven-workflow/scripts/trace_coverage.py \
  --requirements engineering/spec-driven-workflow/assets/sample_requirements.json \
  --index engineering/spec-driven-workflow/assets/sample_trace_index.json \
  --min-coverage 1.0 --format text

Swap --index for --code <path> to scan a real tree. The index form exists so the gate can run against a trace index built by another tool, and so this workflow is runnable straight from a fresh clone.

Workflow 4 — Implement from the spec, one ticket at a time [PROVEN]

Use once the spec is approved and broken into tickets with blocking links. The loop keeps code and spec in lockstep. Detail: references/conversation-capture-and-implementation-loop.md, Part 2.

  1. Pick a ticket from the frontier — one whose blocking tickets are all done. The agent starts each ticket with fresh context: the ticket, its requirement IDs, and the spec sections they live in.
  2. Write a failing test annotated with the requirement ID and watch it fail for the expected reason.
  3. Write the minimum code to pass it, annotated with the same ID.
  4. Validate: run the test suite, then spec_parse.py against the baseline (no drift) and trace_coverage.py (the ticket's IDs now covered, no orphans).
  5. Refactor with the tests green, then review the ticket's diff on two axes — repo standards, and fidelity to the requirement (nothing missing, nothing extra).
  6. Commit once per ticket, naming the ticket and requirement IDs in the message. Close the ticket and recompute the frontier.
  7. If the spec proves wrong mid-ticket, stop. Fix the spec in the same branch, re-lint, update the baseline, then resume. Never code around a wrong requirement.

The spec is done when every ticket is closed, the coverage gate passes at its floor, and a final whole-branch review against the spec finds no gap and no unrequested behaviour.

Decision frameworks

How precise does the spec need to be? [PROVEN]

Precision is a cost, and the right amount depends entirely on who reads the spec next.

ConsumerRequired precisionTest
Engineer on the team who wrote itModerateShared context fills gaps; acceptance criteria on mandatory requirements only
Engineer on another teamHighEvery requirement has criteria; no undefined domain terms
A model generating the implementationVery highEvery requirement quantified; no adjective without a number
An auditor or regulatorVery high, plus provenanceEvery requirement traced to a test result and a decision record

Writing at "very high" for an internal one-week feature is waste. Writing at "moderate" for a generated implementation produces confidently wrong code, because ambiguity gets resolved silently rather than escalated.

Requirement status ladder

Every requirement sits in one of four states. Only one is acceptable at merge.

StatusMeaningAction
coveredImplementation and test both annotatedMerge
untestedCode exists, no test references the IDBlock — this is the state that regresses silently
test-onlyTest exists, no implementation annotatedUsually a missing annotation, occasionally a test asserting nothing
unimplementedNeither existsBlock if mandatory; acceptable if explicitly deferred

Coverage floors by requirement modality [RECOMMENDED]

ModalityKeywordCoverage floor at merge
Mandatorymust, shall1.0 — no exceptions; a mandatory requirement without a test is not implemented
Recommendedshould0.8 — deviations recorded in the PR with a reason
Optionalmay, canNo floor — tracked, not gated

The floors matter less than their being non-negotiable once set. A coverage gate that gets waived twice stops being read.

Ambiguity rules and what each one prevents

RuleFires onPrevents
unquantified-adjectivefast, scalable, secure, intuitiveRequirements nobody can fail
passive-no-actor"notifications should be delivered"Obligations with no owning component
no-acceptance-criteriaNormative statement with no given/when/thenRequirements that cannot be verified
placeholderTBD, TODO, ???Specs that gate merges while still undecided
compound-requirement"and/or", two obligations in one sentencePartial implementations that still pass
undefined-antecedentOpens with it/this/theyRequirements that break when reordered
vague-quantifiersome, several, mostDisagreement discovered at review time

Anti-Patterns

The Write-Once Spec

Mistake: Writing a thorough specification at kickoff, then implementing against reality for six weeks without touching it. Why it happens: Updating the spec has no forcing function. Nothing breaks when it goes stale, so it loses every contest for attention against shipping code. Instead: Put the spec in the same repository, in the same PR, behind the same merge gate as the code. A requirement change and its implementation land together or neither lands. The gate is what converts "we should keep it updated" into a thing that actually happens.

Adjective-Driven Requirements

Mistake: "The API must be fast and the interface must be intuitive." Why it happens: These feel like requirements and are easy to agree on precisely because nobody can disagree. Everyone leaves the meeting satisfied and holding different pictures. Instead: Every adjective becomes a number with a unit and a measurement method: "p95 latency under 200ms measured at the load balancer over a 5-minute window." If you cannot produce the number, the requirement is not ready and should be marked as such rather than shipped vague.

ID Drift

Mistake: Editing a requirement's text in place while keeping its ID, so tests that reference the ID now verify something the spec no longer says. Why it happens: Renumbering feels disruptive, and editing text feels smaller than adding a requirement. Both are true; the consequence is still a silent divergence. Instead: Fingerprint requirement text and diff against a committed baseline on every parse. A drift finding forces a decision: either the tests get updated, or the edit was actually a new requirement and needs a new ID.

One-Way Traceability

Mistake: Checking that every requirement has code, but never checking that every annotated code path has a requirement. Why it happens: The forward direction answers "did we build what we promised," which is the question stakeholders ask. Nobody asks the reverse question, so nobody builds the report. Instead: Run coverage in both directions and treat orphan annotations as errors. Orphans mark dead features whose requirement was deleted, typos in IDs, and scope that entered the codebase without ever entering the spec — all three are worth knowing.

The Re-Interview

Mistake: Capturing a spec from a long discussion by asking the user every question again from scratch. Why it happens: Starting from a blank template feels thorough, and re-reading a long thread feels slow. Instead: Extract decisions, constraints, examples and deferrals from the conversation first, and ask only about gaps that would change a requirement. Re-asking settled questions costs trust and invites the answers to drift.

The Batched Commit

Mistake: Implementing several tickets and landing them as one commit or one unreviewed push. Why it happens: It feels faster to keep coding while the context is warm. Instead: One loop per ticket — red test, code, gates, review, commit. Per-ticket commits keep each requirement's implementation findable, reviewable and revertable on its own.

The Merge Gate Nobody Believes

Mistake: Setting a 100% coverage gate, waiving it under deadline, and waiving it again the following week. Why it happens: The gate was set at an aspirational number rather than the number the team will actually hold, so the first real deadline breaks it. Instead: Gate only on mandatory requirements, at 1.0, and let should requirements report without blocking. A narrow gate that never gets waived changes behaviour; a broad gate that gets waived teaches everyone that red builds are advisory.

Files

FilePurpose
scripts/spec_parse.pyParse a markdown spec into requirements with stable IDs and content fingerprints; diff against a baseline
scripts/spec_lint.pyFlag ambiguity — unquantified adjectives, passive requirements, missing criteria, placeholders
scripts/trace_coverage.pyBidirectional spec-to-code coverage with orphan-annotation detection and a merge gate exit code
references/spec-writing-guide.mdRequirement grammar, acceptance-criteria patterns, and worked ambiguous-to-precise rewrites
references/traceability-model.mdID schemes, annotation conventions per language, CI wiring, and drift handling
references/conversation-capture-and-implementation-loop.mdTurning a conversation into a spec (five bins, drafting rules, read-back) and the per-ticket implementation loop (frontier, test-first, gates, review, commit)
assets/sample_spec.mdRunnable sample spec containing both precise and deliberately ambiguous requirements
assets/sample_requirements.jsonParsed baseline for the drift and coverage workflows
assets/sample_trace_index.jsonPrebuilt trace index exercising covered, untested, test-only, and orphan states
assets/spec-template.mdSkeleton for a new specification with the required structure

Scope & Limitations

In Scope:

  • Ambiguity linting of a markdown spec with spec_lint.py: seven rules, a precision ratio and exit-code gates (--max-findings, --min-precision).
  • Requirement extraction with stable IDs and content fingerprints with spec_parse.py, drift detection against a baseline, and a gate on missing acceptance criteria.
  • Two-way coverage between requirement IDs and annotated code and tests with trace_coverage.py, from a source tree or a prebuilt trace index, with orphan detection and a coverage floor.
  • Spec writing and traceability guidance in references/, plus a spec template and sample files in assets/.
  • Capturing a spec from a conversation or agent session, and the test-first, review-and-commit-per-ticket loop for implementing from it.

Out of Scope:

  • Teaching test-driven development itself (see tdd-guide).
  • Slicing the spec into tracer-bullet tickets with blocking links, and branch/PR planning (see spec-to-repo).
  • Running the test suite or measuring code coverage.
  • Product discovery and deciding which requirements matter.

Important Caveats:

  • Coverage means an annotation with the requirement ID was found. It does not show that the test passes or that the code meets the requirement.
  • The linter uses word and phrase rules. It can miss ambiguity phrased in other ways and can flag acceptable wording, so a high precision ratio still needs human review.
  • Stable IDs depend on section and order. Moving requirements between sections changes their IDs, which shows up as drift against the baseline.

Reference Documentation

  • references/spec-writing-guide.md — requirement grammar and ambiguous-to-precise rewrites.
  • references/traceability-model.md — ID schemes, annotations, CI wiring, drift.
  • references/conversation-capture-and-implementation-loop.md — conversation-to-spec capture and the per-ticket implementation loop.
finishing-a-development-branchobra/superpowersUse when implementation is complete, all tests pass, and you need to decide how to integrate the workStars: 318kUpdated Claude CodeCodexVerifiedInstall
systematic-debuggingobra/superpowersUse when encountering any bug, test failure, or unexpected behavior, before proposing fixesStars: 318kUpdated Claude CodeCodexVerifiedInstall
test-driven-developmentobra/superpowersUse when implementing any feature or bugfix, before writing implementation codeStars: 318kUpdated Claude CodeCodexVerifiedInstall
skill-creatoranthropics/skillsCreate new skills, modify and improve existing skills, and measure skill performance. Use when users want to create a skill from scratch, edit, or optimize an existing skill, run evals to test a skill, benchmark skill performance with variance analysis, or optimize a skill's description for better triggering accuracy.Stars: 196kUpdated Claude CodeCodexVerifiedInstall