@benjaminthomas/spec-driven-dev 1.11.1 → 1.12.0

package/README.md

@@ -63,9 +63,11 @@ 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. It asks its
-questions in your terminal, so run it in a real terminal, not through another tool. If there's no
-terminal to answer in, it says so and uses the detected values.
+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
@@ -209,7 +211,7 @@ example, from inside `/Projects/frontend`:
 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`.
+`--project=new|existing`, `--share=all|memory|none`, `--specs-dir=<path>`, `--tools=cursor,codex`, `--global`, `--yes` (accept everything detected), and `--version`.
 
 To change the rules later, edit the file or run setup again, then run `spec-driven-dev doctor`
 to confirm the file still matches your repos. Setup never overwrites the file without
@@ -247,6 +249,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
@@ -566,6 +587,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.
 
@@ -579,8 +605,9 @@ STP-123" or "ship it" picks the right skill.
 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 stops, changes nothing, and tells you to run
-it in a terminal window or pass flags such as `--layout=multi-repo --repos=…`.
+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=…`.
 
 **Setup didn't ask me about repos.**
 It only asks about repos for a multi-repo or monorepo layout. If it detected `single`, type
@@ -644,7 +671,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)
@@ -741,7 +768,7 @@ skips that step rather than failing.
 
 | Skill | Stage | SKILL.md lines | Words | Supporting files |
 |---|---|---:|---:|---:|
-| `spec-setup` | 0 · configure | 162 | 1,545 | 3 |
+| `spec-setup` | 0 · configure | 179 | 1,747 | 3 |
 | `spec-investigate` | 1 · understand | 373 | 3,211 | 1 |
 | `spec-create` | 2 · plan | 198 | 1,782 | 6 |
 | `spec-implement` | 3 · build | 327 | 2,753 | 3 |
@@ -750,7 +777,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,002** | **17,085** | **22** |
 
 - **8** skills: **1** setup + **6** workflow stages + **1** standalone
 - **4** tools supported natively (Claude Code, Codex CLI, Cursor, Antigravity), plus an MCP fallback
@@ -774,6 +801,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
@@ -802,7 +830,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.1 && git push origin v1.11.1`.
+  3. Tag the release and push the tag: `git tag v1.12.0 && git push origin v1.12.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

@@ -8,11 +8,11 @@
 //   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");
@@ -47,14 +48,20 @@ if (flag("version") || flag("v")) {
 }
 // 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"];
-if (["install", "setup", "settings"].includes(command) && !process.stdin.isTTY && !args.some((a) => ANSWER_FLAGS.some((f) => a === `--${f}` || a.startsWith(`--${f}=`)))) {
+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) {
   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 === "install" ? "" : command}
+        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)`);
@@ -137,7 +144,8 @@ async function install() {
     }
     console.log(`✓ ${skills.length} skills → ${dest}`);
   }
-  if (!dests.length) console.log("• No tools selected — nothing installed.");
+  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;
 }
 
 // ---------- discovery ----------
@@ -245,7 +253,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`;
@@ -453,7 +461,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" },
@@ -466,7 +475,7 @@ 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) => {
@@ -478,6 +487,7 @@ async function setup() {
   fs.writeFileSync(file, toYaml(config));
   if (layout === "multi-repo") register(real(file), repos.map((r) => real(path.resolve(root, r))));
   console.log(`✓ Wrote ${file}`);
+  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.`
@@ -591,8 +601,16 @@ 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);
+  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)`);
@@ -644,6 +662,58 @@ 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; }
+  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 (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) {
@@ -725,6 +795,11 @@ 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() {
@@ -732,14 +807,15 @@ async function settings() {
   if (!file) throw new Error(`No .spec-driven.yml in ${DIR} or above. Run: spec-driven-dev setup`);
   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", [
@@ -747,7 +823,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"))) {
@@ -788,12 +864,20 @@ try {
   else if (command === "risk") risk();
   else if (command === "settings") await settings();
   else if (command === "risk-eval") await riskEvalCmd();
-  else if (command === "install") {
+  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 throw new Error(`Unknown command "${command}" — use install (default), setup, settings, doctor, status, context, risk, or risk-eval`);
-  if (["install", "setup"].includes(command)) console.log('\nNext: in your AI tool, say "investigate <ticket>" or "create a spec".');
+  if (["install", "setup"].includes(command) && !HANDOFF) 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,46 @@
+// 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?
+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`);
+  return features && memory ? "all" : memory ? "memory" : features ? "custom" : "none";
+}
+
+export function blockFor(specs, mode) {
+  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.1",
+  "version": "1.12.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.1",
+  "version": "1.12.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-setup/SKILL.md

@@ -82,6 +82,18 @@ 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:
+   `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`.
 
 ## Step 2 — Confirm in one round
 
@@ -118,15 +130,19 @@ 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.
 
 ## Quick switches (plain words, no YAML)
@@ -140,6 +156,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` |
+| "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,8 @@ 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)