@benjaminthomas/spec-driven-dev 1.11.2 → 1.13.0

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`, `--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
@@ -249,6 +221,25 @@ lines that point to files that no longer exist. If you install
 [graphify](https://github.com/Graphify-Labs/graphify), the skills use it for cheaper code
 navigation. It's optional (`context.graph: off` turns it off), and nothing is installed for you.
 
+### Sharing specs with your team
+
+Setup asks whether to commit the specs folder, and shows what your `.gitignore` does today:
+
+| Choice | What's committed | Good for |
+|---|---|---|
+| **Share everything** (recommended) | plans, investigations, reviews and project memory | teams that review plans in PRs, and handovers |
+| **Share project memory only** | `specs/CONTEXT.md` and `specs/context/` | sharing what the project knows, keeping per-ticket files local |
+| **Keep everything local** | nothing (`specs/` is ignored) | trying it out, or personal use |
+
+Setup changes `.gitignore` only after you agree, edits one marked block, and replaces only lines about
+the specs folder. `risk.md` is always ignored. Change your mind any time with
+`spec-driven-dev settings --share=all|memory|none`, or say "share the specs with the team" in your AI
+tool. `doctor` warns if `.gitignore` drifts from your choice.
+
+**Multi-repo:** the workspace folder usually isn't a git repo, so specs kept there stay on your
+machine. To share them, choose a specs folder inside the repo your team treats as home, for example
+`--specs-dir=frontend/specs`.
+
 ### GitRisk: which files have a history of breaking
 
 `spec-driven-dev risk` scores every tracked code file from git history alone, with no model and no
@@ -568,6 +559,11 @@ confirm. To change it, edit `git.base_branch` / `git.branch_name` or run setup a
 For a single repo or monorepo, yes: the whole team then follows the same rules. A multi-repo
 config sits outside any repo, so it stays on your machine.
 
+**Should I commit the specs?**
+Setup asks. Sharing everything is recommended: teammates and reviewers see the plans and the
+reasoning, and the project memory builds up for everyone. See
+[Sharing specs with your team](#sharing-specs-with-your-team).
+
 **Does it work with my stack?**
 Yes. No skill assumes a language or framework. Each one finds the repo's own commands.
 
@@ -577,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.
@@ -639,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
@@ -647,7 +643,7 @@ spec-driven-dev --yes                             # accept every detected defaul
 spec-driven-dev doctor                            # check .spec-driven.yml against the real repos
 spec-driven-dev status                            # list unfinished specs and each one's next step
 spec-driven-dev context --areas=billing           # print the project memory (index, or chosen areas)
-spec-driven-dev settings                          # switch GitRisk and run-through on/off from a menu
+spec-driven-dev settings                          # switch GitRisk, run-through and sharing from a menu
 spec-driven-dev risk                              # GitRisk: score files from git history → specs/context/risk.md
 spec-driven-dev risk-eval --tickets=tickets.md    # compare agent behaviour with the risk signal on vs off
                                                   #   (--runs=3 --arms=on --timeout=20 --model=sonnet)
@@ -655,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
@@ -689,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
 
@@ -744,8 +740,8 @@ skips that step rather than failing.
 
 | Skill | Stage | SKILL.md lines | Words | Supporting files |
 |---|---|---:|---:|---:|
-| `spec-setup` | 0 · configure | 162 | 1,545 | 3 |
-| `spec-investigate` | 1 · understand | 373 | 3,211 | 1 |
+| `spec-setup` | 0 · configure | 210 | 2,201 | 3 |
+| `spec-investigate` | 1 · understand | 385 | 3,325 | 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 |
@@ -753,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** | | **1,985** | **16,883** | **22** |
+| **Total** | | **2,045** | **17,653** | **22** |
 
 - **8** skills: **1** setup + **6** workflow stages + **1** standalone
 - **4** tools supported natively (Claude Code, Codex CLI, Cursor, Antigravity), plus an MCP fallback
@@ -777,6 +773,7 @@ bin/spec-driven-dev.cjs       launcher (runs on any Node, explains if it's too o
 bin/cli.mjs                   the `spec-driven-dev` CLI: installer, setup menus, doctor, status, context, risk
 bin/risk.mjs                  GitRisk scoring (churn, bug density, fan-out, security)
 bin/risk-eval.mjs             risk on/off experiment harness
+bin/share.mjs                 what's committed from the specs folder (.gitignore block)
 package.json                  npm package (ships bin/ and plugin/skills/)
 mcp-server/                   MCP fallback server
 CHANGELOG.md                  what changed in each version
@@ -805,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.11.2 && git push origin v1.11.2`.
+  3. Tag the release and push the tag: `git tag v1.13.0 && git push origin v1.13.0`.
   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,17 +2,17 @@
 // 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
 //   spec-driven-dev risk            GitRisk: score files from git history into specs/context/risk.md (--files=a,b  --json  --top=N  --since=…)
-//   spec-driven-dev settings        switch features on or off from a menu (GitRisk, run-through); or --risk=on|off --after-approval=…
+//   spec-driven-dev settings        switch features from a menu (GitRisk, run-through, sharing); or --risk=on|off --after-approval=… --share=all|memory|none
 //   spec-driven-dev risk-eval       U8 experiment: run tickets with risk on vs off and compare agent behaviour (--tickets=<file> --runs=N --model=… --arms=on,off --timeout=20)
 //   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  --project=new|existing  --risk=on|off  --version
+//          --packages=apps/web,packages/ui  --after-approval=stop|run-through  --project=new|existing  --risk=on|off  --share=all|memory|none  --specs-dir=<path>  --version
 import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
@@ -20,6 +20,7 @@ import { execFileSync } from "node:child_process";
 import prompts from "prompts";  // arrow-key menus that work in PowerShell, cmd, macOS and Linux terminals
 import { fileURLToPath } from "node:url";
 import { scoreRepo, riskMarkdown, normWeights, weightProblems, setConfigValue } from "./risk.mjs";
+import { SHARE_MODES, shareState, planShare, shareTitle } from "./share.mjs";
 
 const ROOT = path.dirname(path.dirname(fileURLToPath(import.meta.url)));
 const SKILLS_DIR = path.join(ROOT, "plugin", "skills");
@@ -38,32 +39,46 @@ 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);
 }
 // No terminal to answer in (e.g. `!` in Claude Code, an IDE task, a pipe) and nothing passed explicitly:
 // stop rather than write a config from guesses.
-const ANSWER_FLAGS = ["risk", "yes", "y", "layout", "repos", "packages", "tools", "workspace", "after-approval", "skills", "global", "no-setup", "project"];
+const ANSWER_FLAGS = ["share", "specs-dir", "risk", "yes", "y", "layout", "repos", "packages", "tools", "workspace", "after-approval", "skills", "global", "no-setup", "project"];
 const NO_TTY = !process.stdin.isTTY && !args.some((a) => ANSWER_FLAGS.some((f) => a === `--${f}` || a.startsWith(`--${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);
 }
 
@@ -112,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?",
@@ -144,7 +160,26 @@ 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) {
+  const name = path.basename(gitTop(DIR));
+  step(onlySetup ? 1 : 2, `Set up ${name} in your AI tool`, ink.magenta);
+  console.log(`
+${onlySetup ? "Setup happens in your AI tool now, so it can read the code and you can change any answer as you go." : "Skills installed."}
+Next: set up ${name}. In your AI tool, say "run spec-setup". It asks how the project is organised
+(single repo, monorepo, or several repos), your tracker, branches and whether to share specs,
+then looks through the code. Start a new session if your tool doesn't recognise it yet.${onlySetup ? `
+For scripts and CI: spec-driven-dev setup --yes [--layout=… --repos=… --share=…]` : ""}`);
+  const launcher = LAUNCHERS.find(([bin]) => (onlySetup || tools.includes(bin)) && onPath(bin));
+  if (!launcher || !process.stdin.isTTY || YES || onlySetup) return;
+  if (!(await askConfirm(`Open ${launcher[1]} here now and start it? (takes a few minutes, uses your ${launcher[1]} plan)`, true))) return;
+  const { spawnSync } = await import("node:child_process");
+  spawnSync(launcher[0], ["run spec-setup"], { cwd: DIR, stdio: "inherit" });
 }
 
 // ---------- discovery ----------
@@ -185,7 +220,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);
@@ -236,11 +273,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("");
@@ -252,7 +290,7 @@ function toYaml(c) {
     .map(([tool, m]) => `  ${tool}:\n` + MODEL_KEYS.map((t) => `    ${t}: ${m[t]}\n`).join("")).join("");
   out += "effort:   # effort / reasoning level per tier (Claude Code, Codex): low | medium | high | xhigh | max | default\n"
     + MODEL_KEYS.map((t) => `  ${t}: ${EFFORT_DEFAULTS[t]}\n`).join("");
-  out += `context:   # project memory: {specs_dir}/CONTEXT.md (index) + context/<area>.md\n  project: ${c.project || "existing"}   # existing | new\n  graph: auto   # auto = use graphify if installed | off\n`;
+  out += `context:   # project memory: {specs_dir}/CONTEXT.md (index) + context/<area>.md\n  project: ${c.project || "existing"}   # existing | new\n  graph: auto   # auto = use graphify if installed | off\n  share: ${c.share || "all"}   # all | memory | none: what's committed from the specs folder\n`;
   out += "risk:   # GitRisk: historical risk per file from git (spec-driven-dev risk). Weights are a hypothesis to calibrate\n  enabled: on   # on | off (off = skills ignore risk; risk-eval compares the two)\n  since: \"2 years ago\"\n  weights:\n    churn: 0.30\n    bug_density: 0.35\n    fan_out: 0.20\n    security: 0.15\n";
   out += `pipeline:\n  after_approval: ${c.afterApproval || "stop"}   # stop | run-through (implement → verify → review → checkpoint; ship always asks)\n`;
   return out + `specs_dir: ${y(c.specsDir)}\n`;
@@ -460,7 +498,8 @@ async function setup() {
     { title: `${ex}-123: add login${det("ticket", g.commitStyle)}`, value: "ticket", description: "ticket ID first" },
     { title: `Add login${det("freeform", g.commitStyle)}`, value: "freeform", description: "no fixed format" },
   ], g.commitStyle);
-  const specsDir = await askText("Folder for specs (one sub-folder per feature)", "specs");
+  const specsDir = await chooseSpecsDir(layout, root, repos);
+  const share = await chooseShare(root, specsDir);
   const afterApproval = opt("after-approval") || await askSelect("After you approve a spec…", [
     { title: "Stop after each stage", value: "stop", description: "you start implement, verify and checkpoint yourself" },
     { title: "Run straight through", value: "run-through", description: "implement → verify → review → commit in one go; stops at any failure or review blocker, never pushes without asking" },
@@ -473,18 +512,21 @@ async function setup() {
   ], pd.kind);
 
   const config = {
-    project, layout, tracker: { type: trackerType, key, url }, specsDir, devUrl: "", afterApproval,
+    project, share: share || "none", layout, tracker: { type: trackerType, key, url }, specsDir, devUrl: "", afterApproval,
     git: { remote: "origin", base_branch: base, pr_target: pr, branch_name: branchName, commit_style: commitStyle },
     commands: layout === "single" ? commandsFor(repoDirs[0]) : commandsFor(root),
     repos: repos.map((r) => {
       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));
   if (layout === "multi-repo") register(real(file), repos.map((r) => real(path.resolve(root, r))));
   console.log(`✓ Wrote ${file}`);
+  if (share) await applyShare(root, specsDir, share, { quietIfSame: true });
   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(project === "existing"
     ? `  Next: ask your AI tool to "run spec-setup". It audits the ${layout === "multi-repo" ? "repos" : "repo"}, asks a few questions, and saves ${specsDir}/CONTEXT.md.`
@@ -552,8 +594,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}`); }
@@ -598,8 +641,27 @@ function doctor() {
   if (!fs.existsSync(specs)) notes.push(`${c.specs_dir || "specs"}/ doesn't exist yet — created on first spec`);
   if (c.context?.project && !["new", "existing"].includes(c.context.project)) problems.push(`context.project "${c.context.project}" must be new or existing`);
   if (c.context?.graph && !["auto", "off"].includes(c.context.graph)) problems.push(`context.graph "${c.context.graph}" must be auto or off`);
-  const repoRoots = c.layout === "multi-repo" ? (c.repos || []).map((r) => path.resolve(root, expandHome(r.path))) : [root];
+  // 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");
+    if (!g && c.context.share !== "none") notes.push(`context.share is ${c.context.share}, but ${c.specs_dir || "specs"} isn't inside a git repo, so nothing can be shared`);
+    else if (g && SHARE_MODES.includes(c.context.share) && shareState(g.top, g.rel) !== c.context.share)
+      notes.push(`context.share is ${c.context.share}, but .gitignore makes it "${shareTitle[shareState(g.top, g.rel)].toLowerCase()}". Fix: spec-driven-dev settings --share=${c.context.share}`);
+  }
   const rmd = path.join(specs, "context", "risk.md"), rtop = run("git", ["rev-parse", "--show-toplevel"], root);
   if (rtop && fs.existsSync(rmd) && run("git", ["ls-files", path.relative(path.resolve(rtop), real(rmd))], rtop))
     problems.push(`${c.specs_dir || "specs"}/context/risk.md is committed to git. It's regenerated on every run, so it causes merge conflicts. Run: git rm --cached ${path.relative(path.resolve(rtop), real(rmd))}  (spec-driven-dev risk adds it to .gitignore)`);
@@ -651,6 +713,60 @@ function context() {
   }
 }
 
+// ---------- sharing specs through git ----------
+function specsInGit(root, specsDir) {
+  const abs = path.resolve(root, specsDir);
+  let probe = abs;
+  while (!fs.existsSync(probe)) probe = path.dirname(probe);
+  const top = run("git", ["rev-parse", "--show-toplevel"], probe);
+  if (!top) return null;
+  const rel = path.relative(path.resolve(top), real(probe)).split(path.sep).concat(path.relative(probe, abs).split(path.sep)).filter((x) => x && x !== ".").join("/");
+  return rel.startsWith("..") ? null : { top, rel };
+}
+
+async function chooseSpecsDir(layout, root, repos) {
+  if (opt("specs-dir")) return opt("specs-dir");
+  if (layout !== "multi-repo" || isRepo(root)) return askText("Folder for specs (one sub-folder per feature)", "specs");
+  // The workspace folder isn't a repo, so specs kept there can never be shared through git.
+  return askSelect("Where should specs and project memory live?", [
+    { title: `In this workspace folder (${path.join(root, "specs")})`, value: "specs", description: "on this machine only; it isn't a git repo, so it can't be shared" },
+    ...repos.map((r) => ({ title: `Inside ${r}/specs`, value: `${r}/specs`.replace(/^\.\//, ""), description: "can be shared with the team through that repo" })),
+  ], "specs");
+}
+
+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?", [
+    { title: `Share everything${now === "all" ? "  (current)" : ""}  (recommended)`, value: "all", description: "commit plans, investigations, reviews and project memory; teammates and PR reviewers see the reasoning" },
+    { title: `Share project memory only${now === "memory" ? "  (current)" : ""}`, value: "memory", description: "commit CONTEXT.md and context/; keep each feature's working files local" },
+    { title: `Keep everything local${now === "none" ? "  (current)" : ""}`, value: "none", description: "ignore the specs folder; nothing is shared" },
+  ], now === "custom" ? "all" : now);
+}
+
+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") : "";
+  const plan = planShare(before, g.rel, mode);
+  if (plan.text === before) return;
+  if (plan.removed.length && !opt("share") && !(await askConfirm(`To ${shareTitle[mode].toLowerCase()}, these .gitignore lines would be replaced: ${plan.removed.join(", ")}. Go ahead?`, true))) {
+    console.log("  • Left .gitignore as it was. Change it later with: spec-driven-dev settings");
+    return;
+  }
+  fs.writeFileSync(gi, plan.text);
+  console.log(`  ✓ .gitignore updated: ${shareTitle[mode].toLowerCase()}${plan.removed.length ? ` (replaced: ${plan.removed.join(", ")})` : ""}.`);
+  const now = shareState(g.top, g.rel);
+  if (now !== mode) console.log(`  • Another ignore rule (a nested .gitignore or your global git excludes) still makes it "${shareTitle[now].toLowerCase()}". Check: git check-ignore -v ${g.rel}/CONTEXT.md`);
+}
+
 // risk.md is regenerated on every run (it carries a date), so committing it means noisy diffs and merge
 // conflicts between branches. Keep it out of git like a build output; anyone can recreate it in a second.
 function ignoreGenerated(file) {
@@ -732,21 +848,27 @@ const SETTINGS = [
     get: (c) => c.pipeline?.after_approval || "stop", options: [
       { value: "stop", title: "Stop after each stage", description: "you start implement, verify, review and commit yourself" },
       { value: "run-through", title: "Run straight through", description: "implement → verify → review → commit; stops at any failure, never pushes" }] },
+  { block: "context", key: "share", flag: "share", name: "Share specs with the team", about: "what's committed from the specs folder",
+    get: (c) => c.context?.share || "all", after: (file, c, v) => applyShare(path.dirname(file), c.specs_dir || "specs", v), options: [
+      { value: "all", title: "Share everything", description: "commit plans, investigations, reviews and project memory" },
+      { value: "memory", title: "Share project memory only", description: "commit CONTEXT.md and context/; keep feature files local" },
+      { value: "none", title: "Keep everything local", description: "ignore the specs folder" }] },
 ];
 
 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 = (s, v) => {
+  const save = async (s, v) => {
     if (!s.options.some((o) => o.value === v)) throw new Error(`--${s.flag} must be ${s.options.map((o) => o.value).join(" or ")}`);
     text = setConfigValue(text, s.block, s.key, v);
     fs.writeFileSync(file, text);
     console.log(`✓ ${s.name}: ${label(s, v)}  (saved in ${file})`);
+    if (s.after) await s.after(file, parseYaml(text), v);
   };
   const given = SETTINGS.filter((s) => opt(s.flag));
-  if (given.length) given.forEach((s) => save(s, opt(s.flag)));
+  if (given.length) for (const s of given) await save(s, opt(s.flag));
   else for (;;) {
     const c = parseYaml(text);
     const pick = await askSelect("Settings: pick one to change", [
@@ -754,7 +876,7 @@ async function settings() {
       { title: "Done", value: null }], null);
     if (!pick) break;
     const v = await askSelect(`${pick.name}`, pick.options, pick.get(c));
-    if (v !== pick.get(c)) save(pick, v);
+    if (v !== pick.get(c)) await save(pick, v);
   }
   const c = parseYaml(text);
   if (c.risk?.enabled !== "off" && !fs.existsSync(path.join(path.dirname(file), c.specs_dir || "specs", "context", "risk.md"))) {
@@ -795,20 +917,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

@@ -0,0 +1,49 @@
+// Whether specs and project memory are shared through git: all | memory | none.
+// We manage one marked block in .gitignore and only remove lines that are plainly about the specs folder.
+import { execFileSync } from "node:child_process";
+
+export const SHARE_MODES = ["all", "memory", "none"];
+const BEGIN = "# spec-driven-dev: what's shared from the specs folder (spec-driven-dev settings --share=…)";
+const END = "# end spec-driven-dev";
+
+const git = (cwd, args) => {
+  try { return execFileSync("git", args, { cwd, stdio: ["ignore", "pipe", "ignore"] }).toString().trim(); } catch { return ""; }
+};
+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, 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`];
+  return [BEGIN, ...lines, END];
+}
+
+// New .gitignore text for a mode, plus which existing lines would go, so the caller can ask first.
+export function planShare(text, specs, mode) {
+  const s = specs.replace(/^\/+|\/+$/g, "");
+  const about = new Set([s, `${s}/`, `/${s}`, `/${s}/`, `${s}/*`, `/${s}/*`, `${s}/**`, `!${s}/CONTEXT.md`, `!${s}/context/`, `${s}/context/risk.md`, `/${s}/context/risk.md`,
+    "# GitRisk scores, regenerated by spec-driven-dev risk"]);
+  const kept = [], removed = [];
+  let inBlock = false;
+  for (const line of text.split("\n")) {
+    if (line === BEGIN) { inBlock = true; continue; }
+    if (inBlock) { if (line === END) inBlock = false; continue; }
+    if (about.has(line.trim())) { if (!line.startsWith("# GitRisk") && !line.trim().endsWith("risk.md")) removed.push(line.trim()); continue; }
+    kept.push(line);
+  }
+  while (kept.length && kept[kept.length - 1] === "") kept.pop();
+  const body = kept.join("\n");
+  return { text: `${body}${body ? "\n\n" : ""}${blockFor(s, mode).join("\n")}\n`, removed };
+}
+
+export const shareTitle = { all: "Share everything", memory: "Share project memory only", none: "Keep everything local", custom: "Partly shared (custom rules)" };

package/package.json

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

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

@@ -1,6 +1,6 @@
 {
   "name": "ticket-to-pr",
-  "version": "1.11.2",
+  "version": "1.13.0",
   "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**

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,6 +91,34 @@ 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. **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"):
+   - **Share everything (recommended):** commit plans, investigations, reviews and project memory,
+     so teammates and PR reviewers see the reasoning and the memory grows for everyone.
+   - **Share project memory only:** commit `CONTEXT.md` and `context/`; feature files stay local.
+   - **Keep everything local:** ignore the specs folder.
+
+   **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`. A dedicated specs repo is shared by nature: set
+   `context.share: all`.
 
 ## Step 2 — Confirm in one round
 
@@ -118,17 +155,26 @@ Skip if `{specs_dir}/CONTEXT.md` already exists (offer a refresh instead, see `r
    intended stack and conventions for a new one. One round of questions, no more.
 2. Write `{specs_dir}/CONTEXT.md` (and any area files) using `references/context-template.md`.
    Keep the index to 60 lines and area files to 150.
-3. **Risk scores.** For an existing project, run `spec-driven-dev risk` (or
+3. **Apply the sharing choice.** Show the exact `.gitignore` lines that will be replaced or added,
+   and change it only after a yes, by running `spec-driven-dev settings --share=<all|memory|none>`
+   (it manages one marked block and only replaces lines about the specs folder). Never rewrite
+   other `.gitignore` lines.
+4. **Risk scores.** For an existing project, run `spec-driven-dev risk` (or
    `npx -y @benjaminthomas/spec-driven-dev risk`) to write `{specs_dir}/context/risk.md`. It uses
    git only, no model, and adds `risk.md` to `.gitignore` because it's regenerated on every run. Skip it for a new project with no history. Mention the hotspot count in the
    report. Set `risk.enabled: off` only if the user doesn't want it.
-4. **Offer, don't do:** ask whether to add this one line to `CLAUDE.md` / `AGENTS.md` (whichever
+5. **Offer, don't do:** ask whether to add this one line to `CLAUDE.md` / `AGENTS.md` (whichever
    the project uses), so hosts reload the pointer after compaction and in every new session:
    `For spec work, read specs/CONTEXT.md first, then the "Resume here" block of any unfinished spec.`
    Add it only on a yes.
-5. Re-run `npx -y @benjaminthomas/spec-driven-dev doctor` if available. It checks the size limits
+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`,
@@ -140,6 +186,8 @@ 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
 and reviews will ignore risk scores until you turn it back on." People who prefer a menu can run

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

@@ -97,5 +97,19 @@ pipeline:
 context:
   project: existing             # existing (audited) | new (intent recorded) — set by setup
   graph: auto                   # auto = use graphify if installed or graphify-out/ exists | off
+  share: all                    # all = commit specs + project memory (recommended) | memory = commit only
+                                # 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