@benjaminthomas/spec-driven-dev 1.7.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");
   }
@@ -235,22 +236,31 @@ function toYaml(c) {
   out += `tracker:\n  type: ${c.tracker.type}\n  key: ${y(c.tracker.key)}\n  url: ${y(c.tracker.url)}\n`;
   out += `git:\n${cmds(c.git, "  ")}\n`;
   out += `commands:\n${cmds(c.commands, "  ")}\n  dev_url: ${y(c.devUrl)}\n`;
-  out += "models:   # model per task tier (light / standard / deep); \"default\" = the session's model\n" + Object.entries(MODEL_DEFAULTS)
-    .map(([tool, m]) => `  ${tool}:\n` + TIERS.map((t) => `    ${t}: ${m[t]}\n`).join("")).join("");
-  out += `pipeline:\n  after_approval: ${c.afterApproval || "stop"}   # stop | run-through (implement → verify → checkpoint; ship always asks)\n`;
+  out += "models:   # model per task tier; \"default\" = the session's model; escalate = last resort for repeat failures\n" + Object.entries(MODEL_DEFAULTS)
+    .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 += `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`;
 }
 
 const LAYOUTS = ["single", "monorepo", "multi-repo"];
 const TIERS = ["light", "standard", "deep"];
-// Aliases, not dated model IDs, so they keep pointing at the current models. Other tools default to
-// the session's own model; spec-implement then tells you when to switch.
+const MODEL_KEYS = [...TIERS, "escalate"]; // escalate: optional last resort when a deep task keeps failing
+const EFFORTS = ["low", "medium", "high", "xhigh", "max", "default"];
+// Checked against the vendors' docs on 2026-11-06 (Claude Code model-config, OpenAI Codex config,
+// Cursor models page). Claude Code aliases track the newest model per family on your provider.
+// Cursor's models depend on your plan, so it defaults to the session's model.
+// shortcut: model names go stale; refresh these defaults (and the README table) when vendors ship new lines.
 const MODEL_DEFAULTS = {
-  claude: { light: "haiku", standard: "sonnet", deep: "opus" },
-  cursor: { light: "default", standard: "default", deep: "default" },
-  codex: { light: "default", standard: "default", deep: "default" },
-  antigravity: { light: "default", standard: "default", deep: "default" },
+  claude: { light: "haiku", standard: "sonnet", deep: "opus", escalate: "fable" },
+  codex: { light: "gpt-6-luna", standard: "gpt-6.1-sol", deep: "gpt-6.1-sol", escalate: "default" },
+  cursor: { light: "default", standard: "default", deep: "default", escalate: "default" },
+  antigravity: { light: "default", standard: "default", deep: "default", escalate: "default" },
 };
+// Effort / reasoning level per tier, for tools that support it (Claude Code, Codex).
+const EFFORT_DEFAULTS = { light: "low", standard: "medium", deep: "high", escalate: "xhigh" };
 const splitList = (v) => (v || "").split(",").map((x) => x.trim()).filter(Boolean);
 // Paths are stored relative to the config's folder when inside it, absolute otherwise.
 const real = (p) => { try { return fs.realpathSync(p); } catch { return p; } }; // /var vs /private/var etc.
@@ -373,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);
@@ -431,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) => {
@@ -448,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 ----------
@@ -514,7 +541,11 @@ function doctor() {
   for (const [tool, m] of Object.entries(c.models || {})) {
     if (typeof m !== "object") { problems.push(`models.${tool} must list light / standard / deep`); continue; }
     for (const t of TIERS) if (!m[t]) problems.push(`models.${tool}.${t} is missing (use "default" for the session's model)`);
-    for (const k of Object.keys(m)) if (!TIERS.includes(k)) problems.push(`models.${tool}.${k}: unknown tier (use light, standard, deep)`);
+    for (const k of Object.keys(m)) if (!MODEL_KEYS.includes(k)) problems.push(`models.${tool}.${k}: unknown tier (use light, standard, deep, escalate)`);
+  }
+  for (const [k, v] of Object.entries(c.effort || {})) {
+    if (!MODEL_KEYS.includes(k)) problems.push(`effort.${k}: unknown tier (use light, standard, deep, escalate)`);
+    else if (!EFFORTS.includes(v)) problems.push(`effort.${k} "${v}" must be one of ${EFFORTS.join(", ")}`);
   }
   if (c.pipeline?.after_approval && !["stop", "run-through"].includes(c.pipeline.after_approval)) problems.push(`pipeline.after_approval "${c.pipeline.after_approval}" must be stop or run-through`);
   if (c.git?.branch_name && !/\{(ticket|slug)\}/.test(c.git.branch_name)) problems.push(`git.branch_name "${c.git.branch_name}" needs {ticket} or {slug}`);
@@ -542,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}`);
@@ -549,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;
@@ -563,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")}`);
 }
@@ -573,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.7.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 —
@@ -108,14 +122,17 @@ Read `references/coder-prompt-template.md` and construct each agent's prompt by
 
 The coder agents should NOT commit their changes — the orchestrator handles commits after review.
 
-**Pick each coder's model from the task's tier.** Read the task's `## Complexity` tier (treat a
-missing tier as `standard`) and look up the model in `.spec-driven.yml` → `models.<tool>.<tier>`,
-where `<tool>` is the host you're running in (`claude`, `codex`, `cursor`, `antigravity`). Without a
-`models` section, use `models.claude` defaults: `light → haiku`, `standard → sonnet`,
-`deep → opus`.
-
-- **Host can set a model per agent** (e.g. Claude Code's Agent tool `model` parameter): dispatch
-  each coder with its tier's model.
+**Pick each coder's model and effort from the task's tier.** Read the task's `## Complexity` tier
+(treat a missing tier as `standard`), then look up `.spec-driven.yml` → `models.<tool>.<tier>` and
+`effort.<tier>`, where `<tool>` is the host you're running in (`claude`, `codex`, `cursor`,
+`antigravity`). Without those sections, use these defaults: Claude Code `light → haiku/low`,
+`standard → sonnet/medium`, `deep → opus/high`; other hosts use the session's model.
+
+- **Host can set a model per agent** (e.g. Claude Code's Agent tool `model` and `effort`
+  parameters): dispatch each coder with its tier's model and effort.
+- **Model not available** (not on your plan or provider, or rejected by the host): fall back to the
+  session's model, say which task fell back and why, and suggest fixing `models:`. Don't stop the
+  batch for this.
 - **Host can't** (one model per session, as in Cursor or Codex): don't silently run deep tasks on a
   light model. Before dispatching a batch, compare its highest tier with the model you're running
   on. If the batch needs a stronger one, stop and say:
@@ -183,8 +200,10 @@ If the review returns **FAIL**:
    - **{task_content}**: the original task file for context
 4. After fix agents complete, re-run the review (Step 6)
 5. **Escalate on repeat failure.** If a task's issues survive a fix cycle, run its next fix one tier
-   higher (`light → standard → deep`). Note the escalation in the batch report. When a task needed
-   escalating, its tier was probably wrong, which is useful feedback for future specs.
+   higher (`light → standard → deep`). A `deep` task that still fails goes to `models.<tool>.escalate`
+   (e.g. `fable`) at `effort.escalate`, if it's set and not `default`. Ask first if that model can
+   bill to usage credits, as Fable can on some plans. Note every escalation in the batch report:
+   a task that needed escalating was probably under-rated, which is useful feedback for future specs.
 
 **Cap at 3 review cycles per batch.** If the third review still fails, stop and report to the user:
 
@@ -204,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.
 
@@ -249,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:
 
@@ -257,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.
@@ -277,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)