@benjaminthomas/spec-driven-dev 1.4.1 → 1.5.0

package/README.md

@@ -12,8 +12,8 @@ the PR.
 It's a set of eight [Agent Skills](https://agentskills.io), plain Markdown instruction files that
 AI coding tools load on demand. It works with Claude Code, Codex CLI, Cursor, and Google Antigravity,
 in any language or framework, and in a single repo, a monorepo, or several repos that change
-together. Install it from npm with `npm install -g @benjaminthomas/spec-driven-dev`, then run
-`spec-driven-dev` in your project.
+together, even when those repos live in different folders. To set it up, run
+`npx @benjaminthomas/spec-driven-dev@latest` in your project.
 
 ---
 
@@ -54,17 +54,21 @@ start a new session and continue where you left off.
 
 ## Quick start (5 minutes)
 
-**1. Install the CLI from npm** (once per machine):
+**1. Run the installer in your project** (for several repos, run it inside any one of them):
 
 ```bash
-npm install -g @benjaminthomas/spec-driven-dev
+npx @benjaminthomas/spec-driven-dev@latest
 ```
 
-**2. Run it in your project folder** (or, for several repos, in their shared parent folder):
+This one command downloads the tool, installs the skills, and sets up the project. It asks its
+questions in your terminal, so run it in a real terminal, not through another tool. If there's no
+terminal to answer in, it says so and uses the detected values.
 
-```bash
-spec-driven-dev
-```
+> **Why not `npm install -g`?** npm doesn't let a package ask questions while it installs, and an
+> install doesn't know which project it's for. That's why setup is a separate step you run inside
+> the project. If you'll use the `doctor`/`status` commands often, you can also install it
+> globally: `npm install -g @benjaminthomas/spec-driven-dev`, then run `spec-driven-dev` in place of
+> the `npx …` command.
 
 It:
 1. **Finds your AI tools** (Claude Code, Cursor, Codex CLI, Antigravity) and installs the skills
@@ -89,6 +93,11 @@ words in quotes.
 /spec-ship                         "ship it"
 ```
 
+**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
+setup (`pipeline.after_approval` in `.spec-driven.yml`).
+
 That's the whole workflow. Every stage can be used on its own as well: use `/spec-create` straight
 from a planning chat, or `/spec-checkpoint` on any work in progress.
 
@@ -115,9 +124,9 @@ can usually just press Enter):
 | Which AI tools get the skills | tool folders in your home directory and commands on your `PATH` | Claude Code, Cursor |
 | This project only, or all projects | (you choose) | `project` |
 | Project layout | git repos and workspace files (`pnpm-workspace.yaml`, `turbo.json`, `nx.json`, `go.work`, …) | `single`, `monorepo`, or `multi-repo` |
-| *multi-repo:* workspace folder (where the config goes) | the folder you ran it in, or the parent of the repo you're in | `~/work` |
-| *multi-repo:* which repos belong together | git repos in the workspace folder, grouped by GitHub owner | `api`, `web` |
-| *multi-repo:* repos from other folders | (you type paths) | `~/clients/billing, ../shared-lib` |
+| *multi-repo:* which repos nearby belong | git repos up to two folders down, grouped by GitHub owner | `frontend` |
+| *multi-repo:* repos in other places | (you type paths: absolute, `~/…`, or relative) | `~/Work/backend, /srv/database` |
+| *multi-repo:* where the config lives | the repos' shared parent folder, or `~/.spec-driven/<name>/` | `~/Projects` |
 | *monorepo:* package folders | the workspaces your `package.json`/`pnpm-workspace.yaml` declares, or `apps/*`, `packages/*` | `apps/web, packages/ui` |
 | Issue tracker | ticket keys in branch names and commits | Jira, key `STP` |
 | Base branch / PR target | default branch, `staging`/`develop` branches | `staging` |
@@ -125,6 +134,7 @@ can usually just press Enter):
 | Commit style | your recent commit messages | `conventional` (`feat: …`) or `ticket` (`STP-123: …`) |
 | 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` |
 
 **Where the file lives, by layout:**
 
@@ -132,17 +142,32 @@ can usually just press Enter):
 |---|---|---|---|
 | **single** | one repo, one app | the repo root (commit it, so the team shares it) | as described below |
 | **monorepo** | one repo, many apps/packages | the repo root (commit it) | tasks name their package, and checks run per package |
-| **multi-repo** | several repos that change together | their shared parent folder (personal to your machine) | investigation searches every listed repo, tasks stay inside one repo each, and `spec-ship` opens one PR per repo, each linking the others |
+| **multi-repo** | several repos that change together, in any folders | their shared parent folder, or `~/.spec-driven/<name>/` (personal to your machine) | investigation searches every listed repo, tasks stay inside one repo each, and `spec-ship` opens one PR per repo, each linking the others |
 
-Repos outside the workspace folder are saved with their full path. Paths that don't exist or
-aren't git repos are skipped with a message, and setup stops if a multi-repo workspace ends up with
-no repos. You can choose a different layout from the one detected: for example, choose
-`multi-repo` from inside one repo and it uses the parent folder as the workspace, with your current
-repo pre-selected.
+**Repos in different places.** A multi-repo workspace doesn't need its repos in one folder. For
+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]:
+```
+
+- **Where the config goes:** the repos' shared parent folder, or `~/.spec-driven/<name>/` when that
+  parent would be your home folder or `/`.
+- **How every repo finds it:** setup records the workspace in `~/.spec-driven/workspaces.json`, so
+  `/Work/backend` finds its config even though the config isn't above it. The skills, `doctor`,
+  and `status` all look there.
+- **Paths are checked:** ones that don't exist or aren't git repos are skipped with a message, and
+  setup stops if a workspace would end up with no repos.
 
 Every question also has a flag, for scripts and CI:
-`--layout=multi-repo --repos=api,web,~/clients/billing`, `--layout=monorepo --packages=apps/web,packages/ui`,
-`--tools=cursor,codex`, `--global`, `--yes` (accept everything detected).
+`--layout=multi-repo --repos=~/Projects/frontend,~/Work/backend --workspace=~/Projects`,
+`--layout=monorepo --packages=apps/web,packages/ui`, `--after-approval=run-through`,
+`--tools=cursor,codex`, `--global`, `--yes` (accept everything detected), and `--version`.
 
 To change the rules later, edit the file or run setup again, then run `spec-driven-dev doctor`
 to confirm the file still matches your repos. Setup never overwrites the file without
@@ -344,6 +369,18 @@ config sits outside any repo, so it stays on your machine.
 **Does it work with my stack?**
 Yes. No skill assumes a language or framework. Each one finds the repo's own commands.
 
+**Do I have to start every stage myself?**
+No. After you approve a spec, say "approved, run it through": implement, verify, and checkpoint then
+run one after another, stopping at the first failure. Two steps always wait for you: approving the
+spec, and pushing or opening the PR. You don't need slash commands either. Saying "investigate
+STP-123" or "ship it" picks the right skill.
+
+**Setup didn't ask me about repos.**
+It only asks about repos for a multi-repo or monorepo layout. If it detected `single`, type
+`multi-repo` at the layout question, then add your other repos by path. If it asked nothing at all,
+there was no terminal to type answers into (it prints a note saying so), so run it directly in a
+terminal. Check which version ran with `npx @benjaminthomas/spec-driven-dev@latest --version`.
+
 **Can I skip stages?**
 Yes. Every skill works on its own. `spec-verify` even works without a spec: it asks what to check.
 
@@ -487,15 +524,15 @@ skips that step rather than failing.
 
 | Skill | Stage | SKILL.md lines | Words | Supporting files |
 |---|---|---:|---:|---:|
-| `spec-setup` | 0 · configure | 105 | 935 | 1 |
-| `spec-investigate` | 1 · understand | 323 | 2,708 | 1 |
-| `spec-create` | 2 · plan | 149 | 1,328 | 4 |
-| `spec-implement` | 3 · build | 236 | 1,790 | 3 |
-| `spec-verify` | 4 · prove | 153 | 1,459 | 1 |
-| `spec-checkpoint` | 5 · commit | 106 | 762 | 0 |
-| `spec-ship` | 6 · PR | 218 | 1,235 | 0 |
+| `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-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,545** | **12,426** | **17** |
+| **Total** | | **1,607** | **13,051** | **17** |
 
 - **8** skills: **1** setup + **6** workflow stages + **1** standalone
 - **4** tools supported natively (Claude Code, Codex CLI, Cursor, Antigravity), plus an MCP fallback

package/bin/cli.mjs

@@ -7,7 +7,8 @@
 //   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)
 //   flags: --yes  --global  --tools=claude,cursor  --skills=spec-create,...  --no-setup  --dir=<path>
-//          --layout=single|monorepo|multi-repo  --repos=api,../web,/abs/path  --packages=apps/web,packages/ui
+//          --layout=single|monorepo|multi-repo  --repos=~/Projects/frontend,/srv/backend  --workspace=<config dir>
+//          --packages=apps/web,packages/ui  --after-approval=stop|run-through  --version
 import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
@@ -35,8 +36,15 @@ const command = args.find((a) => !a.startsWith("-")) || "install";
 const YES = flag("yes") || flag("y") || !process.stdin.isTTY || ["doctor", "status"].includes(command);
 const DIR = path.resolve(opt("dir") || process.cwd());
 
+if (flag("version") || flag("v")) {
+  console.log(JSON.parse(fs.readFileSync(path.join(ROOT, "package.json"), "utf8")).version);
+  process.exit(0);
+}
+if (["install", "setup"].includes(command) && !process.stdin.isTTY && !flag("yes") && !flag("y"))
+  console.log("• No interactive terminal detected, so no questions will be asked: using the detected values.\n  Run it directly in a terminal to answer them, or pass flags (--layout, --repos, --tools …). Add --yes to hide this note.");
+
 if (flag("help") || flag("h")) {
-  console.log(fs.readFileSync(fileURLToPath(import.meta.url), "utf8").split("\n").slice(1, 10).join("\n").replace(/^\/\/ ?/gm, ""));
+  console.log(fs.readFileSync(fileURLToPath(import.meta.url), "utf8").split("\n").slice(1, 11).join("\n").replace(/^\/\/ ?/gm, ""));
   process.exit(0);
 }
 
@@ -103,6 +111,21 @@ const isRepo = (d) => run("git", ["rev-parse", "--is-inside-work-tree"], d) ===
 const readJson = (f) => { try { return JSON.parse(fs.readFileSync(f, "utf8")); } catch { return null; } };
 const subdirs = (d) => { try { return fs.readdirSync(d, { withFileTypes: true }).filter((e) => e.isDirectory() && !e.name.startsWith(".")).map((e) => e.name); } catch { return []; } };
 
+// Git repos up to two folders down (e.g. ~/work/client/api). A git worktree has a .git *file*;
+// it belongs to its main repo, so it is skipped. Repos aren't searched inside.
+function findRepos(dir, depth = 2, prefix = "") {
+  const out = [];
+  for (const n of subdirs(dir)) {
+    if (n === "node_modules") continue;
+    const full = path.join(dir, n);
+    let isGitDir = false;
+    try { isGitDir = fs.statSync(path.join(full, ".git")).isDirectory(); } catch {}
+    if (isGitDir) out.push(prefix + n);
+    else if (depth > 1) out.push(...findRepos(full, depth - 1, `${prefix}${n}/`));
+  }
+  return out;
+}
+
 function detectLayout(dir) {
   if (isRepo(dir)) {
     const top = run("git", ["rev-parse", "--show-toplevel"], dir);
@@ -121,8 +144,7 @@ function detectLayout(dir) {
     const mono = MARKERS.some((m) => fs.existsSync(path.join(top, m))) || pkg?.workspaces || cargo || packages.length > 1;
     return { layout: mono ? "monorepo" : "single", root: top, repos: mono ? packages : [] };
   }
-  // a git worktree has a .git *file*; it belongs to its main repo, so skip it
-  const repos = subdirs(dir).filter((n) => { try { return fs.statSync(path.join(dir, n, ".git")).isDirectory(); } catch { return false; } });
+  const repos = findRepos(dir);
   return repos.length ? { layout: "multi-repo", root: dir, repos } : { layout: "single", root: dir, repos: [] };
 }
 
@@ -182,13 +204,15 @@ 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 += `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 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 relOrAbs = (root, p) => { const r = path.relative(root, p); return r.startsWith("..") || path.isAbsolute(r) ? p : r || "."; };
+const real = (p) => { try { return fs.realpathSync(p); } catch { return p; } }; // /var vs /private/var etc.
+const relOrAbs = (root, p) => { const r = path.relative(real(root), real(p)); return r.startsWith("..") || path.isAbsolute(r) ? real(p) : r || "."; };
 
 async function chooseLayout(detected) {
   const forced = opt("layout");
@@ -201,41 +225,74 @@ async function chooseLayout(detected) {
   }
 }
 
-// multi-repo: pick from repos found in the workspace folder, then add any others by path.
+const expandHome = (p) => p.replace(/^~(?=$|\/)/, HOME);
+
+function commonParent(paths) {
+  if (!paths.length) return "";
+  let parts = paths[0].split(path.sep);
+  for (const p of paths.slice(1)) { const q = p.split(path.sep); let i = 0; while (i < parts.length && parts[i] === q[i]) i++; parts = parts.slice(0, i); }
+  return parts.join(path.sep) || path.sep;
+}
+
+// multi-repo: the repos can live anywhere (/Projects/frontend, /Work/backend, …). Pick the ones found
+// nearby, add any others by path, then decide where the config lives.
 async function chooseRepos(d) {
-  // Inside one repo but multi-repo chosen → the workspace is the folder that holds this repo.
   const insideRepo = d.layout !== "multi-repo";
-  const defRoot = insideRepo ? path.dirname(d.root) : d.root;
-  const root = path.resolve(DIR, await ask("Workspace folder (where .spec-driven.yml goes)", defRoot));
-  const found = detectLayout(root).layout === "multi-repo" ? detectLayout(root).repos : [];
+  const scanRoot = insideRepo ? path.dirname(d.root) : d.root;
   let picked = [];
   const fromFlag = opt("repos");
   if (fromFlag) {
-    picked = splitList(fromFlag).map((p) => path.resolve(root, p));
+    picked = splitList(fromFlag).map((p) => path.resolve(DIR, expandHome(p)));
   } else {
+    const found = findRepos(scanRoot);
     if (found.length) {
       const owners = {};
-      for (const r of found) (owners[gitFacts(path.join(root, r))?.owner || "?"] ||= []).push(r);
+      for (const r of found) (owners[gitFacts(path.join(scanRoot, r))?.owner || "?"] ||= []).push(r);
       const biggest = Object.values(owners).sort((a, b) => b.length - a.length)[0] || [];
-      const here = insideRepo ? [path.relative(root, d.root)] : [];
-      console.log(`Found ${found.length} git repos in ${root}. Which ones change together as one workspace?`);
-      picked = (await pick("Repos", found.map((r) => ({ value: r, label: `${r}  (${Object.keys(owners).find((o) => owners[o].includes(r))})` })), [...new Set([...here, ...biggest])]))
-        .map((r) => path.join(root, r));
+      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)])]))
+        .map((r) => path.join(scanRoot, r));
     } else if (insideRepo) picked = [d.root];
-    const extra = await ask("Add repos from other folders? Paths, comma-separated (absolute, ~/…, or relative to the workspace folder); empty for none", "");
-    picked.push(...splitList(extra).map((p) => path.resolve(root, p.replace(/^~(?=$|\/)/, HOME))));
+    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))));
   }
-  const repos = [];
+  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 repos.push(relOrAbs(root, p));
+    else abs.push(run("git", ["rev-parse", "--show-toplevel"], p) || p);
   }
-  if (!repos.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).");
+  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).");
+
+  // Config location: the repos' shared parent folder, unless that's too broad (home or /), in which
+  // case a named folder under ~/.spec-driven/. Repos outside it find the config via the registry.
+  const parent = commonParent([...new Set(abs.map(real))].map((p) => path.dirname(p)));
+  const tooBroad = !parent || parent === HOME || parent === path.parse(parent).root || HOME.startsWith(parent + path.sep);
+  // Ran in a workspace folder and every repo is under it → keep the config right there.
+  const allUnderScan = !insideRepo && abs.every((p) => real(p).startsWith(real(scanRoot) + path.sep));
+  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)));
+  fs.mkdirSync(root, { recursive: true });
+  const repos = [...new Set(abs)].map((p) => relOrAbs(root, p));
   console.log(`  Workspace repos: ${repos.join(", ")}`);
   return { root, repos };
 }
 
+// ~/.spec-driven/workspaces.json maps each multi-repo config to its repos, so a repo outside the
+// config's folder (e.g. /Work/backend for a config in /Projects) can still find it.
+const REGISTRY = () => path.join(HOME, ".spec-driven", "workspaces.json");
+function readRegistry() { return readJson(REGISTRY()) || {}; }
+function register(file, repoPaths) {
+  const reg = readRegistry();
+  reg[file] = repoPaths;
+  fs.mkdirSync(path.dirname(REGISTRY()), { recursive: true });
+  fs.writeFileSync(REGISTRY(), JSON.stringify(reg, null, 2) + "\n");
+}
+
 // monorepo: confirm or edit the package folders (relative to the repo root).
 async function choosePackages(d) {
   const root = d.root;
@@ -250,8 +307,13 @@ async function choosePackages(d) {
 }
 
 async function setup() {
+  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);
+  console.log(d.layout === "multi-repo" ? `Detected: ${d.repos.length} git repos under ${d.root} (multi-repo).`
+    : d.layout === "monorepo" ? `Detected: monorepo at ${d.root} with ${d.repos.length} package(s)${d.repos.length ? `: ${d.repos.join(", ")}` : ""}.`
+    : isRepo(d.root) ? `Detected: single repo at ${d.root}. If it works together with other repos, choose multi-repo.`
+    : `Detected: no git repo in ${d.root}. Choose multi-repo to list your repos, wherever they are.`);
   const layout = await chooseLayout(d.layout);
   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.`);
@@ -274,9 +336,17 @@ async function setup() {
   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 config = {
-    layout, tracker: { type: trackerType, key, url }, specsDir, devUrl: "",
+    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) => {
@@ -286,6 +356,7 @@ async function setup() {
     }),
   };
   fs.writeFileSync(file, toYaml(config));
+  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".');
@@ -331,8 +402,13 @@ function findConfig(dir) {
   for (let d = dir; ; d = path.dirname(d)) {
     const f = path.join(d, ".spec-driven.yml");
     if (fs.existsSync(f)) return f;
-    if (d === path.dirname(d) || d === HOME) return null;
+    if (d === path.dirname(d) || d === HOME) break;
   }
+  // Not above us: a multi-repo workspace elsewhere may list this repo.
+  const here = real(dir);
+  for (const [file, repos] of Object.entries(readRegistry()))
+    if (fs.existsSync(file) && repos.some((r) => here === r || here.startsWith(r + path.sep))) return file;
+  return null;
 }
 
 function doctor() {
@@ -345,6 +421,7 @@ 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`);
+  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 : [];
   if (c.layout !== "single" && !repos.length) problems.push(`layout is ${c.layout} but repos: is empty`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@benjaminthomas/spec-driven-dev",
-  "version": "1.4.1",
+  "version": "1.5.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/cli.mjs" },

package/skills/spec-checkpoint/SKILL.md

@@ -17,7 +17,9 @@ Create a checkpoint commit that captures all current changes — but only after
 ## Project config (read first)
 
 Load `.spec-driven.yml`: walk up from the current directory to the home folder, and the first one
-found wins (a `multi-repo` config only applies inside the repos it lists). Its values beat anything
+found wins (a `multi-repo` config only applies inside the repos it lists). If none is found, check
+`~/.spec-driven/workspaces.json`, which maps each multi-repo config to its repo paths. Use the config
+whose repos contain the current directory, because a workspace's repos can live in unrelated folders. Its values beat anything
 you would detect or assume. This skill uses `commands` (lint/typecheck/test/build), `git.commit_style`, and `layout`/`repos`.
 
 **Multi-repo:** run this in every listed repo that has changes, making one commit per repo with the same subject. **Monorepo:** run the checks for the packages that changed, or the root commands if that's how the repo works.

package/skills/spec-create/SKILL.md

@@ -20,7 +20,9 @@ The key insight: implementation plans that live in a single file are either too
 ## Project config (read first)
 
 Load `.spec-driven.yml`: walk up from the current directory to the home folder, and the first one
-found wins (a `multi-repo` config only applies inside the repos it lists). Its values beat anything
+found wins (a `multi-repo` config only applies inside the repos it lists). If none is found, check
+`~/.spec-driven/workspaces.json`, which maps each multi-repo config to its repo paths. Use the config
+whose repos contain the current directory, because a workspace's repos can live in unrelated folders. Its values beat anything
 you would detect or assume. This skill uses `layout`/`repos` and `specs_dir`.
 
 **Monorepo / multi-repo:** every task names its package or repo, and its file paths are relative to that. Keep each task inside one repo. Cross-repo work becomes separate tasks, with the contract (API shape, event, schema) written into both.
@@ -136,9 +138,15 @@ Batch breakdown:
 Next steps:
 1. Review action-required.md for tasks you need to complete manually
 2. Review the requirements and task files
-3. Use /spec-implement to start parallel implementation
+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,
+     never pushes without asking)
 ```
 
+If `.spec-driven.yml` has `pipeline.after_approval: run-through`, say that this project runs through
+by default after approval. Never start implementing from this skill.
+
 ## Critical Rules
 
 - Every task file must be fully self-contained — this is the entire point of the spec structure. A coder agent reading only that file must know exactly what to do.

package/skills/spec-implement/SKILL.md

@@ -4,7 +4,7 @@ description: >
   Orchestrate parallel implementation of a feature specification by dispatching coder agents
   batch-by-batch with code review gates between batches. Use this skill when the user says
   "implement this feature", "start implementing", "run the spec", "execute the plan",
-  "continue implementing", or wants to begin coding a previously planned feature from a
+  "continue implementing", "approved, run it through", or wants to begin coding a previously planned feature from a
   specs/{feature}/ folder. Also use when the user says "/spec-implement" (or their host's
   equivalent invocation syntax) or drags a spec folder into the conversation and asks to
   implement it. This skill does NOT write code itself — it orchestrates coder subagents that
@@ -26,7 +26,9 @@ The orchestrator never writes code itself. Its job is to:
 ## Project config (read first)
 
 Load `.spec-driven.yml`: walk up from the current directory to the home folder, and the first one
-found wins (a `multi-repo` config only applies inside the repos it lists). Its values beat anything
+found wins (a `multi-repo` config only applies inside the repos it lists). If none is found, check
+`~/.spec-driven/workspaces.json`, which maps each multi-repo config to its repo paths. Use the config
+whose repos contain the current directory, because a workspace's repos can live in unrelated folders. Its values beat anything
 you would detect or assume. This skill uses `layout`/`repos`, `commands` (lint/typecheck/test per repo or package), and `git.commit_style`.
 
 **Multi-repo:** create worktrees in each repo a task touches, run each repo's own commands in review, and make the batch commit in every repo that changed, using the same subject line.
@@ -220,6 +222,41 @@ Next steps:
 - Push and create a PR when ready
 ```
 
+## Run-through mode (after approval)
+
+Run-through applies when the user asks for it ("approved, run it through", "build, verify 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:
+
+```
+Run-through progress:
+- [ ] Implement all batches (Steps 1–9) — every review gate passed
+- [ ] Verify — follow the spec-verify skill; every acceptance criterion PASS
+- [ ] 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
+   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.
+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.
+4. **No approval, no run-through.** If the spec hasn't been reviewed and approved in this
+   conversation, or the user only said "implement", do the normal Steps 1–9 and stop.
+
+```
+Run-through complete for "{feature}":
+- Implement: {N} batches, all review gates PASS
+- Verify: {P}/{P} criteria PASS (specs/{feature}/verification-report.md)
+- Checkpoint: {commit hash} — {subject}
+
+Ready to push and open a PR. Run spec-ship? (it will show exactly what gets pushed first)
+```
+
 ## Error Handling
 
 - **Coder agent failure**: mark the task as failed, report to user, continue with remaining tasks in the batch. The review step will catch integration issues.

package/skills/spec-investigate/SKILL.md

@@ -33,7 +33,9 @@ ready-to-use work branch; a human decides when to run `spec-create` next.
 ## Project config (read first)
 
 Load `.spec-driven.yml`: walk up from the current directory to the home folder, and the first one
-found wins (a `multi-repo` config only applies inside the repos it lists). Its values beat anything
+found wins (a `multi-repo` config only applies inside the repos it lists). If none is found, check
+`~/.spec-driven/workspaces.json`, which maps each multi-repo config to its repo paths. Use the config
+whose repos contain the current directory, because a workspace's repos can live in unrelated folders. Its values beat anything
 you would detect or assume. This skill uses `layout`/`repos` (where to look and what each repo does), `tracker`, `git.remote`, `git.base_branch`, `git.branch_name`, and `specs_dir`.
 
 **Monorepo:** name the package(s) involved. **Multi-repo:** search every listed repo whose role fits the ticket, and create the work branch, with the same name, only in the repos the investigation shows need changes.

package/skills/spec-setup/SKILL.md

@@ -44,6 +44,11 @@ Read, don't guess. Collect a draft of every field in `references/config-template
      belong together. Never assume every folder in the parent belongs. Always also ask whether
      repos in **other folders** belong (e.g. `~/clients/billing`). Check each path is a git repo,
      and store paths inside the workspace as relative and paths outside it as absolute.
+   - The repos of one workspace can live in unrelated places (`/Projects/frontend`,
+     `~/Work/backend`, `/srv/database`). Put the config in their shared parent folder, or in
+     `~/.spec-driven/<name>/` when that parent would be the home folder or `/`. Then record it in
+     `~/.spec-driven/workspaces.json` (`{"<config path>": ["<repo path>", …]}`) so every repo can
+     find it.
    - The user can override the detected layout. If they choose `multi-repo` from inside one repo,
      the workspace folder defaults to that repo's parent, with the current repo pre-selected. If
      they choose `monorepo`, ask for the package folders. Never write a `multi-repo` config with
@@ -64,6 +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
+   run implement → verify → checkpoint in one go (`run-through`), stopping at any failure and never
+   pushing. Store it as `pipeline.after_approval`.
+
 ## Step 2 — Confirm in one round
 
 Show the draft as a short table grouped by layout, tracker, git, commands, and specs location.

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

@@ -42,4 +42,10 @@ commands:
   dev: ""                       # how spec-verify starts the app
   dev_url: ""                   # where it answers, e.g. http://localhost:3000
 
+pipeline:
+  # stop        — every stage waits for you (default)
+  # run-through — after you approve a spec: implement → verify → checkpoint in one go,
+  #               stopping at any failure. Pushing / opening the PR (spec-ship) always asks first.
+  after_approval: stop
+
 specs_dir: specs                # where specs/<feature>/ folders go (relative to this file)

package/skills/spec-ship/SKILL.md

@@ -19,7 +19,9 @@ This skill complements `spec-checkpoint`. Use `spec-checkpoint` to commit locall
 ## Project config (read first)
 
 Load `.spec-driven.yml`: walk up from the current directory to the home folder, and the first one
-found wins (a `multi-repo` config only applies inside the repos it lists). Its values beat anything
+found wins (a `multi-repo` config only applies inside the repos it lists). If none is found, check
+`~/.spec-driven/workspaces.json`, which maps each multi-repo config to its repo paths. Use the config
+whose repos contain the current directory, because a workspace's repos can live in unrelated folders. Its values beat anything
 you would detect or assume. This skill uses `git.remote`, `git.pr_target`, `git.branch_name`, `tracker` (to link the ticket in the PR), and `layout`/`repos`.
 
 **Multi-repo:** push and open one PR per repo that has unpushed commits, and list the sibling PRs in each PR's body so reviewers see the whole change.

package/skills/spec-verify/SKILL.md

@@ -26,7 +26,9 @@ by the real code path. It produces a report the user can trust before shipping.
 ## Project config (read first)
 
 Load `.spec-driven.yml`: walk up from the current directory to the home folder, and the first one
-found wins (a `multi-repo` config only applies inside the repos it lists). Its values beat anything
+found wins (a `multi-repo` config only applies inside the repos it lists). If none is found, check
+`~/.spec-driven/workspaces.json`, which maps each multi-repo config to its repo paths. Use the config
+whose repos contain the current directory, because a workspace's repos can live in unrelated folders. Its values beat anything
 you would detect or assume. This skill uses `commands.dev`, `commands.dev_url`, and `layout`/`repos`.
 
 **Monorepo / multi-repo:** start every app or service the criteria need (e.g. the API and the frontend), each with its own `dev` command.