@benjaminthomas/spec-driven-dev 1.5.1 → 1.7.0

package/README.md

@@ -93,6 +93,23 @@ words in quotes.
 /spec-ship                         "ship it"
 ```
 
+**The right model for each task.** `spec-create` rates every task **light**, **standard**, or
+**deep**, based on how much it touches and how risky it is (data, security, concurrency, public
+contracts, unclear requirements). `spec-implement` then runs each task on the model for its tier:
+
+| Tier | Typical task | Claude Code default |
+|---|---|---|
+| light | copy change, config value, small UI tweak following an existing pattern | `haiku` |
+| standard | a normal feature slice: route + service + tests | `sonnet` |
+| deep | migrations with backfills, auth/permissions, concurrency, cross-repo contracts | `opus` |
+
+- **Reviews:** each batch's review runs on at least `standard`, and on the batch's highest tier.
+- **Escalation:** a task that still fails after a fix round is retried one tier up.
+- **Tools that run one model per session** (Cursor, Codex) don't switch silently. Before a heavier
+  batch, they pause and tell you which model to switch to.
+- **Changing the models:** edit the `models:` section of `.spec-driven.yml`, for example to use a
+  newer model for `deep`.
+
 **Fewer stops:** after reviewing the spec, say **"approved, run it through"**. The workflow then
 implements, verifies, and commits in one go. It stops at the first failure, and it always asks
 before pushing or opening a PR. To make this the default after approval, choose `run-through` during
@@ -116,8 +133,12 @@ say **"run spec-setup"**: that does a deeper version that also reads `CLAUDE.md`
 config, and recent PRs, and fills in what the installer can't (such as each repo's role, or commands
 for stacks other than Node). If a skill finds no config, it runs this setup first.
 
-**What `spec-driven-dev` asks, in order** (every answer comes pre-filled with what it detected, so you
-can usually just press Enter):
+**What `spec-driven-dev` asks, in order.** Each question is a menu: move with **↑/↓**, tick with
+**Space**, and confirm with **Enter**. What it detected is pre-selected and marked *(detected)*, so you
+can usually just press Enter. Repo paths are added one at a time: paste a path (quotes, `~`, and
+Windows paths like `C:\work\api` all work). A path that doesn't exist or isn't a git repo is flagged
+straight away, so you can fix it before moving on. Press Enter on an empty line when you're done.
+**Ctrl+C** cancels without changing anything.
 
 | Question | Detected from | Example answer |
 |---|---|---|
@@ -135,6 +156,7 @@ can usually just press Enter):
 | Lint / typecheck / test / build / dev commands | `package.json` scripts and lockfile (per repo or package) | `pnpm run lint` |
 | Where specs go | (you choose) | `specs/` |
 | After you approve a spec | (you choose) | `stop` (wait at each stage) or `run-through` |
+| Model per task tier | written with defaults: Claude Code `haiku`/`sonnet`/`opus`, others `default` | edit `models:` later |
 
 **Where the file lives, by layout:**
 
@@ -148,12 +170,16 @@ can usually just press Enter):
 example, from inside `/Projects/frontend`:
 
 ```
-Layout — single, monorepo, or multi-repo (detected: single) [single]: multi-repo
-Found 1 git repos under /Projects. Which ones belong to this workspace?
-  1. frontend
-Repos [1]:
-Other repo paths, comma-separated (empty for none): ~/Work/backend, /srv/database
-Where should this workspace's .spec-driven.yml live [~/.spec-driven/frontend-workspace]:
+✔ How is this project organised? › Multiple repos
+✔ Which of these repos (found under /Projects) belong to this workspace? › frontend
+? Add a repo from another folder — paste its path, or press Enter to finish (1 selected) › ~/Work/nope
+  › Folder not found: /Users/you/Work/nope
+? Add a repo from another folder — paste its path, or press Enter to finish (1 selected) › ~/Work/backend
+  ✓ added /Users/you/Work/backend
+? Add a repo from another folder — paste its path, or press Enter to finish (2 selected) › /srv/database
+  ✓ added /srv/database
+? Add a repo from another folder — paste its path, or press Enter to finish (3 selected) ›
+✔ Folder for this workspace's settings file (.spec-driven.yml) › ~/.spec-driven/frontend-workspace
 ```
 
 - **Where the config goes:** the repos' shared parent folder, or `~/.spec-driven/<name>/` when that
@@ -408,7 +434,8 @@ touched by an update.
 Releases are published by this repo's GitHub Actions workflow, not from anyone's laptop, through
 npm [trusted publishing](https://docs.npmjs.com/trusted-publishers). Each version's npm page shows
 a provenance badge linking it to the exact commit and workflow run that built it. The package has
-no dependencies, and it contains only `bin/cli.mjs` and the `skills/` folder.
+one small dependency (`prompts`, for the setup menus), and it contains only `bin/` and the `skills/`
+folder.
 
 **Something isn't working. Where do I start?**
 Run `spec-driven-dev doctor` in your project. It checks the config against your
@@ -462,8 +489,9 @@ can otherwise reuse an older copy it cached. What changed in each version is in
 `npx github:benjaminthomas/spec-driven-dev` installs straight from GitHub instead, for example to
 try an unreleased commit on `main`.
 
-**Requirements:** Node.js 14 or newer and git. The installer has no dependencies, and CI tests it on
-Node 14, 16, 18, 20, 22, and 24.
+**Requirements:** Node.js 14 or newer and git, on macOS, Linux, or Windows (PowerShell or cmd). The
+installer has one small dependency, [`prompts`](https://www.npmjs.com/package/prompts), for its menus.
+CI tests it on Node 14, 16, 18, 20, 22, and 24, and on Windows and macOS.
 
 ### Claude Code (plugin, with automatic updates)
 
@@ -532,15 +560,15 @@ skips that step rather than failing.
 
 | Skill | Stage | SKILL.md lines | Words | Supporting files |
 |---|---|---:|---:|---:|
-| `spec-setup` | 0 · configure | 114 | 1,022 | 1 |
-| `spec-investigate` | 1 · understand | 325 | 2,741 | 1 |
-| `spec-create` | 2 · plan | 157 | 1,415 | 4 |
-| `spec-implement` | 3 · build | 273 | 2,109 | 3 |
+| `spec-setup` | 0 · configure | 117 | 1,068 | 1 |
+| `spec-investigate` | 1 · understand | 330 | 2,794 | 1 |
+| `spec-create` | 2 · plan | 166 | 1,503 | 5 |
+| `spec-implement` | 3 · build | 298 | 2,375 | 3 |
 | `spec-verify` | 4 · prove | 155 | 1,492 | 1 |
 | `spec-checkpoint` | 5 · commit | 108 | 795 | 0 |
 | `spec-ship` | 6 · PR | 220 | 1,268 | 0 |
 | `generative-seo` | standalone | 255 | 2,209 | 7 |
-| **Total** | | **1,607** | **13,051** | **17** |
+| **Total** | | **1,649** | **13,504** | **18** |
 
 - **8** skills: **1** setup + **6** workflow stages + **1** standalone
 - **4** tools supported natively (Claude Code, Codex CLI, Cursor, Antigravity), plus an MCP fallback
@@ -559,7 +587,8 @@ skills/<name>/SKILL.md        the skill itself (frontmatter: name, description,
 skills/<name>/references/     templates and prompts the skill loads when needed
 .claude-plugin/               Claude Code plugin + marketplace manifests
 .agents/skills/               symlinks so Codex/Antigravity pick the skills up inside this repo
-bin/cli.mjs                   the `spec-driven-dev` CLI: installer, setup, doctor, status (no dependencies)
+bin/spec-driven-dev.cjs       launcher (runs on any Node, explains if it's too old)
+bin/cli.mjs                   the `spec-driven-dev` CLI: installer, setup menus, doctor, status
 package.json                  npm package (ships bin/ and skills/)
 mcp-server/                   MCP fallback server
 hooks/hooks.json              Claude Code session-start hook (runs `cli.mjs status`)

package/bin/cli.mjs

@@ -13,7 +13,7 @@ import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
 import { execFileSync } from "node:child_process";
-import { createInterface } from "node:readline";  // callback API: readline/promises needs Node 17+
+import prompts from "prompts";  // arrow-key menus that work in PowerShell, cmd, macOS and Linux terminals
 import { fileURLToPath } from "node:url";
 
 const ROOT = path.dirname(path.dirname(fileURLToPath(import.meta.url)));
@@ -61,19 +61,25 @@ if (flag("help") || flag("h")) {
   process.exit(0);
 }
 
-const rl = YES ? null : createInterface({ input: process.stdin, output: process.stdout });
-async function ask(q, def = "") {
-  if (YES) return def;
-  const a = (await new Promise((resolve) => rl.question(`${q}${def ? ` [${def}]` : ""}: `, resolve))).trim();
-  return a || def;
+// Every question goes through these helpers. With --yes (or answers given as flags) they return the default.
+const cancelled = () => { console.log("\n✗ Setup cancelled. Nothing was changed."); process.exit(1); };
+async function ask(q) { const r = await prompts({ name: "v", ...q }, { onCancel: cancelled }); return r.v; }
+async function askText(message, initial = "", validate) {
+  if (YES) return initial;
+  return String((await ask({ type: "text", message, initial, validate })) ?? "").trim();
 }
-async function pick(q, items, defaults) {
-  items.forEach((it, i) => console.log(`  ${i + 1}. ${it.label}`));
-  const defIdx = items.map((it, i) => (defaults.includes(it.value) ? i + 1 : null)).filter(Boolean).join(",");
-  const a = await ask(`${q} (comma-separated numbers, "all", or "none")`, defIdx || "none");
-  if (a === "all") return items.map((it) => it.value);
-  if (a === "none") return [];
-  return a.split(",").map((n) => items[Number(n.trim()) - 1]?.value).filter(Boolean);
+async function askSelect(message, choices, initialValue) {
+  if (YES) return initialValue;
+  const initial = Math.max(0, choices.findIndex((c) => c.value === initialValue));
+  return ask({ type: "select", message, choices, initial, hint: "↑/↓ then Enter" });
+}
+async function askMulti(message, choices) {
+  if (YES) return choices.filter((c) => c.selected).map((c) => c.value);
+  return ask({ type: "multiselect", message, choices, instructions: false, hint: "↑/↓ move · Space select · A all · Enter confirm" });
+}
+async function askConfirm(message, initial = true) {
+  if (YES) return initial;
+  return ask({ type: "toggle", message, initial, active: "yes", inactive: "no" });
 }
 
 const run = (cmd, argv, cwd) => {
@@ -96,10 +102,8 @@ function copyDir(from, to) {
 async function install() {
   const detected = Object.keys(TOOLS).filter((t) => fs.existsSync(path.join(HOME, TOOLS[t].home)) || onPath(TOOLS[t].bin));
   let tools = opt("tools")?.split(",");
-  if (!tools) {
-    console.log("\nWhich AI coding tools should get the skills? (detected ones are pre-selected)");
-    tools = await pick("Tools", Object.entries(TOOLS).map(([value, t]) => ({ value, label: t.label + (detected.includes(value) ? "  ✓ detected" : "") })), detected);
-  }
+  if (!tools) tools = await askMulti("Which AI coding tools should get the skills?",
+    Object.entries(TOOLS).map(([value, t]) => ({ value, title: t.label + (detected.includes(value) ? "  (installed)" : ""), selected: detected.includes(value) })));
   const bad = tools.filter((t) => !TOOLS[t]);
   if (bad.length) throw new Error(`Unknown tool(s): ${bad.join(", ")} — expected ${Object.keys(TOOLS).join(", ")}`);
 
@@ -110,7 +114,10 @@ async function install() {
     tools = tools.filter((t) => t !== "claude");
   }
 
-  const global = flag("global") || (!YES && (await ask("Install for this project only, or globally for all projects? (project/global)", "project")) === "global");
+  const global = flag("global") || (await askSelect("Install the skills for…", [
+    { title: "This project only", value: false, description: "skills go in this folder, e.g. .cursor/skills/" },
+    { title: "All my projects", value: true, description: "skills go in your home folder, e.g. ~/.cursor/skills/" },
+  ], false));
   const skills = opt("skills")?.split(",") || ALL_SKILLS;
   const unknown = skills.filter((s) => !ALL_SKILLS.includes(s));
   if (unknown.length) throw new Error(`Unknown skill(s): ${unknown.join(", ")} — expected ${ALL_SKILLS.join(", ")}`);
@@ -152,7 +159,7 @@ function findRepos(dir, depth = 2, prefix = "") {
 
 function detectLayout(dir) {
   if (isRepo(dir)) {
-    const top = run("git", ["rev-parse", "--show-toplevel"], dir);
+    const top = path.resolve(run("git", ["rev-parse", "--show-toplevel"], dir));  // C:/x → C:\x on Windows
     const pkg = readJson(path.join(top, "package.json"));
     const cargo = fs.existsSync(path.join(top, "Cargo.toml")) && fs.readFileSync(path.join(top, "Cargo.toml"), "utf8").includes("[workspace]");
     const hasManifest = (rel) => MANIFESTS.some((m) => fs.existsSync(path.join(top, rel, m)));
@@ -228,11 +235,22 @@ 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`;
   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_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" },
+};
 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.
@@ -242,14 +260,25 @@ async function chooseLayout(detected) {
   const forced = opt("layout");
   if (forced && !LAYOUTS.includes(forced)) throw new Error(`--layout must be one of ${LAYOUTS.join(", ")}`);
   if (forced) return forced;
-  for (;;) {
-    const a = await ask(`Layout — single, monorepo, or multi-repo (detected: ${detected})`, detected);
-    if (LAYOUTS.includes(a)) return a;
-    console.log(`  Please type one of: ${LAYOUTS.join(", ")}`);
-  }
+  const tag = (v) => (v === detected ? "  (detected)" : "");
+  return askSelect("How is this project organised?", [
+    { title: `Single repo${tag("single")}`, value: "single", description: "one git repo, one app" },
+    { title: `Monorepo${tag("monorepo")}`, value: "monorepo", description: "one git repo with several apps or packages" },
+    { title: `Multiple repos${tag("multi-repo")}`, value: "multi-repo", description: "several git repos that change together, in any folders" },
+  ], detected);
 }
 
-const expandHome = (p) => p.replace(/^~(?=$|\/)/, HOME);
+const expandHome = (p) => p.replace(/^~(?=$|[\\/])/, HOME);
+// Accept what people paste: surrounding quotes, ~, relative paths, Windows or POSIX separators.
+const cleanPath = (v) => path.resolve(DIR, expandHome(String(v).trim().replace(/^(["'])(.*)\1$/, "$2").trim()));
+const gitTop = (p) => { const t = run("git", ["rev-parse", "--show-toplevel"], p); return t ? path.resolve(t) : p; }; // git prints C:/x on Windows
+function repoPathProblem(v) {
+  if (!String(v || "").trim()) return null;
+  const p = cleanPath(v);
+  if (!fs.existsSync(p)) return `Folder not found: ${p}`;
+  if (!isRepo(p)) return `Not a git repo: ${p}`;
+  return null;
+}
 
 function commonParent(paths) {
   if (!paths.length) return "";
@@ -266,7 +295,7 @@ async function chooseRepos(d) {
   let picked = [];
   const fromFlag = opt("repos");
   if (fromFlag) {
-    picked = splitList(fromFlag).map((p) => path.resolve(DIR, expandHome(p)));
+    picked = splitList(fromFlag).map(cleanPath);
   } else {
     const found = findRepos(scanRoot);
     if (found.length) {
@@ -274,19 +303,25 @@ async function chooseRepos(d) {
       for (const r of found) { const o = gitFacts(path.join(scanRoot, r))?.owner || "?"; (owners[o] = owners[o] || []).push(r); }
       const biggest = Object.values(owners).sort((a, b) => b.length - a.length)[0] || [];
       const here = insideRepo ? [path.relative(scanRoot, d.root)] : [];
-      console.log(`Found ${found.length} git repos under ${scanRoot}. Which ones belong to this workspace?`);
-      picked = (await pick("Repos", found.map((r) => ({ value: r, label: `${r}  (${Object.keys(owners).find((o) => owners[o].includes(r))})` })), [...new Set([...here, ...(insideRepo ? [] : biggest)])]))
+      const pre = new Set([...here, ...(insideRepo ? [] : biggest)]);
+      picked = (await askMulti(`Which of these repos (found under ${scanRoot}) belong to this workspace?`,
+        found.map((r) => { const o = Object.keys(owners).find((k) => owners[k].includes(r)); return { value: r, title: r + (o && o !== "?" ? `  (${o})` : ""), selected: pre.has(r) }; })))
         .map((r) => path.join(scanRoot, r));
     } else if (insideRepo) picked = [d.root];
-    console.log("Repos in other places can be part of the same workspace (e.g. ~/Work/backend, /srv/database).");
-    const extra = await ask("Other repo paths, comma-separated (empty for none)", "");
-    picked.push(...splitList(extra).map((p) => path.resolve(DIR, expandHome(p))));
+    // Repos elsewhere: one path at a time, checked as you type, so a typo can be fixed straight away.
+    if (!YES) for (;;) {
+      const v = await askText(`Add a repo from another folder — paste its path, or press Enter to finish${picked.length ? ` (${picked.length} selected)` : ""}`, "",
+        (x) => repoPathProblem(x) || true);
+      if (!v) break;
+      picked.push(cleanPath(v));
+      console.log(`  ✓ added ${gitTop(cleanPath(v))}`);
+    }
   }
   const abs = [];
   for (const p of [...new Set(picked)]) {
     if (!fs.existsSync(p)) console.log(`  ✗ ${p}: folder not found — skipped`);
     else if (!isRepo(p)) console.log(`  ✗ ${p}: not a git repo — skipped`);
-    else abs.push(run("git", ["rev-parse", "--show-toplevel"], p) || p);
+    else abs.push(gitTop(p));
   }
   if (!abs.length) throw new Error("A multi-repo workspace needs at least one git repo. Re-run setup and pick or add repos (or use --repos=a,b).");
 
@@ -299,7 +334,7 @@ async function chooseRepos(d) {
   const defRoot = opt("workspace") ? path.resolve(DIR, expandHome(opt("workspace")))
     : allUnderScan ? scanRoot
     : tooBroad ? path.join(HOME, ".spec-driven", path.basename(abs[0]) + "-workspace") : parent;
-  const root = path.resolve(DIR, expandHome(await ask("Where should this workspace's .spec-driven.yml live", defRoot)));
+  const root = cleanPath(await askText("Folder for this workspace's settings file (.spec-driven.yml)", defRoot));
   fs.mkdirSync(root, { recursive: true });
   const repos = [...new Set(abs)].map((p) => relOrAbs(root, p));
   console.log(`  Workspace repos: ${repos.join(", ")}`);
@@ -321,9 +356,17 @@ function register(file, repoPaths) {
 async function choosePackages(d) {
   const root = d.root;
   const fromFlag = opt("packages");
-  const answer = fromFlag || (await ask("Package folders, comma-separated, relative to the repo root (empty if none yet)", d.repos.join(",")));
+  let chosen = fromFlag ? splitList(fromFlag) : d.repos.length
+    ? await askMulti("Which packages are part of this monorepo?", d.repos.map((r) => ({ value: r, title: r, selected: true })))
+    : [];
+  if (!fromFlag && !YES) for (;;) {
+    const v = await askText("Add another package folder (relative to the repo root), or press Enter to finish", "",
+      (x) => !String(x || "").trim() || fs.existsSync(path.resolve(root, String(x).trim())) || `Folder not found in ${root}`);
+    if (!v) break;
+    chosen.push(v);
+  }
   const pkgs = [];
-  for (const p of splitList(answer)) {
+  for (const p of chosen) {
     if (fs.existsSync(path.resolve(root, p))) pkgs.push(relOrAbs(root, path.resolve(root, p)));
     else console.log(`  ✗ ${p}: folder not found in ${root} — skipped`);
   }
@@ -342,7 +385,7 @@ async function setup() {
   const { root, repos } = layout === "multi-repo" ? await chooseRepos(d) : layout === "monorepo" ? await choosePackages(d) : { root: d.layout === "multi-repo" ? DIR : d.root, repos: [] };
   if (layout === "single" && !isRepo(root)) console.log(`  • ${root} isn't a git repo — run setup inside the repo, or choose multi-repo.`);
   const file = path.join(root, ".spec-driven.yml");
-  if (fs.existsSync(file) && (await ask(`${file} exists — overwrite? (y/n)`, "n")) !== "y") {
+  if (fs.existsSync(file) && !(await askConfirm(`${file} already exists. Replace it?`, false))) {
     console.log("• Kept the existing config. Run the spec-setup skill in your AI tool to review it.");
     return;
   }
@@ -352,22 +395,44 @@ async function setup() {
   const g = infer(facts);
   if (facts.length) console.log(`Detected: tracker ${g.trackerType}${g.key ? ` (${g.key}-…)` : ""}, base ${g.base}, branches "${g.branchName}", commits ${g.commitStyle}`);
 
-  const trackerType = await ask("Issue tracker (jira/github/linear/none)", g.trackerType);
-  const key = trackerType === "jira" || trackerType === "linear" ? await ask("Ticket key prefix (e.g. STP)", g.key) : "";
-  const url = trackerType === "none" ? "" : await ask("Tracker URL (optional)", "");
-  const base = await ask('Base branch work is cut from ("default" = repo default branch)', g.base);
-  const pr = await ask("Branch PRs target", base);
-  const branchName = await ask("Branch name pattern ({ticket} {slug} {type})", g.branchName);
-  const commitStyle = await ask("Commit style (conventional/ticket/freeform)", g.commitStyle);
-  const specsDir = await ask("Where specs/<feature>/ folders go", "specs");
-  console.log("After you approve a spec, the workflow can stop and wait for you at each stage, or run");
-  console.log("implement → verify → checkpoint in one go (it stops at any failure, and never pushes without asking).");
-  let afterApproval = opt("after-approval");
-  if (!afterApproval) for (;;) {
-    afterApproval = await ask("After approval: stop or run-through", "stop");
-    if (["stop", "run-through"].includes(afterApproval)) break;
-    console.log("  Please type stop or run-through");
-  }
+  const det = (v, d) => (v === d ? "  (detected)" : "");
+  const trackerType = await askSelect("Where do your tickets live?", [
+    { title: `Jira${det("jira", g.trackerType)}`, value: "jira" },
+    { title: `GitHub Issues${det("github", g.trackerType)}`, value: "github" },
+    { title: `Linear${det("linear", g.trackerType)}`, value: "linear" },
+    { title: `No tracker${det("none", g.trackerType)}`, value: "none", description: "work from transcripts, docs, or plain descriptions" },
+  ], g.trackerType);
+  const key = trackerType === "jira" || trackerType === "linear" ? (await askText("Ticket key prefix (the STP in STP-123)", g.key)).toUpperCase() : "";
+  const url = trackerType === "none" ? "" : await askText("Tracker URL (optional, press Enter to skip)", "");
+  const branchChoices = (initial) => [
+    { title: "Each repo's default branch", value: "default", description: "e.g. main or master" },
+    ...[...new Set(facts.map((f) => f.integration).filter(Boolean).concat(initial !== "default" ? [initial] : []))].map((b) => ({ title: b, value: b })),
+    { title: "Another branch…", value: "__other" },
+  ];
+  const pickBranch = async (message, initial) => {
+    const v = await askSelect(message, branchChoices(initial), initial);
+    return v === "__other" ? askText("Branch name", "") : v;
+  };
+  const base = await pickBranch("Which branch is new work started from?", g.base);
+  const pr = await pickBranch("Which branch do pull requests go into?", base);
+  const ex = key || "STP";
+  let branchName = await askSelect("How are work branches named?", [
+    { title: `${ex}-123${det("{ticket}", g.branchName)}`, value: "{ticket}", description: "just the ticket ID" },
+    { title: `feat/${ex}-123-add-login${det("{type}/{ticket}-{slug}", g.branchName)}`, value: "{type}/{ticket}-{slug}" },
+    { title: `feat/add-login${det("{type}/{slug}", g.branchName)}`, value: "{type}/{slug}", description: "no ticket ID" },
+    { title: "Custom pattern…", value: "__custom" },
+  ], g.branchName);
+  if (branchName === "__custom") branchName = await askText("Pattern using {ticket}, {slug}, {type}", g.branchName, (x) => /\{(ticket|slug)\}/.test(x) || "Include {ticket} or {slug}");
+  const commitStyle = await askSelect("How are commit messages written?", [
+    { title: `feat: add login${det("conventional", g.commitStyle)}`, value: "conventional", description: "conventional commits" },
+    { title: `${ex}-123: add login${det("ticket", g.commitStyle)}`, value: "ticket", description: "ticket ID first" },
+    { title: `Add login${det("freeform", g.commitStyle)}`, value: "freeform", description: "no fixed format" },
+  ], g.commitStyle);
+  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" },
+  ], "stop");
 
   const config = {
     layout, tracker: { type: trackerType, key, url }, specsDir, devUrl: "", afterApproval,
@@ -412,7 +477,8 @@ function parseYaml(text) {
     }
     const m = line.match(/^([\w-]+):\s*(.*)$/);
     if (!m) continue;
-    const [, key, val] = m;
+    const [, key, rawVal] = m;
+    const val = rawVal.replace(/(^|\s+)#.*$/, "").trim();  // `key:   # comment` opens a block
     if (val === "") {
       const next = text.split("\n").slice(text.split("\n").indexOf(raw) + 1).find((l) => l.trim() && !l.trim().startsWith("#"));
       parent[key] = next && next.trim().startsWith("- ") ? [] : {};
@@ -445,6 +511,11 @@ function doctor() {
   if (!["single", "monorepo", "multi-repo"].includes(c.layout)) problems.push(`layout "${c.layout}" must be single, monorepo, or multi-repo`);
   if (c.tracker && !["jira", "github", "linear", "none"].includes(c.tracker.type)) problems.push(`tracker.type "${c.tracker.type}" must be jira, github, linear, or none`);
   if (c.git?.commit_style && !["conventional", "ticket", "freeform"].includes(c.git.commit_style)) problems.push(`git.commit_style "${c.git.commit_style}" must be conventional, ticket, or freeform`);
+  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)`);
+  }
   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}`);
   const repos = c.layout === "single" ? [{ path: "." }] : Array.isArray(c.repos) ? c.repos : [];
@@ -504,7 +575,7 @@ try {
   else if (command === "status") status();
   else if (command === "install") {
     await install();
-    if (!flag("no-setup") && (YES || (await ask("\nSet up this project now? (y/n)", "y")) === "y")) await setup();
+    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`);
   if (["install", "setup"].includes(command)) console.log('\nNext: in your AI tool, say "investigate <ticket>" or "create a spec".');
@@ -512,5 +583,4 @@ try {
   console.error(`✗ ${e.message}`);
   process.exitCode = 1;
 } finally {
-  rl?.close();
 }

package/package.json

@@ -1,14 +1,39 @@
 {
   "name": "@benjaminthomas/spec-driven-dev",
-  "version": "1.5.1",
+  "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.",
   "type": "module",
-  "bin": { "spec-driven-dev": "bin/spec-driven-dev.cjs" },
-  "files": ["bin", "skills"],
-  "scripts": { "test": "python3 scripts/check.py && node scripts/test-cli.mjs" },
-  "engines": { "node": ">=14" },
-  "keywords": ["agent-skills", "claude-code", "cursor", "codex", "antigravity", "spec-driven-development", "ai-agents"],
-  "repository": { "type": "git", "url": "git+https://github.com/benjaminthomas/spec-driven-dev.git" },
+  "bin": {
+    "spec-driven-dev": "bin/spec-driven-dev.cjs"
+  },
+  "files": [
+    "bin",
+    "skills"
+  ],
+  "scripts": {
+    "test": "python3 scripts/check.py && node scripts/test-cli.mjs"
+  },
+  "engines": {
+    "node": ">=14"
+  },
+  "keywords": [
+    "agent-skills",
+    "claude-code",
+    "cursor",
+    "codex",
+    "antigravity",
+    "spec-driven-development",
+    "ai-agents"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/benjaminthomas/spec-driven-dev.git"
+  },
   "license": "MIT",
-  "publishConfig": { "access": "public" }
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "prompts": "2.4.2"
+  }
 }

package/skills/spec-create/SKILL.md

@@ -68,6 +68,11 @@ Think carefully about granularity. Too coarse and agents can't work in parallel.
 
 Tests ship with the code they cover: fill in each task's **Tests** section (see the task template) instead of creating separate "write tests" tasks. Only add a standalone testing task for cross-cutting suites (e.g. a new E2E harness) or when the user asks for one.
 
+**Rate each task's complexity.** Read `references/complexity-rubric.md` and give every task a tier
+(`light`, `standard`, or `deep`) with the signals that justify it. `spec-implement` uses the tier to
+pick the model for that task, so a risky task under-rated as `light` is the costly mistake. Round up
+when unsure. If one task scores `deep` mainly because it's doing too much, split it first.
+
 ### Step 4: Build the Dependency Graph
 
 For each task, identify:
@@ -130,6 +135,10 @@ Files created:
 - action-required.md
 - tasks/ ({T} task files)
 
+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}
+
 Batch breakdown:
 - Batch 1: {count} tasks (parallel) — {brief description}
 - Batch 2: {count} tasks (parallel) — {brief description}

package/skills/spec-create/references/complexity-rubric.md

@@ -0,0 +1,57 @@
+# Complexity Rubric
+
+Use this to give every task a **tier**: `light`, `standard`, or `deep`. `spec-implement` runs the
+task on the model mapped to that tier in `.spec-driven.yml` (`models:`). Rate from the evidence in
+the task file and investigation, not from how long the description is.
+
+## Contents
+- Scoring
+- Tier from score
+- Overrides
+- Examples
+- What to write in the task file
+
+## Scoring
+
+Add one point for each signal that applies:
+
+| Signal | Point when… |
+|---|---|
+| Spread | the task changes more than 3 files, or files in more than one module/package/repo |
+| New design | there's no existing pattern in the repo to copy (new abstraction, algorithm, or integration) |
+| Data | it changes a schema, migration, persisted format, or data backfill |
+| Concurrency | it involves async ordering, queues, retries, locking, caching, or idempotency |
+| Security | it touches auth, permissions, tenant isolation, secrets, payments, or untrusted input |
+| Public contract | it changes an API, event, or interface that other code or other repos depend on |
+| Ambiguity | acceptance criteria rely on judgement, or the investigation left UNKNOWNs in this area |
+| Hard to verify | correctness can't be fully shown by the tests listed (timing, performance, UI feel) |
+
+## Tier from score
+
+| Score | Tier | Typical work |
+|---|---|---|
+| 0–1 | `light` | copy change, config value, small UI tweak, adding a field following an existing pattern |
+| 2–3 | `standard` | a normal feature slice: a route + service + tests following existing patterns |
+| 4+ | `deep` | cross-cutting design, migrations with backfills, auth/permission logic, concurrency fixes |
+
+## Overrides
+
+- **Security or Data alone make a task at least `standard`**, even if nothing else applies.
+- **Security + Data, or Security + Concurrency, make it `deep`**, whatever the score.
+- If the score is borderline, round up: a tier too high costs money, a tier too low costs rework.
+
+## Examples
+
+- "Rename the Export button to Download CSV" → 0 → `light`
+- "Add `exported_at` column and show it on the orders page" → Data, Spread → 2 → `standard`
+- "Make the CSV export stream rows instead of loading 10k into memory" → New design, Concurrency, Hard to verify → 3 → `standard`
+- "Enforce tenant isolation on all export endpoints and backfill missing tenant IDs" → Security + Data → `deep`
+
+## What to write in the task file
+
+```markdown
+## Complexity
+
+**Tier:** standard
+**Signals:** Data (adds `exported_at` migration), Spread (api + web)
+```

package/skills/spec-create/references/readme-template.md

@@ -29,10 +29,12 @@ graph TD
 
 ## Batches
 
-| Batch | Tasks | Description |
-|------|-------|-------------|
-| 1 | task-01, task-02 | {Brief description of what this batch accomplishes} |
-| 2 | task-03 | {Brief description} |
+| Batch | Tasks | Tiers | Description |
+|------|-------|-------|-------------|
+| 1 | task-01, task-02 | light, standard | {Brief description of what this batch accomplishes} |
+| 2 | task-03 | deep | {Brief description} |
+
+**Model plan:** {n} light · {n} standard · {n} deep. Deep tasks: {task-03 — reason}.
 
 ## Task Status
 

package/skills/spec-create/references/task-template.md

@@ -15,6 +15,11 @@ pending
 
 {N}
 
+## Complexity
+
+**Tier:** {light | standard | deep}
+**Signals:** {which rubric signals applied, with the evidence — or "none"}
+
 ## Description
 
 {2-5 sentences describing what this task accomplishes and why it matters in the context of the overall feature. Include enough context that an agent unfamiliar with the planning conversation understands the purpose.}
@@ -82,5 +87,6 @@ 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.
+- **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/spec-implement/SKILL.md

@@ -108,6 +108,25 @@ 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.
+- **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:
+  `Batch {N} has deep tasks ({task-nn: reason}). Switch to {models.<tool>.deep} for this batch, then
+  say "continue".` If the batch only has light tasks and you're on the deep model, mention that a
+  cheaper model would do, but carry on.
+- If the mapped value is `default`, use whatever model the session already runs, without
+  recommending a switch.
+
+Report the model used for each task in the batch summary.
+
 **Isolate parallel coders in git worktrees when the host allows it.** Coders sharing one working
 tree can clobber each other's edits and each other's lint/test runs. If your host can run an agent
 in its own worktree (e.g. Claude Code's `isolation: "worktree"`), use it for every coder in a
@@ -143,6 +162,9 @@ Read `references/review-prompt-template.md` and construct the review prompt by f
 - **{task_summaries}**: for each task in this batch, the task title and the coder agent's completion summary
 - **{verification_commands}**: `commands.lint`/`typecheck`/`test` from `.spec-driven.yml` for each repo or package touched, or the project's own commands if there's no config (e.g., `pnpm lint && pnpm typecheck && pnpm test`)
 
+Run the reviewer on the model for the **highest tier in the batch**, and never below `standard`: the
+review is where deep mistakes get caught.
+
 The review agent should:
 1. Run lint, typecheck, and tests
 2. Verify acceptance criteria and the tests named in each task file
@@ -160,6 +182,9 @@ If the review returns **FAIL**:
    - **{issues}**: the specific issues for this task group
    - **{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.
 
 **Cap at 3 review cycles per batch.** If the third review still fails, stop and report to the user:
 

package/skills/spec-investigate/SKILL.md

@@ -288,6 +288,11 @@ gitignores `specs/`, matching whatever this repo already does there). Use the st
 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.
 
+**Complexity Estimate** uses the same signals and tiers `spec-create` will apply per task: spread,
+new design, data, concurrency, security, public contract, ambiguity, hard to verify. Security plus
+data, or security plus concurrency, means `deep`. Say which model is worth planning this on, since a
+deep ticket deserves the strongest model for `spec-create` too.
+
 **Recommended Implementation Direction** describes the technically-supported direction the
 evidence points to — reusing existing patterns the investigation actually found, not a novel
 architecture invented on the spot. It is not permission to start building; flag any business

package/skills/spec-investigate/references/report-template.md

@@ -48,6 +48,11 @@ Copy this structure into `specs/{feature-slug}/investigation.md`.
 ### Proposed Solutions Discussed
 ### Open Questions
 ### Conflicts / Discrepancies
+## Complexity Estimate
+- Overall tier: (light / standard / deep): the tier of the hardest part of the work
+- Signals: (which of spread, new design, data, concurrency, security, public contract, ambiguity, hard to verify apply, each with its evidence)
+- Suggested model for planning this: (the `deep` model if the tier is deep; otherwise the session's model is fine)
+
 ## Recommended Implementation Direction
 ## References
 ```

package/skills/spec-setup/SKILL.md

@@ -69,7 +69,10 @@ Read, don't guess. Collect a draft of every field in `references/config-template
    steps (CI is often the most truthful source). Dev URL from the dev script, `.env.example`, or
    framework defaults.
 
-6. **After approval.** Ask whether an approved spec should stop after each stage (`stop`), or
+6. **Models per tier.** Write the `models:` block from the template. Ask which models the user
+   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
    pushing. Store it as `pipeline.after_approval`.
 

package/skills/spec-setup/references/config-template.yml

@@ -42,6 +42,28 @@ commands:
   dev: ""                       # how spec-verify starts the app
   dev_url: ""                   # where it answers, e.g. http://localhost:3000
 
+# Which model runs each task tier (spec-create rates every task light / standard / deep).
+# Values are whatever your tool accepts; "default" means "whatever model the session is using".
+# Hosts that can pick a model per agent (Claude Code) switch automatically; others (Cursor, Codex)
+# tell you which model to switch to before a heavier batch.
+models:
+  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
+
 pipeline:
   # stop        — every stage waits for you (default)
   # run-through — after you approve a spec: implement → verify → checkpoint in one go,