@benjaminthomas/spec-driven-dev 1.8.0 → 1.10.0

package/bin/cli.mjs

@@ -5,10 +5,11 @@
 //   spec-driven-dev                 install + project setup (interactive)
 //   spec-driven-dev setup           project setup only
 //   spec-driven-dev doctor          check .spec-driven.yml against the real repos (exit 1 on problems)
-//   spec-driven-dev status          list specs with unfinished tasks (used by the session-start hook)
+//   spec-driven-dev status          list specs with unfinished work and each one's "Resume here" next step
+//   spec-driven-dev context         print specs/CONTEXT.md; --areas=billing,api prints only those area files
 //   flags: --yes  --global  --tools=claude,cursor  --skills=spec-create,...  --no-setup  --dir=<path>
 //          --layout=single|monorepo|multi-repo  --repos=~/Projects/frontend,/srv/backend  --workspace=<config dir>
-//          --packages=apps/web,packages/ui  --after-approval=stop|run-through  --version
+//          --packages=apps/web,packages/ui  --after-approval=stop|run-through  --project=new|existing  --version
 import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
@@ -17,7 +18,7 @@ import prompts from "prompts";  // arrow-key menus that work in PowerShell, cmd,
 import { fileURLToPath } from "node:url";
 
 const ROOT = path.dirname(path.dirname(fileURLToPath(import.meta.url)));
-const SKILLS_DIR = path.join(ROOT, "skills");
+const SKILLS_DIR = path.join(ROOT, "plugin", "skills");
 const HOME = process.env.SPEC_DRIVEN_HOME || os.homedir(); // overridable for tests
 const ALL_SKILLS = fs.readdirSync(SKILLS_DIR).filter((d) => fs.existsSync(path.join(SKILLS_DIR, d, "SKILL.md")));
 
@@ -33,7 +34,7 @@ const args = process.argv.slice(2);
 const flag = (n) => args.includes(`--${n}`);
 const opt = (n) => args.find((a) => a.startsWith(`--${n}=`))?.split("=")[1];
 const command = args.find((a) => !a.startsWith("-")) || "install";
-const YES = flag("yes") || flag("y") || !process.stdin.isTTY || ["doctor", "status"].includes(command);
+const YES = flag("yes") || flag("y") || !process.stdin.isTTY || ["doctor", "status", "context"].includes(command);
 const DIR = path.resolve(opt("dir") || process.cwd());
 
 if (flag("version") || flag("v")) {
@@ -42,7 +43,7 @@ if (flag("version") || flag("v")) {
 }
 // No terminal to answer in (e.g. `!` in Claude Code, an IDE task, a pipe) and nothing passed explicitly:
 // stop rather than write a config from guesses.
-const ANSWER_FLAGS = ["yes", "y", "layout", "repos", "packages", "tools", "workspace", "after-approval", "skills", "global", "no-setup"];
+const ANSWER_FLAGS = ["yes", "y", "layout", "repos", "packages", "tools", "workspace", "after-approval", "skills", "global", "no-setup", "project"];
 if (["install", "setup"].includes(command) && !process.stdin.isTTY && !args.some((a) => ANSWER_FLAGS.some((f) => a === `--${f}` || a.startsWith(`--${f}=`)))) {
   console.log(`✗ No interactive terminal, so setup can't ask its questions. Nothing was changed.
 
@@ -109,7 +110,7 @@ async function install() {
 
   // Claude Code users who already have the plugin would get every skill twice.
   const plugins = path.join(HOME, ".claude/plugins/installed_plugins.json");
-  if (tools.includes("claude") && !opt("tools") && fs.existsSync(plugins) && fs.readFileSync(plugins, "utf8").includes('"spec-driven-dev@')) {
+  if (tools.includes("claude") && !opt("tools") && fs.existsSync(plugins) && /"(spec-driven-dev|ticket-to-pr)@/.test(fs.readFileSync(plugins, "utf8"))) {
     console.log("• Claude Code already has the spec-driven-dev plugin, so it's skipped here (update it with /plugin).");
     tools = tools.filter((t) => t !== "claude");
   }
@@ -239,7 +240,8 @@ function toYaml(c) {
     .map(([tool, m]) => `  ${tool}:\n` + MODEL_KEYS.map((t) => `    ${t}: ${m[t]}\n`).join("")).join("");
   out += "effort:   # effort / reasoning level per tier (Claude Code, Codex): low | medium | high | xhigh | max | default\n"
     + MODEL_KEYS.map((t) => `  ${t}: ${EFFORT_DEFAULTS[t]}\n`).join("");
-  out += `pipeline:\n  after_approval: ${c.afterApproval || "stop"}   # stop | run-through (implement → verify → checkpoint; ship always asks)\n`;
+  out += `context:   # project memory: {specs_dir}/CONTEXT.md (index) + context/<area>.md\n  project: ${c.project || "existing"}   # existing | new\n  graph: auto   # auto = use graphify if installed | off\n`;
+  out += `pipeline:\n  after_approval: ${c.afterApproval || "stop"}   # stop | run-through (implement → verify → review → checkpoint; ship always asks)\n`;
   return out + `specs_dir: ${y(c.specsDir)}\n`;
 }
 
@@ -381,7 +383,16 @@ async function choosePackages(d) {
   return { root, repos: pkgs };
 }
 
+// shortcut: counts only (no model here), so a big template repo with 1 commit reads as existing; the spec-setup skill confirms.
+function detectProject(dirs) {
+  const n = (d, a) => Number(run("git", a, d).split("\n").filter(Boolean).length);
+  const commits = dirs.reduce((t, d) => t + (Number(run("git", ["rev-list", "--count", "HEAD"], d)) || 0), 0);
+  const files = dirs.reduce((t, d) => t + n(d, ["ls-files"]), 0);
+  return { commits, files, kind: commits >= 20 || files >= 50 ? "existing" : "new" };
+}
+
 async function setup() {
+  if (opt("project") && !["new", "existing"].includes(opt("project"))) throw new Error("--project must be new or existing");
   if (opt("after-approval") && !["stop", "run-through"].includes(opt("after-approval"))) throw new Error("--after-approval must be stop or run-through");
   console.log("\nProject setup — detecting how this project works…");
   const d = detectLayout(DIR);
@@ -439,11 +450,17 @@ async function setup() {
   const specsDir = await askText("Folder for specs (one sub-folder per feature)", "specs");
   const afterApproval = opt("after-approval") || await askSelect("After you approve a spec…", [
     { title: "Stop after each stage", value: "stop", description: "you start implement, verify and checkpoint yourself" },
-    { title: "Run straight through", value: "run-through", description: "implement → verify → commit in one go; stops at any failure, never pushes without asking" },
+    { title: "Run straight through", value: "run-through", description: "implement → verify → review → commit in one go; stops at any failure or review blocker, never pushes without asking" },
   ], "stop");
 
+  const pd = detectProject(repoDirs.filter(isRepo));
+  const project = opt("project") || await askSelect("Is this a new project or an existing one?", [
+    { title: `Existing project${pd.kind === "existing" ? "  (detected)" : ""}`, value: "existing", description: `${pd.commits} commits, ${pd.files} files — your AI tool audits it once and saves what it learns` },
+    { title: `New project${pd.kind === "new" ? "  (detected)" : ""}`, value: "new", description: "nothing to audit — your AI tool asks about the stack and conventions you want" },
+  ], pd.kind);
+
   const config = {
-    layout, tracker: { type: trackerType, key, url }, specsDir, devUrl: "", afterApproval,
+    project, layout, tracker: { type: trackerType, key, url }, specsDir, devUrl: "", afterApproval,
     git: { remote: "origin", base_branch: base, pr_target: pr, branch_name: branchName, commit_style: commitStyle },
     commands: layout === "single" ? commandsFor(repoDirs[0]) : commandsFor(root),
     repos: repos.map((r) => {
@@ -456,7 +473,9 @@ async function setup() {
   if (layout === "multi-repo") register(real(file), repos.map((r) => real(path.resolve(root, r))));
   console.log(`✓ Wrote ${file}`);
   console.log(isRepo(root) ? "  Commit it so your team shares the same rules." : "  This folder isn't a git repo, so the config is personal to this machine.");
-  console.log('  Fill in repo roles, dev_url, and non-Node commands by asking your AI tool to "run spec-setup".');
+  console.log(project === "existing"
+    ? `  Next: ask your AI tool to "run spec-setup". It audits the ${layout === "multi-repo" ? "repos" : "repo"}, asks a few questions, and saves ${specsDir}/CONTEXT.md.`
+    : `  Next: ask your AI tool to "run spec-setup". It asks about your stack and conventions and saves ${specsDir}/CONTEXT.md.`);
 }
 
 // ---------- reading the config ----------
@@ -554,6 +573,10 @@ function doctor() {
   }
   const specs = path.join(root, c.specs_dir || "specs");
   if (!fs.existsSync(specs)) notes.push(`${c.specs_dir || "specs"}/ doesn't exist yet — created on first spec`);
+  if (c.context?.project && !["new", "existing"].includes(c.context.project)) problems.push(`context.project "${c.context.project}" must be new or existing`);
+  if (c.context?.graph && !["auto", "off"].includes(c.context.graph)) problems.push(`context.graph "${c.context.graph}" must be auto or off`);
+  const repoRoots = c.layout === "multi-repo" ? (c.repos || []).map((r) => path.resolve(root, expandHome(r.path))) : [root];
+  checkContext(specs, c.specs_dir || "specs", repoRoots, problems, notes);
   console.log(`Checked ${file}`);
   for (const n of notes) console.log(`  • ${n}`);
   for (const p of problems) console.log(`  ✗ ${p}`);
@@ -561,7 +584,43 @@ function doctor() {
   else console.log("✓ Config matches the repos.");
 }
 
-// Silent unless something is unfinished, so it costs no context in a session start hook.
+const LIMITS = { "CONTEXT.md": 60, area: 150 };
+// Context lines point at code as `path` or `path:line`; flag the ones that no longer exist anywhere in the repos.
+function checkContext(specs, specsName, repoRoots, problems, notes) {
+  const index = path.join(specs, "CONTEXT.md");
+  if (!fs.existsSync(index)) { notes.push(`no ${specsName}/CONTEXT.md yet — ask your AI tool to "run spec-setup" to audit the project`); return; }
+  const areaDir = path.join(specs, "context");
+  const files = [index, ...(fs.existsSync(areaDir) ? fs.readdirSync(areaDir).filter((f) => f.endsWith(".md") && f !== "archive.md").map((f) => path.join(areaDir, f)) : [])];
+  for (const f of files) {
+    const text = fs.readFileSync(f, "utf8");
+    const rel = path.relative(specs, f), max = f === index ? LIMITS["CONTEXT.md"] : LIMITS.area, lines = text.split("\n").length;
+    if (lines > max) problems.push(`${specsName}/${rel} is ${lines} lines (limit ${max}) — merge duplicates or move old entries to context/archive.md`);
+    for (const [, p] of text.matchAll(/`([\w.@-]+(?:\/[\w.@-]+)+\/?)(?::\d+)?`/g)) {
+      if (p.startsWith("context/") || /^(?:https?|www|@)/.test(p)) continue; // @scope/pkg is a package name, not a path
+      if (!repoRoots.some((r) => fs.existsSync(path.join(r, p)))) notes.push(`${specsName}/${rel} mentions \`${p}\`, which no longer exists — stale context?`);
+    }
+  }
+}
+
+function context() {
+  const file = findConfig(DIR);
+  const root = file ? path.dirname(file) : DIR;
+  const specsName = (file && parseYaml(fs.readFileSync(file, "utf8")).specs_dir) || "specs";
+  const index = path.join(root, specsName, "CONTEXT.md");
+  const areas = splitList(opt("areas"));
+  if (!areas.length) {
+    if (!fs.existsSync(index)) { console.log(`No ${specsName}/CONTEXT.md yet. Ask your AI tool to "run spec-setup" to create it.`); return; }
+    process.stdout.write(fs.readFileSync(index, "utf8"));
+    return;
+  }
+  for (const a of areas) {
+    const f = path.join(root, specsName, "context", `${a.replace(/[^\w-]/g, "")}.md`);
+    if (fs.existsSync(f)) process.stdout.write(fs.readFileSync(f, "utf8").replace(/\n*$/, "\n\n"));
+    else console.log(`(no ${specsName}/context/${a}.md — nothing recorded for this area yet)\n`);
+  }
+}
+
+// Silent unless something is unfinished, so it's cheap to run at the start of a session.
 function status() {
   const file = findConfig(DIR);
   const root = file ? path.dirname(file) : DIR;
@@ -575,9 +634,12 @@ function status() {
       continue;
     }
     const t = fs.readFileSync(readme, "utf8");
+    const next = t.match(/^## Resume here[\s\S]*?^- \*\*Next:\*\*\s*(.+)$/m)?.[1]?.trim();
     const done = (t.match(/^\s*- \[x\]/gim) || []).length, todo = (t.match(/^\s*- \[ \]/gm) || []).length;
-    if (todo) lines.push(`- ${specsName}/${name}: ${done}/${done + todo} tasks done → next: spec-implement`);
+    if (todo) lines.push(`- ${specsName}/${name}: ${done}/${done + todo} tasks done → next: ${next || "spec-implement"}`);
     else if (done && !fs.existsSync(path.join(specs, name, "verification-report.md"))) lines.push(`- ${specsName}/${name}: all tasks done, not verified → next: spec-verify`);
+    else if (done && !fs.existsSync(path.join(specs, name, "review.md"))) lines.push(`- ${specsName}/${name}: verified, not reviewed → next: spec-review`);
+    else if (done && /\[blocker\][^\n]*\n(?:(?!###)[^\n]*\n)*?- \*\*Status:\*\* open/.test(fs.readFileSync(path.join(specs, name, "review.md"), "utf8"))) lines.push(`- ${specsName}/${name}: review has open blockers → next: fix them (spec-review)`);
   }
   if (lines.length) console.log(`spec-driven-dev: unfinished work in ${root}\n${lines.join("\n")}`);
 }
@@ -585,11 +647,12 @@ function status() {
 try {
   if (command === "doctor") doctor();
   else if (command === "status") status();
+  else if (command === "context") context();
   else if (command === "install") {
     await install();
     if (!flag("no-setup") && (await askConfirm("Set up this project now?", true))) await setup();
   } else if (command === "setup") await setup();
-  else throw new Error(`Unknown command "${command}" — use install (default), setup, doctor, or status`);
+  else throw new Error(`Unknown command "${command}" — use install (default), setup, doctor, status, or context`);
   if (["install", "setup"].includes(command)) console.log('\nNext: in your AI tool, say "investigate <ticket>" or "create a spec".');
 } catch (e) {
   console.error(`✗ ${e.message}`);

package/package.json

@@ -1,14 +1,14 @@
 {
   "name": "@benjaminthomas/spec-driven-dev",
-  "version": "1.8.0",
-  "description": "Spec-driven AI development workflow (investigate → spec → implement → verify → ship) as Agent Skills for Claude Code, Cursor, Codex CLI and Antigravity.",
+  "version": "1.10.0",
+  "description": "Spec-driven AI development workflow (investigate → spec → implement → verify → review → ship) as Agent Skills for Claude Code, Cursor, Codex CLI and Antigravity.",
   "type": "module",
   "bin": {
     "spec-driven-dev": "bin/spec-driven-dev.cjs"
   },
   "files": [
     "bin",
-    "skills"
+    "plugin/skills"
   ],
   "scripts": {
     "test": "python3 scripts/check.py && node scripts/test-cli.mjs"

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

@@ -49,6 +49,26 @@ issues before proceeding — do not skip or ignore failures.
 
 Iterate until every check passes cleanly. Only then move to the next step.
 
+### Step 2b: Update project context (spec work only)
+
+Skip this step unless the changes belong to a spec (`{specs_dir}/{feature}/` exists for this work).
+
+1. Overwrite the README's **Resume here** (`Stage: committed`, `Next: spec-ship`). Write
+   `Last commit: this checkpoint (git log -1)`, because the commit's hash doesn't exist yet and
+   amending afterwards would change it again.
+2. **When the feature is done** (every task checked) and `{specs_dir}/CONTEXT.md` exists, distil
+   the lasting lessons. Use the light model tier for this where the host lets you pick a subagent
+   model.
+   - Read the feature's `log.md`. This is the one time it's read in full.
+   - Keep only what a future feature in the same area needs: decisions and why, conventions found,
+     pitfalls. Drop routine progress.
+   - Add them to the end of the right `context/<area>.md` (create it if the area has none), and add
+     one line to CONTEXT.md's **Specs** list. Follow the rules in
+     references/context-template.md inside the installed `spec-setup` skill folder (not this repo): dated, with a source, added at the end, within the size
+     limits, superseded lines moved to `context/archive.md`.
+   - Show the context changes in the report so the user can correct them.
+3. No CONTEXT.md? Skip the distilling and suggest running `spec-setup` to create one.
+
 ### Step 3: Stage Everything
 
 Stage all changes — tracked modifications, deletions, and new untracked files:
@@ -65,6 +85,9 @@ anything you don't recognize; skim its diff if you're unsure.
 
 ### Step 4: Craft the Commit Message
 
+Check `{specs_dir}/CONTEXT.md`'s **Conventions** first, if it exists. A recorded rule about commits
+(authorship, trailers, format) beats the defaults below.
+
 Write a commit message in the config's `git.commit_style` (`conventional` → `feat: …`, `ticket` → `STP-123: …` using the ticket ID from the branch name, `freeform`). Without config, follow the project's existing conventions (observed from `git log`). Structure:
 
 - **First line**: clear, concise summary in imperative mood (50-72 chars)

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

@@ -32,6 +32,19 @@ 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
+
+- **Take context from the investigation.** Use `investigation.md`'s **Relevant Context**. Without an
+  investigation, read `{specs_dir}/CONTEXT.md` (or `spec-driven-dev context`) and only the
+  `context/<area>.md` files this feature touches. Never load the archive.
+- **Copy, don't link.** Put only the 3–5 lines each task needs into that task's **Project Context**.
+  Coders never read the context files, which keeps parallel coders from each loading them.
+- **Trace requirements.** Number them R1, R2… (keep the investigation's numbers), fill **Covers** in
+  every task and the **Coverage** table in requirements.md. Don't finish while a requirement has no
+  task.
+- **Start the memory.** Create or extend `log.md` (`references/log-template.md`) and fill the
+  README's **Resume here** block.
+
 ## When to Use
 
 - After a planning conversation where requirements and technical details have been discussed
@@ -92,6 +105,7 @@ specs/{feature-name}/
 ├── README.md
 ├── requirements.md
 ├── action-required.md
+├── log.md
 └── tasks/
     ├── task-01-{name}.md
     ├── task-02-{name}.md
@@ -103,6 +117,7 @@ Read the templates in `references/` before writing each file:
 - `references/task-template.md` — for each task file (self-contained with all context)
 - `references/requirements-template.md` — for the requirements document
 - `references/action-required-template.md` — for manual human steps
+- `references/log-template.md` — for the append-only log
 
 Task files are numbered with zero-padded two-digit prefixes in topological order: Batch 1 tasks first, then Batch 2, etc. Within a batch, order is arbitrary but stable.
 
@@ -135,6 +150,7 @@ Files created:
 - action-required.md
 - tasks/ ({T} task files)
 
+Coverage: R1–R{n} all mapped to tasks
 Model plan: {n} light · {n} standard · {n} deep
   (models from .spec-driven.yml → light: {model}, standard: {model}, deep: {model})
   Deep tasks: {task-nn — main reason}
@@ -149,7 +165,7 @@ Next steps:
 2. Review the requirements and task files
 3. When you're happy with it, either:
    - say "implement" to build it and stop for review, or
-   - say "approved, run it through" to build, verify and commit in one go (stops at any failure,
+   - say "approved, run it through" to build, verify, review and commit in one go (stops at any failure,
      never pushes without asking)
 ```
 
@@ -163,4 +179,5 @@ by default after approval. Never start implementing from this skill.
 - Tasks within the same batch must not modify overlapping files. Parallel agents on the same branch cannot safely touch the same files.
 - Keep tasks atomic — one concern per task. If a task has more than 5-7 files to modify, consider splitting it.
 - Put tests in each task's Tests section, not in separate testing tasks (unless the user asks, or it's a cross-cutting suite).
+- Every requirement (R1…) maps to at least one task, and every task lists what it **Covers**.
 - Number task files in topological order (batch 1 first, then batch 2, etc.) for easy scanning.

package/plugin/skills/spec-create/references/log-template.md

@@ -0,0 +1,27 @@
+# Log Template
+
+`specs/{feature}/log.md` keeps what would otherwise live only in the chat: decisions, deviations,
+answers from the user, review findings, and dead ends. Without it, those are lost when the session
+ends or the conversation is compacted.
+
+**Rules**
+- **Append only.** Add entries at the bottom. Never rewrite or reorder.
+- **Never read it in full.** A new session reads the README's **Resume here** block. Read the log's
+  last ~20 lines only when Resume here isn't enough.
+- **One to three lines per entry.** Point to files as `path:line`. Don't paste code.
+- **Log what's worth keeping:** a decision and its reason, a change from the spec, the user's answer
+  to a question, a review finding and its fix, an approach that failed and why. Skip routine
+  progress, which the checkboxes already show.
+
+## Template
+
+```markdown
+# Log: {Feature Name}
+
+- 2026-11-10 spec-create · Created spec: {N} tasks in {B} batches. Covers R1–R{n}.
+- 2026-11-10 spec-implement · Decision: reuse `retryWithBackoff` (`src/lib/retry.ts:12`) instead of a new helper. The user asked for it.
+- 2026-11-10 spec-implement · Deviation: task-03 also touches `src/api/routes.ts`, because the route table lives there.
+- 2026-11-11 spec-verify · R3 failed: webhook retried 5 times, not 3. Fixed in task-04 and re-verified.
+```
+
+Each entry has the date, the skill that wrote it, then what happened and why.

package/{skills → plugin/skills}/spec-create/references/readme-template.md

@@ -7,6 +7,15 @@ Use this structure for the README.md at the root of each spec folder. The README
 ```markdown
 # {Feature Name}
 
+## Resume here
+
+<!-- Overwritten by each spec-* skill when it finishes. A new session reads this first. Keep it ~10 lines. -->
+- **Stage:** spec created, awaiting approval
+- **Next:** review the spec, then say "implement" (or "approved, run it through")
+- **Open questions:** {none, or one line each}
+- **Last commit:** {short sha, or "none yet"}
+- **Areas:** {context areas this feature touches, e.g. billing, api}
+
 ## Overview
 
 {One paragraph summary of what the feature does and why it exists.}
@@ -15,6 +24,7 @@ Use this structure for the README.md at the root of each spec folder. The README
 
 - [Requirements](./requirements.md) — full requirements and acceptance criteria
 - [Action Required](./action-required.md) — manual steps needing human action
+- [Log](./log.md) — decisions, deviations and review findings (append-only)
 
 ## Dependency Graph
 
@@ -48,6 +58,8 @@ graph TD
 
 ## Key Points
 
+- **Resume here** is the cheap way back in. Every `spec-*` skill overwrites it when it finishes (stage, next action, open questions, last commit), so a new or compacted session reads ~10 lines instead of the whole history. `spec-driven-dev status` prints each spec's **Next** line.
+
 - The **Dependency Graph** uses Mermaid syntax (widely rendered in GitHub, VS Code, etc.). Each node shows the task number and title for quick reference.
 - The **Batches** table provides a scannable overview of what runs in parallel.
 - The **Task Status** section uses markdown checkboxes that the `spec-implement` skill updates as tasks complete. The orchestrator parses these to determine which batch to resume from.

package/{skills → plugin/skills}/spec-create/references/requirements-template.md

@@ -26,11 +26,18 @@ Use this structure for the requirements.md at the root of each spec folder.
 
 ## Acceptance Criteria
 
-{High-level criteria for the entire feature. Individual task files have their own granular criteria.}
+{High-level criteria for the entire feature, numbered R1, R2… so tasks and verification can point to them. Keep the numbers from investigation.md if it has them. Individual task files have their own granular criteria.}
 
-- [ ] {Criterion 1}
-- [ ] {Criterion 2}
-- [ ] {Criterion 3}
+- [ ] R1: {Criterion 1}
+- [ ] R2: {Criterion 2}
+- [ ] R3: {Criterion 3}
+
+## Coverage
+
+| Requirement | Tasks |
+|---|---|
+| R1 | task-01, task-03 |
+| R2 | task-02 |
 
 ## Assumptions
 
@@ -51,4 +58,5 @@ Use this structure for the requirements.md at the root of each spec folder.
 
 - The requirements doc provides **overall feature context** that each coder agent receives alongside its task file. Keep it focused on the "what" and "why" — individual task files handle the "how."
 - Non-goals are important: they prevent agents from over-building. If search functionality is out of scope, say so — otherwise a well-meaning agent might add it.
+- **Every requirement must map to at least one task.** `spec-create` doesn't finish while the Coverage table has a requirement with no task, and `spec-verify` reports pass/fail per requirement number.
 - Acceptance criteria here are feature-level (the whole thing works end-to-end). Task-level criteria live in each task file.

package/{skills → plugin/skills}/spec-create/references/task-template.md

@@ -15,6 +15,10 @@ pending
 
 {N}
 
+## Covers
+
+{Requirement numbers from requirements.md this task delivers, e.g. R1, R3.}
+
 ## Complexity
 
 **Tier:** {light | standard | deep}
@@ -31,6 +35,12 @@ pending
 
 **Context from dependencies:** {Prose summary of what the dependency tasks produce that this task needs. For example: "task-01-setup-database.md creates the PostgreSQL schema with users and sessions tables. This task builds the API routes that query those tables." This is what makes each file self-contained — the agent does not need to read other task files to understand its inputs.}
 
+## Project Context
+
+{Only the 3–5 lines from the project context (CONTEXT.md / context/<area>.md, via the investigation's Relevant Context) that apply to THIS task: conventions, pitfalls, off-limits areas. The coder never reads the context files itself. Write "None" if nothing applies.}
+
+- {e.g. Errors go through `AppError` (`src/lib/errors.ts:8`); never throw raw strings.}
+
 ## Files to Create
 
 - `path/to/new-file.ts` — {Brief purpose}
@@ -87,6 +97,8 @@ pending
 - The **Dependencies** section includes prose context (not just filenames) so the agent understands its inputs without reading other files. This is the most important part of making task files self-contained.
 - **Files to Create** and **Files to Modify** make the task's scope explicit. Tasks in the same batch should not overlap on these lists.
 - **Technical Details** captures everything from the planning conversation — CLI commands, schemas, code snippets, file paths, env vars, API endpoints. If it was discussed during planning and is relevant to this task, it belongs here.
+- **Covers** links the task to requirement numbers, so nothing in requirements.md is left without a task.
+- **Project Context** carries just the conventions this task needs. Copy lines; don't link to CONTEXT.md, because parallel coders reading the whole context would multiply the token cost.
 - **Complexity** comes from `complexity-rubric.md`. `spec-implement` picks the coder's model from this tier, so rate honestly: under-rating a risky task is the expensive mistake.
 - **Tests** names the tests the coder writes alongside the code. A behavioural acceptance criterion without a matching test is a gap — add the test or explain why it can only be checked by `spec-verify`.
 - **Acceptance Criteria** should be specific enough that completion can be verified objectively (by a code review agent or a human).

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

@@ -38,6 +38,20 @@ 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
+
+- **Start cheap.** Read the README's **Resume here** block first. Read the last ~20 lines of
+  `log.md` only if that isn't enough. You, the orchestrator, read `{specs_dir}/CONTEXT.md` once,
+  because its **Conventions** and **Off-limits** apply to your own work too: commit messages and
+  trailers, branches, files nobody may touch. Coders don't read it. Each task file's **Project
+  Context** already carries what its coder needs. Open one `context/<area>.md` only when a review
+  finding depends on a convention the task file doesn't state.
+- **Log as you go.** Append 1–3 lines to `log.md` for each decision, deviation from the spec, user
+  answer, review finding and fix, or failed approach. Skip routine progress.
+- **Before stopping for any reason** (batch done, failure, user stop, run-through gate), overwrite
+  **Resume here** with the stage, next action, open questions, and last commit. A new or compacted
+  session must be able to continue from that block alone.
+
 ## Orchestration Model
 
 This skill's parallelism assumes your host can run multiple independent agents at once —
@@ -209,12 +223,14 @@ After the batch passes review (or the user chooses to proceed):
 
 1. **Update task files**: for each completed task, change the Status field from `pending` to `complete`
 2. **Update README.md**: change `- [ ]` to `- [x]` for each completed task
-3. **Commit the batch**:
+3. **Update memory**: append a log entry (what this batch decided or changed from the spec) and
+   overwrite the README's **Resume here** (`Stage: batch {N}/{total} done`, `Next: …`).
+4. **Commit the batch**:
    ```
    git add -A
    git commit -m "feat({feature}): complete batch {N} — {brief summary}"   # or the config's git.commit_style
    ```
-4. **Report batch completion**:
+5. **Report batch completion**:
    ```
    Batch {N} of {total} complete.
 
@@ -254,7 +270,7 @@ Next steps:
 
 ## Run-through mode (after approval)
 
-Run-through applies when the user asks for it ("approved, run it through", "build, verify and
+Run-through applies when the user asks for it ("approved, run it through", "build, verify, review and
 commit it") or when `.spec-driven.yml` has `pipeline.after_approval: run-through` and the user has
 approved the spec. In that case, don't stop after Step 9. Continue:
 
@@ -262,16 +278,18 @@ approved the spec. In that case, don't stop after Step 9. Continue:
 Run-through progress:
 - [ ] Implement all batches (Steps 1–9) — every review gate passed
 - [ ] Verify — follow the spec-verify skill; every acceptance criterion PASS
+- [ ] Review — follow the spec-review skill; no blockers (should-fix items are listed, not blocking)
 - [ ] Checkpoint — follow the spec-checkpoint skill; every check passes, commit made
 - [ ] Stop and hand off to spec-ship
 ```
 
 1. **Gate on each stage.** Move on only if the previous stage fully passed. On any failure (a review
-   gate exhausted its 3 cycles, a criterion FAILed or was SKIPPED, a check failed), stop the
+   gate exhausted its 3 cycles, a criterion FAILed or was SKIPPED, spec-review found a blocker, a
+   check failed), stop the
    run-through and report where it stopped, why, and the command to resume (e.g. "fix X, then say
    'continue the run-through'").
-2. **Verify, then checkpoint.** Follow those skills' own instructions in full, including the
-   verification report. Don't shortcut them because you're running them in sequence.
+2. **Verify, review, then checkpoint.** Follow those skills' own instructions in full, including
+   the verification report and review.md. Review fixes still need the user's yes. Don't shortcut them because you're running them in sequence.
 3. **Never push.** The run-through ends at a local commit. Finish with the summary below and ask
    whether to run `spec-ship`. `spec-ship` still shows exactly what will be pushed and waits for a
    yes.
@@ -282,6 +300,7 @@ Run-through progress:
 Run-through complete for "{feature}":
 - Implement: {N} batches, all review gates PASS
 - Verify: {P}/{P} criteria PASS (specs/{feature}/verification-report.md)
+- Review: 0 blockers · {S} should-fix · {N} nits (specs/{feature}/review.md)
 - Checkpoint: {commit hash} — {subject}
 
 Ready to push and open a PR. Run spec-ship? (it will show exactly what gets pushed first)

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

@@ -8,9 +8,9 @@ description: >
   plan it", or hands over any of those inputs and wants the
   system understood (current behaviour, root cause, affected repos/files, risks, open
   questions) rather than fixed or built yet. This is the first stage of the
-  investigate → create → (human approval) → implement → verify → ship pipeline — it hands off
+  investigate → create → (human approval) → implement → verify → review → ship pipeline — it hands off
   to the existing spec-create skill and does not replace, duplicate, or invoke spec-create,
-  spec-implement, spec-verify, or spec-ship itself. Ticket-agnostic: works for bugs, features,
+  spec-implement, spec-verify, spec-review, or spec-ship itself. Ticket-agnostic: works for bugs, features,
   refactors, security, performance, infra, or cross-repository tickets in any repo.
 license: MIT
 ---
@@ -22,11 +22,11 @@ Discover and record the facts. Do not design the fix and do not write any code.
 This skill is stage 1 of:
 
 ```
-spec-investigate → spec-create → human approval → spec-implement → spec-verify → spec-ship
+spec-investigate → spec-create → human approval → spec-implement → spec-verify → spec-review → spec-checkpoint → spec-ship
 ```
 
-`spec-create`, `spec-implement`, `spec-verify`, and `spec-ship` already exist elsewhere (e.g. the
-`spec-driven-dev` plugin, or whatever equivalent this host provides). **Never create, redesign,
+`spec-create`, `spec-implement`, `spec-verify`, `spec-review`, and `spec-ship` already exist elsewhere (e.g. the
+`ticket-to-pr` plugin, or whatever equivalent this host provides). **Never create, redesign,
 duplicate, or invoke those skills from here.** Your only output is an investigation report plus a
 ready-to-use work branch; a human decides when to run `spec-create` next.
 
@@ -45,6 +45,26 @@ 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 (read before investigating)
+
+Cheap sources first, code second:
+
+1. Read `{specs_dir}/CONTEXT.md`, the index of 60 lines or fewer, or run
+   `spec-driven-dev context`. Pick the areas this work touches and read only those
+   `context/<area>.md` files (`spec-driven-dev context --areas=billing,api`). Never load
+   `context/archive.md`.
+2. **Optional graph.** If `context.graph` isn't `off` and graphify is available
+   (`graphify-out/graph.json` exists or `graphify` is on the PATH), map the system with
+   `graphify query "<topic>" --budget 1500` and `graphify path "<A>" "<B>"` before grepping. Treat
+   INFERRED or AMBIGUOUS edges as hints. Never install it.
+3. **Context is a lead, not evidence.** Verify it against the code like any other source. Where the
+   code contradicts it, record that under **Relevant Context → Context corrections**. Don't edit
+   CONTEXT.md from here.
+4. Copy the 10–20 lines that apply into the report's **Relevant Context** section. That digest is
+   what later stages use, so they don't reload the context files.
+
+No CONTEXT.md? Investigate as usual, and suggest running `spec-setup` afterwards to create one.
+
 ## Invocation
 
 ```
@@ -285,6 +305,10 @@ needed — this mirrors where `spec-create` already keeps its own output, so the
 naturally from the same place; don't commit this folder if the repo's convention already
 gitignores `specs/`, matching whatever this repo already does there). Use the structure in `references/report-template.md`.
 
+Number the **Potential Requirements** R1, R2… so `spec-create` and `spec-verify` can trace
+each one. Start `{specs_dir}/{feature-slug}/log.md` (append-only; template: references/log-template.md inside the installed
+`spec-create` skill folder, next to its SKILL.md, not in this repo) with one entry: the date, `spec-investigate`, and the headline finding.
+
 Every section should be specific and evidence-backed, or explicitly say "None found" /
 "Not applicable to this ticket" rather than being left looking like an oversight.
 

package/{skills → plugin/skills}/spec-investigate/references/report-template.md

@@ -16,6 +16,12 @@ Copy this structure into `specs/{feature-slug}/investigation.md`.
 - Base Branch:
 - Base Commit:
 
+## Relevant Context
+<!-- 10–20 lines max: only what applies to this work, copied from specs/CONTEXT.md and context/<area>.md. spec-create passes these on to task files. -->
+- Areas: (e.g. billing, api)
+- Conventions / decisions / pitfalls that apply: (one line each, with the source)
+- Context corrections: (where the code contradicts CONTEXT.md, with evidence; or "none")
+
 ## Business Context
 ## Problem Statement
 ## Expected Behaviour
@@ -45,6 +51,7 @@ Copy this structure into `specs/{feature-slug}/investigation.md`.
 ### Business Decisions
 ### Technical Decisions
 ### Potential Requirements
+(Number them R1, R2… so spec-create and spec-verify can trace each one.)
 ### Proposed Solutions Discussed
 ### Open Questions
 ### Conflicts / Discrepancies