@benjaminthomas/spec-driven-dev 1.12.0 → 1.13.1

package/README.md

@@ -63,26 +63,21 @@ start a new session and continue where you left off.
 npx @benjaminthomas/spec-driven-dev@latest
 ```
 
-This one command downloads the tool, installs the skills, and sets up the project. In a terminal
-window it asks its setup questions there. Run it with `!` inside Claude Code (or any other place
-without a terminal to answer in) and it installs the skills for the AI tools it finds, then tells
-you to say **"run spec-setup"**, which asks the same questions in the chat. It never writes the
-settings file from guesses.
-
-> **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)).
-
-**3. In your AI tool, run each stage in order.** You can type the slash command or just say the
+It installs the skills into the AI tools you pick (Claude Code, Cursor, Codex CLI, Antigravity),
+for this project or all your projects. Each step has its own colour so it's easy to follow. It also
+works with `!` inside Claude Code: it then installs for the tools it finds.
+
+> **Why not `npm install -g`?** You can: `npm install -g @benjaminthomas/spec-driven-dev`, then run
+> `spec-driven-dev` in place of the `npx …` command. Handy if you use `doctor`/`status` often.
+
+**2. Say "run spec-setup" in your AI tool.** Setup is a conversation, so the agent can read the code
+and you can change any answer as you go. It asks how the project is organised (one repo, a monorepo,
+or several repos that change together), your tracker, branches and commit style, where specs live
+and whether your team shares them, then looks through the code and saves the project memory
+([details below](#project-setup-your-teams-rules)). If Claude Code or Codex is installed, the
+installer offers to open it with "run spec-setup" already typed in.
+
+**3. Then run each stage in order.** You can type the slash command or just say the
 words in quotes.
 
 ```
@@ -145,36 +140,24 @@ 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:** `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 `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.
+**How the file gets created:** in your AI tool, say **"run spec-setup"**. It detects what it can
+(layout, tracker, branches, commit style per repo, commands, written rules in `CLAUDE.md`/`AGENTS.md`,
+CI config, recent PR targets), shows you a draft marked *detected* or *guess*, and asks only about
+the guesses, in one round. You can correct anything in plain words ("actually it's Jira, key STP")
+before it writes the file. If any skill finds no config, it runs this setup first.
 
-| Question | Detected from | Example answer |
+| What it asks | 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` |
-| *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` |
+| How the project is organised | git repos and workspace files (`pnpm-workspace.yaml`, `turbo.json`, `nx.json`, `go.work`, …). A Shopify app's `extensions/` count as one app | `single`, `monorepo`, or `multi-repo` |
+| *multi-repo:* which repos you work on | git repos nearby, grouped by GitHub owner, plus the team's `team-repos.yml` | `soreto-shopify, reverb-backend` |
+| *multi-repo:* where specs live | (you choose) | a dedicated specs repo, a code repo, or this machine only |
 | Issue tracker | ticket keys in branch names and commits | Jira, key `STP` |
-| Base branch / PR target | default branch, `staging`/`develop` branches | `staging` |
+| Base branch / PR target | default branch, `staging`/`develop`, recent PR targets | `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/` |
+| Commit style | recent commit messages, judged per repo | `ticket` (`STP-123: …`), with one repo on `conventional` |
+| Commands | `package.json` scripts, lockfile, Makefile, CI | `npm run lint` |
+| Share specs with the team | your `.gitignore` today | everything / project memory only / local |
 | After you approve a spec | (you choose) | `stop` (wait at each stage) or `run-through` |
-| Model and effort per task tier | written with the defaults above | edit `models:` / `effort:` later |
 
 **Where the file lives, by layout:**
 
@@ -184,34 +167,23 @@ straight away, so you can fix it before moving on. Press Enter on an empty line
 | **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, 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`:
+**Repos in different places.** A multi-repo workspace doesn't need its repos in one folder
+(`/Projects/frontend`, `~/Work/backend`, `/srv/database`). The config goes in their shared parent
+folder, or `~/.spec-driven/<name>/` when that would be your home folder, and is recorded in
+`~/.spec-driven/workspaces.json` so every repo finds it.
 
-```
-✔ 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
-```
+**Teams where people work on different repos.** One developer has the Shopify app and the backend,
+another the dashboard and the backend. Each person's workspace lists only the repos they have, and
+specs go in a place everyone has: a small dedicated specs repo is best. Its `team-repos.yml` lists
+every team repo with its git URL, so setup offers them, `doctor` shows which aren't cloned yet (with
+the clone command), and an investigation stops and says so when a ticket needs a repo that isn't on
+this machine.
 
-- **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`,
-`--project=new|existing`, `--share=all|memory|none`, `--specs-dir=<path>`, `--tools=cursor,codex`, `--global`, `--yes` (accept everything detected), and `--version`.
+**For scripts and CI** there's `spec-driven-dev setup` with flags (it asks nothing):
+`--yes`, `--layout=multi-repo --repos=~/Projects/frontend,~/Work/backend --workspace=~/Projects`,
+`--layout=monorepo --packages=apps/web,packages/ui`, `--specs-dir=<path>`, `--share=all|memory|none`,
+`--after-approval=run-through`, `--project=new|existing`. Installer flags: `--tools=cursor,codex`,
+`--global`, `--no-setup`, `--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
@@ -601,19 +573,19 @@ run one after another, stopping at the first failure or review blocker. Two step
 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 anything.**
-Update to 1.5.1 or later (`npx @benjaminthomas/spec-driven-dev@latest --version`). Earlier versions
-crashed on Node 14 or 16, which nvm often switches to inside older projects, and wrote a config
-silently when there was no terminal. Now it runs on Node 14+. With no terminal to answer in (a `!`
-command in Claude Code, an editor task, piped input), it installs the skills and hands the questions
-to your AI tool: say "run spec-setup" there. `spec-driven-dev setup` on its own still needs a
-terminal, or flags such as `--layout=multi-repo --repos=…`.
+**The installer didn't ask me about my project.**
+That's expected from 1.13.0: the installer only installs the skills. Project setup happens in your
+AI tool: say "run spec-setup". It runs on Node 14+, and works from `!` inside Claude Code too.
+
+**npm prints "Unknown project config" warnings.**
+They come from your project's `.npmrc`, not from this package: settings such as `auto-install-peers`
+or `shamefully-hoist` are for pnpm, and npm warns about them on every `npm`/`npx` command in that
+folder. If the project uses npm (it has a `package-lock.json`), delete those lines. If it uses pnpm,
+run `pnpm dlx @benjaminthomas/spec-driven-dev` instead.
 
-**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`.
+**Setup thought my repo was a monorepo (or a single repo).**
+Tell it in the chat: "this is one repo that works with reverb-backend". A Shopify app's
+`extensions/` folder is treated as part of one app from 1.13.0.
 
 **Can I skip stages?**
 Yes. Every skill works on its own. `spec-verify` even works without a spec: it asks what to check.
@@ -663,7 +635,7 @@ 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 setup --yes                       # 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
@@ -679,7 +651,7 @@ 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,
+example `npx @benjaminthomas/spec-driven-dev doctor`. 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
@@ -713,8 +685,8 @@ install `ticket-to-pr@spec-driven-dev`; the old name no longer gets updates.
 
 To see unfinished specs and their next step at any time, run `spec-driven-dev status`
 (for example, `specs/stp-123: 3/5 tasks done → next: spec-implement`). If
-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.
+you use the plugin, `spec-driven-dev` skips Claude Code so you don't get every skill twice. Then say
+"run spec-setup" in Claude Code for the project config.
 
 ### By hand
 
@@ -768,8 +740,8 @@ skips that step rather than failing.
 
 | Skill | Stage | SKILL.md lines | Words | Supporting files |
 |---|---|---:|---:|---:|
-| `spec-setup` | 0 · configure | 179 | 1,747 | 3 |
-| `spec-investigate` | 1 · understand | 373 | 3,211 | 1 |
+| `spec-setup` | 0 · configure | 210 | 2,201 | 3 |
+| `spec-investigate` | 1 · understand | 387 | 3,367 | 1 |
 | `spec-create` | 2 · plan | 198 | 1,782 | 6 |
 | `spec-implement` | 3 · build | 327 | 2,753 | 3 |
 | `spec-verify` | 4 · prove | 163 | 1,557 | 1 |
@@ -777,7 +749,7 @@ skips that step rather than failing.
 | `spec-checkpoint` | 6 · commit | 140 | 1,144 | 0 |
 | `spec-ship` | 7 · PR | 230 | 1,388 | 0 |
 | `generative-seo` | standalone | 255 | 2,209 | 7 |
-| **Total** | | **2,002** | **17,085** | **22** |
+| **Total** | | **2,047** | **17,695** | **22** |
 
 - **8** skills: **1** setup + **6** workflow stages + **1** standalone
 - **4** tools supported natively (Claude Code, Codex CLI, Cursor, Antigravity), plus an MCP fallback
@@ -830,7 +802,7 @@ plugin/evals/                 `claude plugin eval` cases
   1. Increase `version` in both `package.json` and `plugin/.claude-plugin/plugin.json` (the check fails if
      they differ).
   2. Add a `CHANGELOG.md` entry, then commit and push.
-  3. Tag the release and push the tag: `git tag v1.12.0 && git push origin v1.12.0`.
+  3. Tag the release and push the tag: `git tag v1.13.1 && git push origin v1.13.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`.
 

package/bin/cli.mjs

@@ -2,8 +2,8 @@
 // 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.
 //
-//   spec-driven-dev                 install + project setup (interactive)
-//   spec-driven-dev setup           project setup only
+//   spec-driven-dev                 install the skills, then hand over to your AI tool ("run spec-setup")
+//   spec-driven-dev setup           scripted setup for CI: needs --yes or answer flags (people: say "run spec-setup")
 //   spec-driven-dev doctor          check .spec-driven.yml against the real repos (exit 1 on problems)
 //   spec-driven-dev status          list specs with unfinished work and each one's "Resume here" next step
 //   spec-driven-dev context         print specs/CONTEXT.md; --areas=billing,api prints only those area files
@@ -39,9 +39,24 @@ const args = process.argv.slice(2);
 const flag = (n) => args.includes(`--${n}`);
 const opt = (n) => args.find((a) => a.startsWith(`--${n}=`))?.split("=")[1];
 const command = args.find((a) => !a.startsWith("-")) || "install";
-const YES = flag("yes") || flag("y") || !process.stdin.isTTY || ["doctor", "status", "context", "risk", "risk-eval"].includes(command);
+const YES = flag("yes") || flag("y") || !process.stdin.isTTY || ["doctor", "status", "context", "risk", "risk-eval", "setup"].includes(command);
 const DIR = path.resolve(opt("dir") || process.cwd());
 
+// Colour only for a person at a terminal; pipes, CI and NO_COLOR get plain text (and the tests stay plain).
+const COLOR = (process.stdout.isTTY || !!process.env.FORCE_COLOR) && !process.env.NO_COLOR && process.env.TERM !== "dumb";
+const paint = (code) => (t) => (COLOR ? `\x1b[${code}m${t}\x1b[0m` : t);
+const ink = { green: paint("32"), yellow: paint("33"), red: paint("31"), cyan: paint("36"), magenta: paint("35"), blue: paint("34"), bold: paint("1"), dim: paint("2") };
+// Each stage gets its own colour so the steps are easy to tell apart while scrolling.
+const step = (n, title, color) => console.log(`\n${color(ink.bold(`━━ ${n} · ${title} `))}${color("━".repeat(Math.max(4, 44 - title.length)))}`);
+if (COLOR) {
+  const plain = console.log.bind(console);
+  console.log = (...a) => {
+    const t = a.join(" ");
+    plain(t.replace(/^(\s*)(✓)/gm, (_, s, g) => s + ink.green(g)).replace(/^(\s*)(✗.*)$/gm, (_, s, g) => s + ink.red(g))
+      .replace(/^(\s*)(•)/gm, (_, s, g) => s + ink.yellow(g)).replace(/^(Next:.*)$/gm, (_, g) => ink.cyan(ink.bold(g))));
+  };
+}
+
 if (flag("version") || flag("v")) {
   console.log(JSON.parse(fs.readFileSync(path.join(ROOT, "package.json"), "utf8")).version);
   process.exit(0);
@@ -53,18 +68,17 @@ const NO_TTY = !process.stdin.isTTY && !args.some((a) => ANSWER_FLAGS.some((f) =
 // Installing the skills needs no answers, so the default command still does that without a terminal
 // (e.g. `!` in Claude Code) and hands the questions to the spec-setup skill, which asks them in the chat.
 const HANDOFF = command === "install" && NO_TTY;
-if (["setup", "settings"].includes(command) && NO_TTY) {
+// Setup is a conversation in the AI tool now; the setup command stays for scripts and CI (flags only).
+const SETUP_IN_AGENT = command === "setup" && !args.some((a) => ANSWER_FLAGS.some((f) => a === `--${f}` || a.startsWith(`--${f}=`)));
+if (command === "settings" && NO_TTY) {
   console.log(`✗ No interactive terminal, so ${command === "settings" ? "the settings menu can't open" : "setup can't ask its questions"}. Nothing was changed.
 
   This happens when it runs through another program: a "!" command in Claude Code, an editor task,
   or piped input. Either:
     • run it yourself in a terminal window (Terminal, iTerm, or your editor's terminal panel):
-        npx @benjaminthomas/spec-driven-dev@latest ${command}${command === "setup" ? `
-    • or, in your AI tool (Claude Code, Cursor, Codex), say "run spec-setup": it asks the same
-      questions in the chat` : ""}
-    • or give the answers as flags, for example:
-        npx @benjaminthomas/spec-driven-dev@latest ${command === "settings" ? "settings --risk=off" : "setup --layout=multi-repo --repos=~/Projects/frontend,~/Projects/backend"}
-      (add --yes to accept everything it detects)`);
+        npx @benjaminthomas/spec-driven-dev@latest settings
+    • or give the answer as a flag, for example:
+        npx @benjaminthomas/spec-driven-dev@latest settings --risk=off`);
   process.exit(1);
 }
 
@@ -113,6 +127,7 @@ function copyDir(from, to) {
 
 // ---------- install ----------
 async function install() {
+  step(1, "Install the skills", ink.blue);
   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) tools = await askMulti("Which AI coding tools should get the skills?",
@@ -145,7 +160,33 @@ async function install() {
     console.log(`✓ ${skills.length} skills → ${dest}`);
   }
   if (!dests.length) console.log(HANDOFF ? "• No AI coding tools found (Claude Code, Cursor, Codex or Antigravity). Install one, or pass --tools=claude,cursor." : "• No tools selected — nothing installed.");
-  return dests.length;
+  return dests.length ? tools : [];
+}
+
+// The setup questions (layout, repos, tracker, branches, sharing) and the audit need a model, so they
+// happen in the AI tool. Claude Code and Codex can be opened with the request already typed in.
+const LAUNCHERS = [["claude", "Claude Code"], ["codex", "Codex"]];
+async function handOver(tools, onlySetup) {
+  // The folder says where the AI tool opens; "project" says what gets set up (it can span several repos).
+  const name = path.basename(gitTop(DIR));
+  const what = "It first asks how your project is organised: one repo, a monorepo, or several repos that change together.";
+  const next = `Next: in ${name}, open your AI tool and say "run spec-setup".\n${what}
+Then it asks about your tracker, branches and sharing, and looks through the code.
+Start a new session if your tool doesn't recognise it yet.`;
+  step(onlySetup ? 1 : 2, "Set up your project in your AI tool", ink.magenta);
+  if (onlySetup) {
+    console.log(`Setup happens in your AI tool now, so it can read the code and you can change any answer as you go.\n${next}\nFor scripts and CI: spec-driven-dev setup --yes [--layout=… --repos=… --share=…]`);
+    return;
+  }
+  const launcher = LAUNCHERS.find(([bin]) => tools.includes(bin) && onPath(bin));
+  if (!launcher || !process.stdin.isTTY || YES) { console.log(`Skills installed.\n${next}`); return; }
+  // The question carries the explanation, so there's no paragraph to read twice.
+  if (!(await askConfirm(`Open ${launcher[1]} in ${name} to set up your project? ${what} (A few minutes, on your ${launcher[1]} plan.)`, true))) {
+    console.log(next);
+    return;
+  }
+  const { spawnSync } = await import("node:child_process");
+  spawnSync(launcher[0], ["run spec-setup"], { cwd: DIR, stdio: "inherit" });
 }
 
 // ---------- discovery ----------
@@ -186,7 +227,9 @@ function detectLayout(dir) {
       const base = g.replace(/\/\*\*?$/, "");
       return base === g ? [g.replace(/\/$/, "")] : subdirs(path.join(top, base)).map((n) => `${base}/${n}`);
     }))].filter(hasManifest);
-    const mono = MARKERS.some((m) => fs.existsSync(path.join(top, m))) || pkg?.workspaces || cargo || packages.length > 1;
+    // A Shopify app keeps its app extensions in npm workspaces under extensions/: one app, not a monorepo.
+    const shopifyApp = fs.readdirSync(top).some((f) => /^shopify\.app.*\.toml$/.test(f)) && declared.length > 0 && declared.every((g) => g.startsWith("extensions/"));
+    const mono = !shopifyApp && (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 : [] };
   }
   const repos = findRepos(dir);
@@ -237,11 +280,12 @@ function infer(facts) {
 const y = (v) => JSON.stringify(v ?? ""); // JSON strings are valid YAML scalars
 function toYaml(c) {
   const cmds = (o, pad) => Object.entries(o).map(([k, v]) => `${pad}${k}: ${y(v)}`).join("\n");
-  let out = `# .spec-driven.yml — written by spec-driven-dev setup. Edit freely, or re-run setup.\n# Every spec-* skill reads this first. Field reference: skills/spec-setup/references/config-template.yml\nversion: 1\nlayout: ${c.layout}\n`;
+  let out = `# .spec-driven.yml — written by spec-driven-dev. Edit freely, or say \"run spec-setup\" in your AI tool to review it.\n# Every spec-* skill reads this first. Field reference: skills/spec-setup/references/config-template.yml\nversion: 1\nlayout: ${c.layout}\n`;
   if (c.repos.length) {
     out += "repos:\n" + c.repos.map((r) => {
       let e = `  - path: ${y(r.path)}\n    role: ${y(r.role)}\n`;
-      if (r.base && r.base !== c.git.base_branch) e += `    git:\n      base_branch: ${y(r.base)}\n      pr_target: ${y(r.base)}\n`;
+      const g = [r.base && r.base !== c.git.base_branch ? `      base_branch: ${y(r.base)}\n      pr_target: ${y(r.base)}\n` : "", r.commitStyle ? `      commit_style: ${y(r.commitStyle)}\n` : ""].join("");
+      if (g) e += `    git:\n${g}`;
       if (r.commands && Object.values(r.commands).some(Boolean)) e += `    commands:\n${cmds(r.commands, "      ")}\n`;
       return e;
     }).join("");
@@ -481,7 +525,9 @@ async function setup() {
     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.resolve(root, r)) };
+      // each repo keeps its own commit style when it differs from the workspace's (one repo uses STP-123:, another feat:)
+      const own = f && f.subjects.length >= 5 ? infer([f]).commitStyle : "";
+      return { path: r, role: "", base: f ? f.integration || "default" : "", commitStyle: own && own !== commitStyle ? own : "", commands: commandsFor(path.resolve(root, r)) };
     }),
   };
   fs.writeFileSync(file, toYaml(config));
@@ -555,8 +601,9 @@ function findConfig(dir) {
 }
 
 function doctor() {
+  if (COLOR) step("✓", "Check the settings", ink.cyan);
   const file = findConfig(DIR);
-  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)`);
+  if (!file) throw new Error(`No .spec-driven.yml in ${DIR} or above. In your AI tool, say "run spec-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}`); }
@@ -604,6 +651,17 @@ function doctor() {
   // Multi-repo context names paths from the workspace folder (soreto-shopify/app/) or from inside a repo (app/).
   const repoRoots = c.layout === "multi-repo" ? [root, ...(c.repos || []).map((r) => path.resolve(root, expandHome(r.path)))] : [root];
   checkContext(specs, c.specs_dir || "specs", repoRoots, problems, notes);
+  // The team's repo list (in the specs location) vs the repos on this machine.
+  const team = parseYaml(fs.existsSync(path.join(specs, "team-repos.yml")) ? fs.readFileSync(path.join(specs, "team-repos.yml"), "utf8") : "").repos;
+  if (Array.isArray(team)) {
+    const mine = new Set((c.repos || []).map((r) => path.basename(String(r.path || "").replace(/\/+$/, ""))));
+    for (const t of team) {
+      if (!t.name || mine.has(t.name)) continue;
+      const here = path.join(root, t.name);
+      notes.push(isRepo(here) ? `${t.name} is cloned at ${here} but isn't in this workspace — say "add ${t.name} to the workspace" if you work on it`
+        : `team repo ${t.name} isn't on this machine (fine if you don't work on it)${t.url ? `: git clone ${t.url} ${here}` : ""}`);
+    }
+  }
   if (c.context?.share) {
     if (!SHARE_MODES.includes(c.context.share)) problems.push(`context.share "${c.context.share}" must be all, memory or none`);
     const g = specsInGit(root, c.specs_dir || "specs");
@@ -687,6 +745,7 @@ async function chooseShare(root, specsDir) {
   const g = specsInGit(root, specsDir);
   if (opt("share") && !SHARE_MODES.includes(opt("share"))) throw new Error("--share must be all, memory or none");
   if (!g) { if (opt("share") && opt("share") !== "none") console.log(`  • ${specsDir} isn't inside a git repo, so it can't be shared. Choose a folder inside a repo (--specs-dir) to share it.`); return null; }
+  if (!g.rel) { console.log(`  • ${specsDir} is a repo of its own, so everything in it is shared.`); return "all"; }
   const now = shareState(g.top, g.rel);
   if (now !== "all") console.log(`  • Your .gitignore currently makes ${g.rel}: ${shareTitle[now].toLowerCase()}.`);
   return opt("share") || askSelect("Share specs and project memory with your team?", [
@@ -699,6 +758,7 @@ async function chooseShare(root, specsDir) {
 async function applyShare(root, specsDir, mode, { quietIfSame } = {}) {
   const g = specsInGit(root, specsDir);
   if (!g) { console.log(`  • ${specsDir} isn't inside a git repo, so there's nothing to share or ignore.`); return; }
+  if (!g.rel) mode = "all"; // a dedicated specs repo is shared by definition
   if (quietIfSame && shareState(g.top, g.rel) === mode && mode !== "all") return;
   const gi = path.join(g.top, ".gitignore");
   const before = fs.existsSync(gi) ? fs.readFileSync(gi, "utf8") : "";
@@ -804,7 +864,7 @@ const SETTINGS = [
 
 async function settings() {
   const file = findConfig(DIR);
-  if (!file) throw new Error(`No .spec-driven.yml in ${DIR} or above. Run: spec-driven-dev setup`);
+  if (!file) throw new Error(`No .spec-driven.yml in ${DIR} or above. In your AI tool, say "run spec-setup" first.`);
   let text = fs.readFileSync(file, "utf8");
   const label = (s, v) => s.options.find((o) => o.value === v)?.title || v;
   const save = async (s, v) => {
@@ -864,20 +924,14 @@ try {
   else if (command === "risk") risk();
   else if (command === "settings") await settings();
   else if (command === "risk-eval") await riskEvalCmd();
-  else if (command === "install" && HANDOFF) {
-    console.log("No interactive terminal (for example a \"!\" command in Claude Code), so this installs the skills\nwith the detected defaults and leaves the setup questions to your AI tool.\n");
-    const n = await install();
-    if (n) console.log(`
-Next: in your AI tool, say "run spec-setup". It asks the setup questions in the chat
-(single repo, monorepo or multi-repo, tracker, branches) and writes .spec-driven.yml.
-If your AI tool doesn't recognise it yet, start a new session so it loads the new skills.
-To answer in a terminal instead, open Terminal or iTerm and run: npx @benjaminthomas/spec-driven-dev setup`);
-  } else if (command === "install") {
-    await install();
-    if (!flag("no-setup") && (await askConfirm("Set up this project now?", true))) await setup();
-  } else if (command === "setup") await setup();
+  else if (command === "install") {
+    if (HANDOFF) console.log("No interactive terminal (for example a \"!\" command in Claude Code), so the skills go to the AI tools it finds, for this project.\n");
+    const tools = await install();
+    if (tools.length && !flag("no-setup")) await handOver(tools);
+  } else if (SETUP_IN_AGENT) handOver([], true);
+  else if (command === "setup") await setup();
   else throw new Error(`Unknown command "${command}" — use install (default), setup, settings, doctor, status, context, risk, or risk-eval`);
-  if (["install", "setup"].includes(command) && !HANDOFF) console.log('\nNext: in your AI tool, say "investigate <ticket>" or "create a spec".');
+  if (command === "setup" && !SETUP_IN_AGENT) console.log('\nNext: in your AI tool, say "investigate <ticket>" or "create a spec".');
 } catch (e) {
   console.error(`✗ ${e.message}`);
   process.exitCode = 1;

package/bin/share.mjs

@@ -12,13 +12,16 @@ const git = (cwd, args) => {
 const ignored = (top, rel) => !!git(top, ["check-ignore", "--no-index", rel]);
 
 // What git does today: is the project memory ignored, and is a feature's working folder ignored?
+const under = (specs, p) => (specs ? `${specs}/${p}` : p); // specs can be a whole repo (a dedicated specs repo)
+
 export function shareState(top, specs) {
-  const memory = !ignored(top, `${specs}/CONTEXT.md`) && !ignored(top, `${specs}/context/notes.md`);
-  const features = !ignored(top, `${specs}/some-feature/README.md`);
+  const memory = !ignored(top, under(specs, "CONTEXT.md")) && !ignored(top, under(specs, "context/notes.md"));
+  const features = !ignored(top, under(specs, "some-feature/README.md"));
   return features && memory ? "all" : memory ? "memory" : features ? "custom" : "none";
 }
 
 export function blockFor(specs, mode) {
+  if (!specs) return [BEGIN, "/context/risk.md", END]; // a specs repo exists to be shared: only the generated file is ignored
   const lines = mode === "none" ? [`${specs}/`]
     : mode === "memory" ? [`${specs}/*`, `!${specs}/CONTEXT.md`, `!${specs}/context/`, `${specs}/context/risk.md`]
     : [`${specs}/context/risk.md`];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@benjaminthomas/spec-driven-dev",
-  "version": "1.12.0",
+  "version": "1.13.1",
   "description": "Spec-driven AI development workflow (investigate → spec → implement → verify → review → ship) as Agent Skills for Claude Code, Cursor, Codex CLI and Antigravity.",
   "type": "module",
   "bin": {

package/plugin/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "ticket-to-pr",
-  "version": "1.12.0",
+  "version": "1.13.1",
   "description": "Parallel-batch spec-driven feature workflow (spec-setup, spec-investigate, spec-create, spec-implement, spec-verify, spec-review, spec-checkpoint, spec-ship) plus a portable SEO/GEO operations skill (generative-seo) for any codebase.",
   "author": {
     "name": "Benjamin Thomas",

package/plugin/skills/spec-investigate/SKILL.md

@@ -65,6 +65,18 @@ Cheap sources first, code second:
 
 No CONTEXT.md? Investigate as usual, and suggest running `spec-setup` afterwards to create one.
 
+## Repos this machine doesn't have (multi-repo)
+
+The workspace config lists only the repos cloned here. If the ticket or the evidence points at a
+repo that isn't listed (its name in the ticket, an API or package it owns, a `team-repos.yml` role
+that matches), **stop before concluding** and say so plainly:
+
+> This ticket also touches **reverb-react** (the merchant dashboard), which isn't on this machine.
+> Clone it: `git clone <url from team-repos.yml> <workspace>/reverb-react`, then say "add
+> reverb-react to the workspace" and investigate again. Or I can carry on and mark that part UNKNOWN.
+
+Never present a cross-repo change as complete when part of it lives in a repo you couldn't read.
+
 ## Risk signal (GitRisk)
 
 Use it only when `.spec-driven.yml` has `risk.enabled: on`, or has no `risk:` block, **and**
@@ -72,12 +84,14 @@ Use it only when `.spec-driven.yml` has `risk.enabled: on`, or has no `risk:` bl
 file, compute scores, or mention risk. That keeps on/off comparisons (`spec-driven-dev risk-eval`)
 clean.
 
-1. Once you know the change surface, look up its files: `spec-driven-dev risk --files=a,b` (or
+1. **Required, not optional:** once you know the change surface, and before writing the report, look up its files: `spec-driven-dev risk --files=a,b` (or
    `npx -y @benjaminthomas/spec-driven-dev risk --files=…`), or find them in `risk.md`. Without the
    CLI, approximate a file's history with `git log --since="2 years ago" --format=%s -- <file>`.
 2. For each **high** or **critical** file in the surface, look harder: read its last ~10 commit
    subjects and the diffs of its last 1–2 fix commits, and check its dependents. Write what keeps
    breaking there in the report's **Risk Hotspots** section.
+   The report's **Risk Hotspots** section must exist when risk is on: list the high/critical files,
+   or write "none of the touched files are high or critical (checked)" so a reader knows it was done.
 3. A score is a reason to look harder, never evidence. Hotspot findings still need their
    VERIFIED / INFERRED labels.
 4. **New files** (added in the last 90 days with fewer than 3 commits, or not committed yet) show as tier `new`: too little

package/plugin/skills/spec-setup/SKILL.md

@@ -17,7 +17,9 @@ license: MIT
 # spec-setup
 
 Learn this project's rules and context once, save them, and let every other `spec-*` skill reuse
-them. Team rules live in a config file the team can review and change — never in the skills
+them. This is **the** setup: the npm installer only copies the skills and then sends people here, so
+treat it as their first conversation with the workflow. Explain each question in a line, and let
+them change any earlier answer at any point ("actually it's Jira") before you write anything. Team rules live in a config file the team can review and change — never in the skills
 themselves. What the project *knows* (areas, conventions, decisions) lives in
 `{specs_dir}/CONTEXT.md`, kept small so loading it is cheap.
 
@@ -44,6 +46,11 @@ Read, don't guess. Collect a draft of every field in `references/config-template
      `package.json`, `turbo.json`, `nx.json`, `lerna.json`, `go.work`, `[workspace]` in
      `Cargo.toml`, several `apps/*`/`packages/*`/`services/*` with their own manifests) →
      `monorepo`; list the packages.
+   - **Not a monorepo:** a Shopify app (`shopify.app*.toml` at the root) whose workspaces only cover
+     `extensions/`. Those are parts of one app deployed together, so it's `single` (or one repo of a
+     multi-repo workspace). The same goes for any repo whose "packages" are plug-ins of one app.
+   - **Ask when one repo works with others.** Even inside a single repo, ask once: "Does this repo
+     change together with other repos (for example a backend)?" A yes means `multi-repo`.
    - 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. Always also ask whether
@@ -68,7 +75,9 @@ Read, don't guess. Collect a draft of every field in `references/config-template
    `gh repo view --json defaultBranchRef`); integration branches (`staging`, `develop`,
    `pre-prod`); which branch recent PRs targeted (`gh pr list --state merged --limit 20 --json
    baseRefName`); the pattern of the last ~20 remote branch names; the commit style from
-   `git log -30 --format=%s`.
+   `git log -30 --format=%s`. Judge commit style **per repo**: when one repo writes `STP-123: …` and
+   the others write `feat: …`, keep the majority at the top level and give that repo its own
+   `git.commit_style`.
 5. **Commands, per repo/package.** `package.json` scripts plus the lockfile's package manager,
    `Makefile`, `pyproject.toml`/`tox.ini`, `Cargo.toml`, `go.mod`, `composer.json`, CI workflow
    steps (CI is often the most truthful source). Dev URL from the dev script, `.env.example`, or
@@ -82,7 +91,22 @@ Read, don't guess. Collect a draft of every field in `references/config-template
    pushing. Store it as `pipeline.after_approval`.
 8. **New or existing project.** Detect it (commit and file counts) and confirm in one line. Store
    it as `context.project`. This decides what Step 4 does.
-9. **Sharing with the team.** Find out what git does with the specs folder today:
+9. **Where specs live (multi-repo).** One specs folder serves the whole workspace: each ticket gets
+   one folder there even when it changes several repos; code, branches and PRs stay in each repo.
+   Offer, in this order, with the reason for each:
+   - **A dedicated specs repo (recommended for teams where developers work on different subsets of
+     repos):** everyone clones it, whatever code repos they have. Use an existing one (path or git
+     URL; offer the `git clone` command) or create one: only after a yes, `mkdir` it next to the
+     repos and `git init`. Never create a remote repo; say how to push it (`gh repo create`).
+     Then set `specs_dir: <specs-repo>` (its root holds `CONTEXT.md`, `context/` and feature folders).
+   - **Inside one code repo** (`<repo>/specs`): fine when every developer has that repo.
+   - **The workspace folder:** on this machine only, since it isn't a git repo.
+10. **The team's repo list.** Keep `{specs_dir}/team-repos.yml` (see `references/config-template.yml`)
+   listing every repo the team works across with its git URL and a one-line role. Each developer's
+   own `.spec-driven.yml` lists only the repos they have. When the file exists, offer its repos
+   instead of making people remember them, and for any not cloned here show
+   `git clone <url> <workspace>/<name>`. When someone adds a repo, add it to the file too.
+11. **Sharing with the team.** Find out what git does with the specs folder today:
    `git check-ignore -v {specs_dir}/CONTEXT.md` and `git check-ignore -v {specs_dir}/x/README.md`.
    Then ask once, saying what's true now (e.g. "your .gitignore ignores `specs/`, so nothing is
    shared today"):
@@ -93,7 +117,8 @@ Read, don't guess. Collect a draft of every field in `references/config-template
 
    **Multi-repo:** if the config folder isn't a git repo, specs kept there can't be shared. Say so
    and offer `specs_dir: <repo>/specs` inside the repo the team treats as home.
-   Store the answer as `context.share`.
+   Store the answer as `context.share`. A dedicated specs repo is shared by nature: set
+   `context.share: all`.
 
 ## Step 2 — Confirm in one round
 
@@ -145,6 +170,11 @@ Skip if `{specs_dir}/CONTEXT.md` already exists (offer a refresh instead, see `r
 6. Re-run `npx -y @benjaminthomas/spec-driven-dev doctor` if available. It checks the size limits
    and flags context lines that point to files which no longer exist.
 
+## After setup
+
+Finish with **one** next step, not a list: "Setup's done. Say *investigate STP-123* to start your
+first ticket." If anything was left out (a tracker URL, a repo not cloned), name it in one line.
+
 ## Quick switches (plain words, no YAML)
 
 When the user asks to switch a feature on or off, change only that one line of `.spec-driven.yml`,
@@ -156,6 +186,7 @@ keep every other line and comment, and confirm in one sentence. Don't re-run dis
 | "turn GitRisk on", "use the risk scores" | `risk.enabled: on`, then run `spec-driven-dev risk` if `{specs_dir}/context/risk.md` doesn't exist yet |
 | "run straight through after I approve", "fewer stops" | `pipeline.after_approval: run-through` |
 | "stop after each stage" | `pipeline.after_approval: stop` |
+| "add reverb-react to the workspace", "I also work on X" | add it under `repos:` (clone first if needed, from `team-repos.yml`), and to `team-repos.yml` if it's new to the team |
 | "share the specs with the team", "keep specs local", "share only the project memory" | `context.share: all / none / memory`: show the `.gitignore` change, then run `spec-driven-dev settings --share=…` on a yes |
 
 Reply with what changed and what it means, for example: "GitRisk is now off. Investigations, plans

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

@@ -101,4 +101,15 @@ context:
                                 # CONTEXT.md + context/ | none = ignore the specs folder. risk.md is always ignored.
                                 # Change with: spec-driven-dev settings --share=…
 
-specs_dir: specs                # where specs/<feature>/ folders go (relative to this file)
+specs_dir: specs                # where specs/<feature>/ folders go (relative to this file).
+                                # Multi-repo teams: a dedicated specs repo (e.g. soreto-specs) everyone clones.
+
+# {specs_dir}/team-repos.yml — every repo the team works across, shared with the specs. Each developer's
+# .spec-driven.yml lists only the repos they have; setup offers the rest with their clone commands.
+# repos:
+#   - name: reverb-backend
+#     url: git@github.com:acme/reverb-backend.git
+#     role: REST API and workers
+#   - name: reverb-react
+#     url: git@github.com:acme/reverb-react.git
+#     role: merchant dashboard