@benjaminthomas/spec-driven-dev 1.8.0 → 1.10.0

package/plugin/skills/spec-review/SKILL.md

@@ -0,0 +1,131 @@
+---
+name: spec-review
+description: >
+  Review the whole change before it ships: checks the branch diff against the spec (every
+  requirement R1… delivered, nothing out of scope), the project's recorded conventions and
+  off-limits areas, and the code itself (correctness, security, error handling, tests,
+  performance). Writes a ranked review.md with file:line evidence and blocks spec-ship on
+  blockers. Use after spec-verify, when the user says "review this", "code review", "review the
+  branch", "review PR #42", "is this ready to merge", or "/spec-review". Also works with no spec
+  folder, on any branch, diff, or pull request, including a teammate's. Reports findings and offers
+  fixes; it changes code only after the user says yes, through spec-implement's fix loop.
+license: MIT
+---
+
+# Review the change
+
+`spec-implement` reviews each batch as it's built. This skill reviews the **finished whole**, the
+way a careful human reviewer would before merge: does it do what was asked, does it follow how this
+project works, and is the code sound? Every finding is checked against the code before it's
+reported. A short list of real problems beats a long list of guesses.
+
+```
+investigate → create → approve → implement → verify → review → checkpoint → ship
+```
+
+## Project config (read first)
+
+Load `.spec-driven.yml`: walk up from the current directory to the home folder, and the first one
+found wins (a `multi-repo` config only applies inside the repos it lists). If none is found, check
+`~/.spec-driven/workspaces.json`, which maps each multi-repo config to its repo paths. Use the config
+whose repos contain the current directory. Its values beat anything you would detect or assume. This
+skill uses `git` (base branch, PR target), `commands` (lint/typecheck/test), `models`/`effort`,
+`layout`/`repos`, and `specs_dir`.
+
+**Multi-repo:** review each listed repo that has changes on this branch, and write one review.md
+covering all of them. **No config?** Work from the repo itself and say what you assumed.
+
+## Step 1: Work out what to review
+
+| The user gave | Diff to review | Spec |
+|---|---|---|
+| nothing, on a spec's branch | `git diff <merge-base with pr_target>...HEAD`, plus uncommitted changes | `{specs_dir}/{feature}/` matched by branch or ticket |
+| a PR number or URL | `gh pr diff <n>` and `gh pr view <n>` | the PR's linked spec, if any |
+| a branch, commit range, or paths | that diff | none, unless one matches |
+
+No spec? Review against the PR or commit description and the code alone, and say so in the report.
+
+## Step 2: Load only what the review needs
+
+Keep it cheap, because the diff is the expensive part:
+
+1. The README's **Resume here** block, `requirements.md` (requirements R1… and Coverage), and the
+   investigation's **Relevant Context**. Without a spec, read `{specs_dir}/CONTEXT.md` and only the
+   `context/<area>.md` files the diff touches. Never the archive.
+2. `git diff --stat` first, then the diff itself. Open a full file only around a suspected finding,
+   to confirm it.
+3. **Optional graph.** If `context.graph` isn't `off` and graphify is available, use
+   `graphify query "callers of <changed function>" --budget 1000` to find callers the diff didn't
+   update. Treat INFERRED edges as hints to check.
+
+**Model.** Review on at least the `standard` tier (`models.<tool>.standard`), and on `deep` when the
+spec's hardest task is deep or the diff touches auth, payments, personal data, or migrations. A
+review on a weaker model than the code was written with misses things.
+
+## Step 3: Review in four passes
+
+1. **Against the spec.** For each requirement R1…, point to the code that delivers it, or report it
+   as missing. Flag changes no task asked for (scope creep) and task-listed files that weren't
+   touched. Non-goals that got built count as findings.
+2. **Against the project's memory.** Conventions, off-limits areas, and pitfalls from Step 2. A
+   broken recorded convention is a finding. Quote the convention and its source. Check the
+   **commits** too, not just the diff: `git log --format='%h %an <%ae>%n%B' <base>..HEAD` against
+   any recorded rule on commit format, authorship, or trailers.
+3. **The code.** Correctness (logic, edge cases, error paths, races), security (injection, authz,
+   secrets, unsafe input), data safety (migrations, deletes, irreversible writes), tests (behaviour
+   without a test, tests weakened, skipped or deleted), and performance on hot paths only.
+4. **Run the checks.** Run `commands.lint`, `typecheck`, and `test` once if verify didn't just run
+   them on this exact commit. A failing check is a blocker.
+
+**Verify every finding before reporting it.** Re-read the code around it and ask "what concrete
+input or state makes this go wrong?" If you can't name one, drop it or mark it a question. Don't
+report style the linter would catch, or personal taste.
+
+## Step 4: Write the report
+
+Write `{specs_dir}/{feature}/review.md` using `references/report-template.md`. With no spec, write
+`review.md` in the current directory only if the user wants a file; otherwise report in chat.
+
+| Severity | Meaning | Effect |
+|---|---|---|
+| **blocker** | wrong behaviour, a missing requirement, a security or data-loss risk, a failing check | `spec-ship` and run-through stop |
+| **should-fix** | a real problem that's safe to ship but shouldn't stay: a missing test, a broken convention, fragile code | listed in the PR |
+| **nit** | small and optional | listed once, never blocks |
+| **question** | needs the author's intent to judge | asked, never blocks |
+
+Then append one line to `log.md` (counts per severity) and overwrite the README's **Resume here**:
+`Stage: reviewed (B blockers, S should-fix)`, `Next: fix blockers` or `Next: spec-checkpoint`.
+
+## Step 5: Offer fixes (only on a yes)
+
+Tell the user the result:
+
+```
+Reviewed {feature}: {B} blockers · {S} should-fix · {N} nits · {Q} questions → specs/{feature}/review.md
+Fix the blockers and should-fix items now? (y / pick numbers / n)
+```
+
+- **On a yes,** hand the chosen findings to `spec-implement`'s fix loop: grouped by task, one
+  fix agent each, tests run, then review again. Log each fix. After the fixes, re-review only the
+  changed lines and update review.md.
+- **On a no,** stop. Blockers stay open, and `spec-ship` will refuse to open a PR until they're
+  fixed or the user explicitly accepts each one, which is recorded in review.md.
+- **Someone else's PR:** never push to their branch. Offer to post the findings as PR review
+  comments (`gh pr review`), and do it only after the user says yes and has seen the text.
+
+## Run-through
+
+In run-through mode (see `spec-implement`), this runs after verify passes. **Any blocker stops the
+run-through** at this stage with the report. should-fix items don't stop it, but they are listed in
+the final summary. Fixes still need a yes.
+
+## Boundaries
+
+- Reports and asks. Never edits code, commits, or pushes on its own.
+- Writing `review.md`, the log line, and **Resume here** is part of the review, not a code change.
+  Do it even when the user says "don't change anything". Without the file, `spec-ship` can't see
+  the result. Skip it only if the user explicitly says not to write files, and then say the result
+  won't gate shipping.
+- Never posts to a PR, issue, or chat without the user's yes on the exact text.
+- Never weakens a finding to get a pass, and never re-labels a blocker to unblock shipping. Only the
+  user can accept a blocker.

package/plugin/skills/spec-review/references/report-template.md

@@ -0,0 +1,44 @@
+# Review Report Template
+
+Copy this structure into `specs/{feature}/review.md`.
+
+```markdown
+# Review: {feature}
+
+**Result:** {B} blockers · {S} should-fix · {N} nits · {Q} questions
+**Reviewed:** {base}...{head short sha} ({files} files, +{add}/−{del}) on {date}, model {model}
+**Checks:** lint {PASS/FAIL/skipped} · typecheck {…} · test {…}
+
+## Requirements
+
+| Req | Delivered by | Status |
+|---|---|---|
+| R1 | `src/x.ts:40` | ✅ delivered |
+| R2 | — | ❌ missing → finding 1 |
+
+## Findings
+
+### 1. [blocker] {one-line title}
+- **Where:** `path/to/file.ts:123`
+- **Problem:** {what's wrong}
+- **Failure:** {the concrete input or state that makes it go wrong}
+- **Fix:** {the suggested change}
+- **Status:** open  <!-- open | fixed in {sha} | accepted by {user} on {date}: {reason} -->
+
+### 2. [should-fix] …
+
+## Scope
+
+- Unrequested changes: {files or "none"}
+- Task-listed files not touched: {files or "none"}
+
+## Conventions checked
+
+- {convention} ({source}): {followed / broken → finding n}
+```
+
+## Key Points
+
+- Number findings once and never renumber them, so "fix 1 and 3" stays unambiguous across fix rounds.
+- **Status** is how a blocker gets cleared: `fixed in <sha>` after a fix round, or `accepted by <user>` when the user explicitly takes the risk. `spec-ship` refuses while any blocker is `open`.
+- Leave out sections that don't apply, such as Requirements when there's no spec.

package/{skills → plugin/skills}/spec-setup/SKILL.md

@@ -4,17 +4,22 @@ description: >
   One-time discovery that teaches the spec-driven-dev pipeline how THIS project works, and saves
   the answers to .spec-driven.yml — project layout (single repo, monorepo, or multiple repos),
   issue tracker, base branch, PR target, branch naming, commit style, and the lint/typecheck/test/
-  build/dev commands. Use when the user says "set up spec-driven", "configure the pipeline",
-  "spec-setup", "change our branch rules", or when any other spec-* skill finds no
-  .spec-driven.yml. Detects everything it can from the repos first and only asks about what is
-  ambiguous. Writes config only — never changes code, branches, or commits.
+  build/dev commands. It also builds the project's memory: for an existing repo a shallow audit
+  plus one round of questions, for a new one the intended stack and conventions, saved to a small
+  specs/CONTEXT.md that later skills load cheaply. Use when the user says "set up spec-driven",
+  "configure the pipeline", "spec-setup", "audit this repo", "refresh the project context",
+  "change our branch rules", or when any other spec-* skill finds no .spec-driven.yml or no
+  CONTEXT.md. Detects everything it can first and only asks about what is ambiguous. Writes config
+  and context files only — never changes code, branches, or commits.
 license: MIT
 ---
 
 # spec-setup
 
-Learn this project's rules once, save them, and let every other `spec-*` skill reuse them. Team
-rules live in a config file the team can review and change — never in the skills themselves.
+Learn this project's rules and context once, save them, and let every other `spec-*` skill reuse
+them. Team rules live in a config file the team can review and change — never in the skills
+themselves. What the project *knows* (areas, conventions, decisions) lives in
+`{specs_dir}/CONTEXT.md`, kept small so loading it is cheap.
 
 ## Where the config lives
 
@@ -73,8 +78,10 @@ Read, don't guess. Collect a draft of every field in `references/config-template
    has for each tool they installed, only if they want to tune it: the Claude defaults (haiku /
    sonnet / opus) work as-is, and `default` is safe for the rest.
 7. **After approval.** Ask whether an approved spec should stop after each stage (`stop`), or
-   run implement → verify → checkpoint in one go (`run-through`), stopping at any failure and never
+   run implement → verify → review → checkpoint in one go (`run-through`), stopping at any failure and never
    pushing. Store it as `pipeline.after_approval`.
+8. **New or existing project.** Detect it (commit and file counts) and confirm in one line. Store
+   it as `context.project`. This decides what Step 4 does.
 
 ## Step 2 — Confirm in one round
 
@@ -103,6 +110,21 @@ for the rest.
 4. Report: the file path, a one-line summary per section, and "re-run spec-setup any time these
    change".
 
+## Step 4 — Project context
+
+Skip if `{specs_dir}/CONTEXT.md` already exists (offer a refresh instead, see `references/audit.md`).
+
+1. Read `references/audit.md` and follow it: a shallow audit for an existing project, or the
+   intended stack and conventions for a new one. One round of questions, no more.
+2. Write `{specs_dir}/CONTEXT.md` (and any area files) using `references/context-template.md`.
+   Keep the index to 60 lines and area files to 150.
+3. **Offer, don't do:** ask whether to add this one line to `CLAUDE.md` / `AGENTS.md` (whichever
+   the project uses), so hosts reload the pointer after compaction and in every new session:
+   `For spec work, read specs/CONTEXT.md first, then the "Resume here" block of any unfinished spec.`
+   Add it only on a yes.
+4. Re-run `npx -y @benjaminthomas/spec-driven-dev doctor` if available. It checks the size limits
+   and flags context lines that point to files which no longer exist.
+
 ## Updating
 
 Re-running `spec-setup` with an existing config: load it, re-detect, and show only what changed or
@@ -111,7 +133,10 @@ a value the user set by hand.
 
 ## Boundaries
 
-- Writes `.spec-driven.yml` and nothing else. No branches, commits, pushes, installs, or code.
-- Never put secrets, tokens, or credentials in the config.
+- Writes `.spec-driven.yml`, `{specs_dir}/CONTEXT.md` and `{specs_dir}/context/*.md`, plus the
+  one-line pointer in `CLAUDE.md` / `AGENTS.md` only if the user says yes. No branches, commits,
+  pushes, installs, or code. Never installs graphify or anything else.
+- Never put secrets, tokens, or credentials in the config or context files. Ask before saving
+  sensitive business details.
 - A value in the config beats a detected value. If the config looks wrong mid-run (a base
   branch that doesn't exist), the other skills stop and point back here rather than overriding it.

package/plugin/skills/spec-setup/references/audit.md

@@ -0,0 +1,71 @@
+# Repository audit
+
+Builds the first `{specs_dir}/CONTEXT.md`. It is deliberately **shallow**: map the project now,
+and let each feature add detail for the areas it touches. Use the **light** model tier
+(`models.<tool>.light`) where the host can choose a model for a subagent, because this is
+summarising, not reasoning.
+
+## 1. New or existing project?
+
+Use `context.project` from `.spec-driven.yml` if it's set (the npm CLI asks this). Otherwise
+detect it, then confirm in one line instead of asking blind:
+
+- `git rev-list --count HEAD` (commits) and `git ls-files | wc -l` (tracked files).
+- **Existing** if there are 20 or more commits or 50 or more tracked files. **New** otherwise.
+- Ask outright only when it's unclear, for example a fresh repo created from a large template.
+
+Example: "This looks like an existing project (412 commits, 1,830 files). I'll audit it. OK?"
+
+## 2a. Existing project: audit with small outputs
+
+Prefer commands whose output is short over opening files. For a multi-repo workspace, run them per
+repo and give each repo its own row in **Areas**.
+
+| What | How (cheap) |
+|---|---|
+| Layout and size | `git ls-files \| cut -d/ -f1-2 \| sort \| uniq -c \| sort -rn \| head -30` |
+| Stack and commands | manifests (`package.json`, `go.mod`, `pyproject.toml`, …), CI workflow files |
+| Busy areas | `git log --since=6.months --name-only --format= \| cut -d/ -f1-2 \| sort \| uniq -c \| sort -rn \| head -15` |
+| Written rules | `README*`, `CLAUDE.md`, `AGENTS.md`, `CONTRIBUTING.md`, `docs/adr*`, PR templates |
+| Conventions | read 2–3 representative files in the busiest areas, not every file |
+
+**Graph (optional).** If `context.graph` isn't `off` and `graphify-out/graph.json` exists, or
+`graphify` is on the PATH: use it for structure instead of reading code. Prefer
+`graphify query "<question>" --budget 1500` and `graphify path "<A>" "<B>"`, and never load
+`GRAPH_REPORT.md` in full. Treat INFERRED or AMBIGUOUS edges as hints to check, not facts. Never
+install graphify yourself. If it isn't installed and the repo is large (more than about 2,000
+tracked files), mention once: "Optional: graphify (`uv tool install graphifyy`) makes code
+navigation cheaper on big repos." Record the answer as `context.graph: off` if they decline, so you
+never ask again.
+
+## 3. Discovery questions (one round)
+
+Show the draft map first, with each line marked **detected** (with its source) or **guess**. Then
+ask only what the code can't answer, in one message:
+
+- What does the product do, and who uses it?
+- Which areas are legacy, frozen, or off-limits?
+- Known fragile spots or recurring pain?
+- Where is it heading in the next few months?
+- Rules that live in people's heads (e.g. "every API change needs versioning")?
+
+Anything they skip stays out. Don't guess to fill gaps.
+
+## 2b. New project: record intent
+
+There's nothing to audit. Ask about the intended stack, conventions, and architecture choices, and
+save them as the first entries under **Conventions** and **Decisions**, marked `(you told me)`.
+
+## 4. Write and record
+
+- Write `CONTEXT.md` from `context-template.md`, within 60 lines. Create an area file only where
+  you learned more than fits in one line. Most areas start with none.
+- Put the audited commit on the index's header line (`audited at <short sha> (<date>)`).
+- Never write secrets. Ask before saving sensitive business details.
+- Report: the file path, the number of areas, and what was skipped.
+
+## Refresh (re-running the audit)
+
+Never start over. Read the commit on the index's header line, then look at
+`git diff --stat <that commit>..HEAD` and re-check only the areas whose files changed. Update those
+lines, move superseded ones to `context/archive.md`, and update the header commit.

package/{skills → plugin/skills}/spec-setup/references/config-template.yml

@@ -77,8 +77,13 @@ effort:
 
 pipeline:
   # stop        — every stage waits for you (default)
-  # run-through — after you approve a spec: implement → verify → checkpoint in one go,
-  #               stopping at any failure. Pushing / opening the PR (spec-ship) always asks first.
+  # run-through — after you approve a spec: implement → verify → review → checkpoint in one go,
+  #               stopping at any failure or review blocker. Pushing / opening the PR (spec-ship) always asks first.
   after_approval: stop
 
+# Project memory: {specs_dir}/CONTEXT.md (index, ≤60 lines) + {specs_dir}/context/<area>.md (≤150 each).
+context:
+  project: existing             # existing (audited) | new (intent recorded) — set by setup
+  graph: auto                   # auto = use graphify if installed or graphify-out/ exists | off
+
 specs_dir: specs                # where specs/<feature>/ folders go (relative to this file)

package/plugin/skills/spec-setup/references/context-template.md

@@ -0,0 +1,83 @@
+# Project context templates
+
+What the project knows, kept small so it can be loaded cheaply. Two levels:
+
+- `{specs_dir}/CONTEXT.md`: the **index**. **60 lines or fewer.** Read once per stage, only during
+  spec work.
+- `{specs_dir}/context/<area>.md`: details for one area. **150 lines or fewer each.** Read only when
+  a task touches that area.
+- `{specs_dir}/context/archive.md`: old or superseded entries. Never loaded by default.
+
+`spec-driven-dev context` prints the index, and `spec-driven-dev context --areas=billing,auth`
+prints only those area files, with no model needed. `spec-driven-dev doctor` checks the size limits
+and flags paths that no longer exist.
+
+## Rules for writing context
+
+- **Only what the code can't tell you quickly:** decisions and their reasons, conventions, places
+  that are off-limits, pitfalls, product intent. Don't paste code. Point to it as `path:line`.
+- **Every entry gets a date and a source:** `(2026-11-10, spec stp-123)`, `(audit, a1b2c3d)`, or
+  `(you told me)`.
+- **Add at the end of a section.** Don't reorder or reformat what's already there. The start of the
+  file then stays the same, and the host's prompt cache can reuse it.
+- **Over the limit?** Merge duplicates. Move anything superseded or older than about a year to
+  `archive.md`. Never delete a decision without archiving it.
+- **No secrets, keys, tokens, or personal data.** Ask before writing sensitive business details
+  such as customer names or pricing. These files are usually committed.
+- **The code wins.** If code and context disagree, say so in the report and suggest a fix. Never
+  silently rewrite context to match a guess.
+
+## CONTEXT.md (index)
+
+```markdown
+# Project context
+<!-- Index only, 60 lines max. Details live in context/<area>.md. Maintained by spec-* skills. -->
+Project: existing · audited at a1b2c3d (2026-11-10) · graph: none
+
+## Product
+{2–3 lines: what it does, who uses it.}
+
+## Areas
+| Area | Where | What it does | Details |
+|---|---|---|---|
+| billing | `api/src/billing/` | invoices, Stripe webhooks | [billing](context/billing.md) |
+| web | `web/` | React customer app | — |
+
+## Conventions
+- {The handful of rules that apply everywhere, e.g. "errors go through `AppError`" (audit, a1b2c3d)}
+
+## Off-limits / handle with care
+- {e.g. `legacy/` is frozen, no changes without approval (you told me)}
+
+## Decisions
+- {One line each, newest last: decision, reason, (date, source). Long ones go in an area file.}
+
+## Specs
+- {stp-123: retry failed webhooks, touched billing (2026-11-10)}
+```
+
+## context/<area>.md
+
+```markdown
+# {Area}
+<!-- 150 lines max. Loaded only when a task touches this area. -->
+Where: `{paths}` · last checked {date} at {commit}
+
+## How it works
+{A few lines plus `path:line` pointers. Entry points, main flow, data it owns.}
+
+## Conventions
+- {rule} ({date}, {source})
+
+## Decisions
+- {decision}: {why} ({date}, {source})
+
+## Pitfalls
+- {what bit someone, and how to avoid it} ({date}, {source})
+```
+
+## Per-feature: Resume here and log.md
+
+These live in each spec folder. Their templates are readme-template.md and log-template.md in
+the installed `spec-create` skill folder's references/. The README's **Resume here** block (about 10 lines)
+is what a new session reads first. `log.md` is append-only and is never read in full.

package/{skills → plugin/skills}/spec-ship/SKILL.md

@@ -70,6 +70,12 @@ Verify tooling before doing anything else.
      git remote add origin https://github.com/{user}/{repo}.git
    ```
 
+4. **Review blockers?** If this branch belongs to a spec and `specs/{feature}/review.md` exists,
+   stop while any finding is `[blocker]` with `Status: open`. Show those findings and offer: fix them
+   (spec-review's fix step), or have the user accept each one, which is recorded in review.md. If
+   there's no review.md for a spec branch, say so and offer to run `spec-review` first. The user
+   may skip it, and that choice goes in the PR description. List should-fix items in the PR body.
+
 ### Step 1: Detect the Environment
 
 Run these commands to understand the current state:
@@ -193,6 +199,10 @@ EOF
 )"
 ```
 
+If this branch belongs to a spec, overwrite its README's **Resume here** (`Stage: PR open`,
+`Next: review`, the PR URL) and append one line to `log.md`. Commit that only if the user
+agrees; otherwise leave it for the next checkpoint.
+
 ### Step 8: Report
 
 Display the result clearly:

package/{skills → plugin/skills}/spec-verify/SKILL.md

@@ -5,7 +5,7 @@ description: >
   — and checking off every acceptance criterion from its specs/{feature}/ folder one by one. Use
   this after /spec-implement finishes a spec, when the user says "test this end to end",
   "verify this feature actually works", "did we actually build this right", or "/spec-verify",
-  and before /spec-ship or opening a PR. This is the spec-aware sibling of the generic /verify and
+  and before /spec-review, /spec-ship, or opening a PR. This is the spec-aware sibling of the generic /verify and
   /run skills — /verify checks an arbitrary diff's runtime behavior and /run just launches the
   app, but this skill specifically reads a spec's requirements.md and task files, builds a master
   checklist of acceptance criteria, and reports pass/fail per criterion with real evidence
@@ -38,6 +38,14 @@ isn't, detect what this skill needs from the repo, ask about anything ambiguous,
 the answers to `.spec-driven.yml` (keys: `layout`, `repos`, `tracker`, `git`, `commands`,
 `specs_dir`).
 
+## Project context and memory
+
+- Read the README's **Resume here** block first.
+- Where requirements.md numbers its criteria (R1…), group the checklist by requirement and report
+  pass/fail per requirement number.
+- Append each failure and how you confirmed it to `log.md`. When you finish, overwrite
+  **Resume here** (`Verified X/Y`, `Next: spec-checkpoint`, or what to fix first).
+
 ## When there's no spec folder
 
 If the user asks to verify a feature that wasn't built through `spec-create`, don't refuse —
@@ -144,7 +152,7 @@ Then tell the user directly:
 ```
 Verified {feature}: {X}/{Y} criteria passed.
 
-{If all pass:} Ready to ship.
+{If all pass:} Next: spec-review (reviews the whole change before checkpoint and ship).
 {If failures:} {N} failing — see specs/{feature}/verification-report.md for exact repro steps.
 Options: loop back to /spec-implement to fix, or fix manually.
 ```