Spec Driven Workflow

# Create a "Spec Driven Workflow" AI Skill

I want you to help me set up a reusable AI skill that I can use in future conversations. Read the complete skill definition below, then help me install it.

## Complete Skill Definition

# 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

```bash
# 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.

```bash
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.

```bash
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.

```bash
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.

| Consumer | Required precision | Test |
|----------|-------------------|------|
| Engineer on the team who wrote it | Moderate | Shared context fills gaps; acceptance criteria on mandatory requirements only |
| Engineer on another team | High | Every requirement has criteria; no undefined domain terms |
| A model generating the implementation | Very high | Every requirement quantified; no adjective without a number |
| An auditor or regulator | Very high, plus provenance | Every 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.

| Status | Meaning | Action |
|--------|---------|--------|
| `covered` | Implementation and test both annotated | Merge |
| `untested` | Code exists, no test references the ID | Block — this is the state that regresses silently |
| `test-only` | Test exists, no implementation annotated | Usually a missing annotation, occasionally a test asserting nothing |
| `unimplemented` | Neither exists | Block if mandatory; acceptable if explicitly deferred |

### Coverage floors by requirement modality [RECOMMENDED]

| Modality | Keyword | Coverage floor at merge |
|----------|---------|------------------------|
| Mandatory | must, shall | 1.0 — no exceptions; a mandatory requirement without a test is not implemented |
| Recommended | should | 0.8 — deviations recorded in the PR with a reason |
| Optional | may, can | No 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

| Rule | Fires on | Prevents |
|------|----------|----------|
| `unquantified-adjective` | fast, scalable, secure, intuitive | Requirements nobody can fail |
| `passive-no-actor` | "notifications should be delivered" | Obligations with no owning component |
| `no-acceptance-criteria` | Normative statement with no given/when/then | Requirements that cannot be verified |
| `placeholder` | TBD, TODO, ??? | Specs that gate merges while still undecided |
| `compound-requirement` | "and/or", two obligations in one sentence | Partial implementations that still pass |
| `undefined-antecedent` | Opens with it/this/they | Requirements that break when reordered |
| `vague-quantifier` | some, several, most | Disagreement 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

| File | Purpose |
|------|---------|
| `scripts/spec_parse.py` | Parse a markdown spec into requirements with stable IDs and content fingerprints; diff against a baseline |
| `scripts/spec_lint.py` | Flag ambiguity — unquantified adjectives, passive requirements, missing criteria, placeholders |
| `scripts/trace_coverage.py` | Bidirectional spec-to-code coverage with orphan-annotation detection and a merge gate exit code |
| `references/spec-writing-guide.md` | Requirement grammar, acceptance-criteria patterns, and worked ambiguous-to-precise rewrites |
| `references/traceability-model.md` | ID schemes, annotation conventions per language, CI wiring, and drift handling |
| `references/conversation-capture-and-implementation-loop.md` | Turning 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.md` | Runnable sample spec containing both precise and deliberately ambiguous requirements |
| `assets/sample_requirements.json` | Parsed baseline for the drift and coverage workflows |
| `assets/sample_trace_index.json` | Prebuilt trace index exercising covered, untested, test-only, and orphan states |
| `assets/spec-template.md` | Skeleton 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.

---

## What I Need You to Do

First, detect which platform I'm using (Claude.ai, ChatGPT, etc.) and follow the matching instructions below.

### If I'm on Claude.ai:

Walk me through these exact steps:

1. **Create the Project:** Tell me to go to **claude.ai > Projects > Create project** and name it **"Spec Driven Workflow"**

2. **Add Project Knowledge:** Give me the COMPLETE skill definition above as a single copyable text block inside a code fence. Tell me to click **"Add content" > "Add text content"** inside the project, then paste that entire block. Do NOT say "paste from above" -- give me the actual text to copy right there.

3. **Set Custom Instructions:** Tell me to open project settings and paste this exact instruction:
   "You are an expert Spec Driven Workflow in the Engineering domain. Use the project knowledge as your expertise. Follow the workflows, frameworks, and templates defined there. Always provide specific, actionable output."

4. **Test It:** Give me a specific sample prompt I can use inside the new project to verify it works. Pick a real task from the skill's workflows.

### If I'm on ChatGPT:

Walk me through these exact steps:

1. **Create a Custom GPT:** Tell me to go to **chatgpt.com > Explore GPTs > Create**
2. **Configure it:**
   - Name: **"Spec Driven Workflow"**
   - Description: "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."
   - Instructions: Give me the COMPLETE skill definition above as a single copyable text block inside a code fence to paste into the Instructions field. Do NOT say "paste from above."
3. **Test It:** Give me a sample prompt to verify it works.

### If I'm on another platform:
Ask which tool I'm using and adapt the instructions accordingly.

## Important
- Always provide the full skill text in a ready-to-copy code block -- never tell me to "scroll up" or "copy from above"
- Keep the setup steps simple and numbered
- After setup, test it with me using a real workflow from the skill

Source: https://github.com/borghei/Claude-Skills/tree/main/engineering/spec-driven-workflow/SKILL.md