@benjaminthomas/spec-driven-dev 1.4.0 → 1.5.0

package/README.md

@@ -1,5 +1,9 @@
 # spec-driven-dev
 
+[![npm](https://img.shields.io/npm/v/@benjaminthomas/spec-driven-dev?label=npm)](https://www.npmjs.com/package/@benjaminthomas/spec-driven-dev)
+[![check](https://github.com/benjaminthomas/spec-driven-dev/actions/workflows/check.yml/badge.svg)](https://github.com/benjaminthomas/spec-driven-dev/actions/workflows/check.yml)
+[![license: MIT](https://img.shields.io/badge/license-MIT-blue)](LICENSE)
+
 **A step-by-step workflow that gets AI coding agents from "here's a ticket" to "here's a reviewed PR"
 without guessing.** It first investigates the problem, then writes a plan you approve, then builds it
 in parallel with tests and review, then checks the real running app, and finally commits and opens
@@ -8,7 +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. One command installs it: `npx @benjaminthomas/spec-driven-dev`.
+together, even when those repos live in different folders. To set it up, run
+`npx @benjaminthomas/spec-driven-dev@latest` in your project.
 
 ---
 
@@ -26,6 +31,7 @@ together. One command installs it: `npx @benjaminthomas/spec-driven-dev`.
 - [Compatibility](#compatibility)
 - [By the numbers](#by-the-numbers)
 - [Working on this repo](#working-on-this-repo)
+- [Changelog](CHANGELOG.md)
 
 ---
 
@@ -48,20 +54,30 @@ start a new session and continue where you left off.
 
 ## Quick start (5 minutes)
 
-**1. Install.** In your project folder (or, for several repos, their shared parent folder), run:
+**1. Run the installer in your project** (for several repos, run it inside any one of them):
 
 ```bash
-npx @benjaminthomas/spec-driven-dev
+npx @benjaminthomas/spec-driven-dev@latest
 ```
 
-The installer:
+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.
+
+> **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
    into each one you choose, for this project or for all projects.
 2. **Sets up your project** by detecting its layout, issue tracker, branch conventions, and
    commands, then asking you to confirm. The answers go into `.spec-driven.yml`
    ([details below](#project-setup-your-teams-rules)).
 
-**2. In your project, run each stage in order.** You can type the slash command or just say the
+**3. In your AI tool, run each stage in order.** You can type the slash command or just say the
 words in quotes.
 
 ```
@@ -77,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.
 
@@ -89,24 +110,31 @@ others `fix/STP-123-short-name`. Some have one repo, others have six. None of th
 skills. Each project describes its own rules in **`.spec-driven.yml`**, and every skill reads that
 file before doing anything.
 
-**How the file gets created:** `npx @benjaminthomas/spec-driven-dev` (or `npx @benjaminthomas/spec-driven-dev setup` to run only this
+**How the file gets created:** `spec-driven-dev` (or `spec-driven-dev setup` to run only this
 step) detects the answers from your repos and asks you to confirm them. In your AI tool you can also
 say **"run spec-setup"**: that does a deeper version that also reads `CLAUDE.md`/`AGENTS.md`, CI
 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 it asks:**
+**What `spec-driven-dev` asks, in order** (every answer comes pre-filled with what it detected, so you
+can usually just press Enter):
 
 | Question | Detected from | Example answer |
 |---|---|---|
+| 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` |
-| Which repos belong together (multi-repo) | sibling git repos grouped by GitHub owner | `api`, `web`, `worker` |
+| *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` |
 | Branch name pattern | your recent branch names | `{ticket}` → `STP-123` |
 | 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:**
 
@@ -114,9 +142,34 @@ for stacks other than Node). If a skill finds no config, it runs this setup firs
 |---|---|---|---|
 | **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 in different places.** A multi-repo workspace doesn't need its repos in one folder. For
+example, from inside `/Projects/frontend`:
 
-To change the rules later, edit the file or run setup again, then run `npx @benjaminthomas/spec-driven-dev doctor`
+```
+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=~/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
 asking. See [`config-template.yml`](skills/spec-setup/references/config-template.yml) for every field.
 
@@ -316,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.
 
@@ -326,6 +391,24 @@ Yes. Every skill works on its own. `spec-verify` even works without a spec: it a
 Yes. Progress is saved in the spec's `README.md` checkboxes and the commit for each batch. Run
 `spec-implement` again to continue.
 
+**How do I update?**
+Run `npm install -g @benjaminthomas/spec-driven-dev@latest`, then `spec-driven-dev` in your project.
+Claude Code plugin users run
+`/plugin marketplace update spec-driven-dev` and then update the plugin. Your config is never
+touched by an update.
+
+**Can I trust the npm package?**
+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.
+
+**Something isn't working. Where do I start?**
+Run `spec-driven-dev doctor` in your project. It checks the config against your
+repos and names anything that doesn't match. If that passes, open an
+[issue](https://github.com/benjaminthomas/spec-driven-dev/issues) with the doctor output and the
+skill you were running.
+
 **`spec-verify` says it skipped some UI checks.**
 Your tool needs browser automation (an MCP browser server, a built-in browser tool, or an
 extension) for checks that involve the UI. Checks that only touch the API or database work
@@ -338,23 +421,41 @@ everywhere.
 ### Any tool: npm (recommended)
 
 ```bash
-npx @benjaminthomas/spec-driven-dev                                   # detect tools, install, set up the project
-npx @benjaminthomas/spec-driven-dev setup                             # only (re)run project setup
-npx @benjaminthomas/spec-driven-dev --global                          # install for all projects, not just this one
-npx @benjaminthomas/spec-driven-dev --tools=cursor,codex              # pick tools without being asked
-npx @benjaminthomas/spec-driven-dev --skills=spec-create,spec-ship    # install only some skills
-npx @benjaminthomas/spec-driven-dev --yes                             # accept every detected default (CI-friendly)
-npx @benjaminthomas/spec-driven-dev doctor                            # check .spec-driven.yml against the real repos
-npx @benjaminthomas/spec-driven-dev status                            # list specs with unfinished work
+npm install -g @benjaminthomas/spec-driven-dev    # once per machine; adds the `spec-driven-dev` command
 ```
 
+Then, in a project:
+
+```bash
+spec-driven-dev                                   # detect tools, install skills, set up the project
+spec-driven-dev setup                             # only (re)run project setup
+spec-driven-dev --global                          # install skills for all projects, not just this one
+spec-driven-dev --tools=cursor,codex              # pick tools without being asked
+spec-driven-dev --skills=spec-create,spec-ship    # install only some skills
+spec-driven-dev --yes                             # accept every detected default (CI-friendly)
+spec-driven-dev doctor                            # check .spec-driven.yml against the real repos
+spec-driven-dev status                            # list specs with unfinished work
+spec-driven-dev --help                            # show all of the above
+```
+
+**Without installing:** replace `spec-driven-dev` with `npx @benjaminthomas/spec-driven-dev`, for
+example `npx @benjaminthomas/spec-driven-dev setup`. That downloads and runs the latest version once,
+which is handy in CI or on a machine you won't use again.
+
 `doctor` checks that every branch, folder, and `npm run` script named in the config exists, and
 that each value is one the skills understand. It exits 1 if anything is wrong, so you can run it in
 CI. `status` prints nothing when all specs are finished.
 
-Run it again at any time to update: it replaces the installed skill folders with the latest
-version. `npx github:benjaminthomas/spec-driven-dev` installs straight from GitHub (for example, an unreleased
-commit on `main`).
+**Updating:** run `npm install -g @benjaminthomas/spec-driven-dev@latest` to get the newest CLI,
+then `spec-driven-dev` in each project to refresh its skills. This replaces the installed skill
+folders and leaves your `.spec-driven.yml` alone. If you use `npx`, add `@latest`, because `npx`
+can otherwise reuse an older copy it cached. What changed in each version is in
+[CHANGELOG.md](CHANGELOG.md).
+
+`npx github:benjaminthomas/spec-driven-dev` installs straight from GitHub instead, for example to
+try an unreleased commit on `main`.
+
+**Requirements:** Node.js 18 or newer and git. The installer has no dependencies.
 
 ### Claude Code (plugin, with automatic updates)
 
@@ -369,8 +470,8 @@ The plugin also adds a **session-start reminder**. When you open Claude Code in
 unfinished specs, Claude is told which ones and what the next step is (for example,
 `specs/stp-123: 3/5 tasks done → next: spec-implement`). It prints nothing when everything is
 finished. If
-you use the plugin, `npx @benjaminthomas/spec-driven-dev` skips Claude Code so you don't get every skill twice. Run
-`npx @benjaminthomas/spec-driven-dev setup` for the project config.
+you use the plugin, `spec-driven-dev` skips Claude Code so you don't get every skill twice. Run
+`spec-driven-dev setup` for the project config.
 
 ### By hand
 
@@ -423,20 +524,20 @@ skips that step rather than failing.
 
 | Skill | Stage | SKILL.md lines | Words | Supporting files |
 |---|---|---:|---:|---:|
-| `spec-setup` | 0 · configure | 99 | 857 | 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,539** | **12,348** | **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
 - **3** layouts: single repo, monorepo, multi-repo
-- **1** install command, `npx @benjaminthomas/spec-driven-dev`, plus the Claude Code plugin and an MCP fallback
+- **1** npm package, `@benjaminthomas/spec-driven-dev`, plus the Claude Code plugin and an MCP fallback
 - **0** stack assumptions: lint, typecheck, test, build, and dev commands come from your repo
 
 _The table is generated by `python3 scripts/check.py --fix`; CI fails if it goes out of date._
@@ -450,19 +551,22 @@ 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 npx installer + project setup (no dependencies)
+bin/cli.mjs                   the `spec-driven-dev` CLI: installer, setup, doctor, status (no dependencies)
 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`)
 CHANGELOG.md                  what changed in each version
 scripts/check.py              consistency checks + metrics generator
 scripts/test-cli.mjs          installer self-test (fake HOME, throwaway repos)
+.github/workflows/check.yml   CI: consistency checks + installer self-test on every push and PR
+.github/workflows/publish.yml publishes to npm when a vX.Y.Z tag is pushed
 evals/                        `claude plugin eval` cases
 ```
 
 - **Adding a skill:** create `skills/<name>/SKILL.md`, then add the name to the two manifests, a `.agents/skills/<name>` symlink, the `STAGES` map in
   `scripts/check.py`, and this README. `python3 scripts/check.py` lists anything you missed.
-- **Before pushing:** run `python3 scripts/check.py --fix`. CI (`.github/workflows/check.yml`) runs
+- **Before pushing:** run `python3 scripts/check.py --fix`, then `npm test` (which runs the checks
+  and the installer self-test). CI (`.github/workflows/check.yml`) runs
   the same checks, the installer self-test, and a syntax check on the MCP server.
 - **Evals:** `claude plugin eval . --runs 1` checks that skills trigger on their phrases and stay
   within their own stage. These runs use your Claude credentials, so they aren't part of CI.
@@ -476,8 +580,15 @@ evals/                        `claude plugin eval` cases
 - **Releasing:**
   1. Increase `version` in both `package.json` and `.claude-plugin/plugin.json` (the check fails if
      they differ).
-  2. Add a `CHANGELOG.md` entry.
-  3. Push, then `npm publish`.
+  2. Add a `CHANGELOG.md` entry, then commit and push.
+  3. Tag the release and push the tag: `git tag v1.4.1 && git push origin v1.4.1`.
+  4. Watch the **publish** run in the repo's Actions tab. When it's green, the new version is on
+     npm. Claude Code plugin users get it from the marketplace once the commit is on `main`.
+
+  `.github/workflows/publish.yml` then runs the tests and publishes to npm through
+  [trusted publishing](https://docs.npmjs.com/trusted-publishers). No npm token or passkey is
+  needed, and the package page shows a provenance badge linking the release to the exact commit.
+  The workflow refuses to publish if the tag doesn't match `package.json`.
 
 ## License
 

package/bin/cli.mjs

@@ -1,12 +1,14 @@
 #!/usr/bin/env node
-// spec-driven-dev installer: detects your AI coding tools, copies the skills into each one, and
+// spec-driven-dev installer (npm i -g @benjaminthomas/spec-driven-dev): detects your AI coding tools, copies the skills into each one, and
 // runs project discovery (layout, tracker, branches, commands) to write .spec-driven.yml.
 //
-//   npx @benjaminthomas/spec-driven-dev                 install + project setup (interactive)
-//   npx @benjaminthomas/spec-driven-dev setup           project setup only
-//   npx @benjaminthomas/spec-driven-dev doctor          check .spec-driven.yml against the real repos (exit 1 on problems)
-//   npx @benjaminthomas/spec-driven-dev status          list specs with unfinished tasks (used by the session-start hook)
+//   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)
 //   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
 import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
@@ -34,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, 9).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);
 }
 
@@ -102,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);
@@ -120,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: [] };
 }
 
@@ -181,29 +204,126 @@ 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 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");
+  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 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) {
+  const insideRepo = d.layout !== "multi-repo";
+  const scanRoot = insideRepo ? path.dirname(d.root) : d.root;
+  let picked = [];
+  const fromFlag = opt("repos");
+  if (fromFlag) {
+    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(scanRoot, r))?.owner || "?"] ||= []).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)])]))
+        .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))));
+  }
+  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);
+  }
+  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;
+  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(",")));
+  const pkgs = [];
+  for (const p of splitList(answer)) {
+    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`);
+  }
+  return { root, repos: pkgs };
+}
+
 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);
-  let repos = d.repos;
-  if (d.layout === "multi-repo") {
-    const owners = {};
-    for (const r of repos) (owners[gitFacts(path.join(d.root, r))?.owner || "?"] ||= []).push(r);
-    const biggest = Object.values(owners).sort((a, b) => b.length - a.length)[0] || [];
-    console.log(`Found ${repos.length} git repos in ${d.root}. Which ones change together as one workspace?`);
-    repos = await pick("Repos", repos.map((r) => ({ value: r, label: `${r}  (${Object.keys(owners).find((o) => owners[o].includes(r))})` })), biggest);
-  }
-  const layout = await ask(`Layout — single, monorepo, or multi-repo (detected: ${d.layout})`, d.layout);
-  const root = d.root;
+  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.`);
   const file = path.join(root, ".spec-driven.yml");
   if (fs.existsSync(file) && (await ask(`${file} exists — overwrite? (y/n)`, "n")) !== "y") {
     console.log("• Kept the existing config. Run the spec-setup skill in your AI tool to review it.");
     return;
   }
 
-  const repoDirs = layout === "multi-repo" ? repos.map((r) => path.join(root, r)) : [isRepo(root) ? root : DIR];
+  const repoDirs = layout === "multi-repo" ? repos.map((r) => path.resolve(root, r)) : [root];
   const facts = repoDirs.map(gitFacts).filter(Boolean);
   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}`);
@@ -216,18 +336,27 @@ 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: layout === "single" ? [] : (layout === "multi-repo" ? repos : d.repos).map((r) => {
-      const f = layout === "multi-repo" ? gitFacts(path.join(root, r)) : null;
+    repos: repos.map((r) => {
+      const f = layout === "multi-repo" ? gitFacts(path.resolve(root, r)) : null;
       // a repo without an integration branch must say so, or it inherits the top-level base (e.g. staging) it doesn't have
-      return { path: r, role: "", base: f ? f.integration || "default" : "", commands: commandsFor(path.join(root, r)) };
+      return { path: r, role: "", base: f ? f.integration || "default" : "", commands: commandsFor(path.resolve(root, r)) };
     }),
   };
   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".');
@@ -273,13 +402,18 @@ 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() {
   const file = findConfig(DIR);
-  if (!file) throw new Error(`No .spec-driven.yml in ${DIR} or above. Run: npx @benjaminthomas/spec-driven-dev setup`);
+  if (!file) throw new Error(`No .spec-driven.yml in ${DIR} or above. Run: spec-driven-dev setup  (or npx @benjaminthomas/spec-driven-dev setup)`);
   const root = path.dirname(file);
   let c;
   try { c = parseYaml(fs.readFileSync(file, "utf8")); } catch (e) { throw new Error(`${file} could not be read: ${e.message}`); }
@@ -287,11 +421,12 @@ 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`);
   for (const r of repos) {
-    const dir = path.join(root, r.path || "");
+    const dir = path.resolve(root, r.path || ".");
     const label = r.path === "." ? "repo" : r.path;
     if (!fs.existsSync(dir)) { problems.push(`${label}: folder not found`); continue; }
     const gitDir = c.layout === "monorepo" ? root : dir;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@benjaminthomas/spec-driven-dev",
-  "version": "1.4.0",
+  "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

@@ -41,7 +41,18 @@ Read, don't guess. Collect a draft of every field in `references/config-template
      `monorepo`; list the packages.
    - Not inside a git repo, but sibling folders are git repos → candidate `multi-repo`. Group them
      by remote owner (`git remote get-url origin`) and show the groups — the user picks which repos
-     belong together. Never assume every folder in the parent belongs.
+     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
+     no repos.
    - Otherwise → `single`.
 2. **Existing written rules.** `CLAUDE.md`, `AGENTS.md`, `CONTRIBUTING.md`, PR templates,
    `.github/workflows`. Anything stated there is a strong default — quote it back to the user.
@@ -58,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.