@benjaminthomas/spec-driven-dev 1.15.0 → 1.16.0

package/README.md

@@ -180,6 +180,16 @@ every team repo with its git URL, so setup offers them, `doctor` shows which are
 the clone command), and an investigation stops and says so when a ticket needs a repo that isn't on
 this machine.
 
+**Joining a team that's already set up.** The first person's setup moves the team's rules (tracker,
+base branch, branch and commit style, per-repo commands, models, GitRisk, sharing) into **`team.yml`
+in the specs repo**, which is committed with the specs. Each person's own `.spec-driven.yml` keeps only
+where their repos are on that machine and personal preferences. A colleague clones the specs repo and
+the code repos they work on, then says "run spec-setup": it finds the team's setup, offers **Join**, and
+asks only which of the team's repos they have. No audit, no convention questions, and nothing shared
+changes. From a terminal: `spec-driven-dev setup --join=../soreto-specs`. Changing a team rule is an
+edit to `team.yml` and a commit, and anything set in your own file overrides it for you only (`doctor`
+lists those overrides). An existing setup can be converted with `spec-driven-dev team init`.
+
 **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`,
@@ -660,6 +670,8 @@ spec-driven-dev doctor                            # check .spec-driven.yml again
 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, run-through and sharing from a menu
+spec-driven-dev team init                         # share the team's rules in the specs repo (team.yml)
+spec-driven-dev setup --join=../team-specs        # join a team that's already set up
 spec-driven-dev ci --notify                       # GitHub Actions: refresh GitRisk hotspots on every merge
 spec-driven-dev uninstall                         # remove the skills, plugin and cache (--all: settings too)
 spec-driven-dev risk                              # GitRisk: score files from git history → specs/context/risk.md
@@ -775,16 +787,16 @@ skips that step rather than failing.
 
 | Skill | Stage | SKILL.md lines | Words | Supporting files |
 |---|---|---:|---:|---:|
-| `spec-setup` | 0 · configure | 273 | 2,829 | 4 |
-| `spec-investigate` | 1 · understand | 387 | 3,367 | 1 |
-| `spec-create` | 2 · plan | 198 | 1,782 | 6 |
-| `spec-implement` | 3 · build | 327 | 2,753 | 3 |
-| `spec-verify` | 4 · prove | 163 | 1,557 | 1 |
-| `spec-review` | 5 · review | 137 | 1,294 | 1 |
-| `spec-checkpoint` | 6 · commit | 140 | 1,144 | 0 |
-| `spec-ship` | 7 · PR | 230 | 1,388 | 0 |
+| `spec-setup` | 0 · configure | 298 | 3,141 | 4 |
+| `spec-investigate` | 1 · understand | 387 | 3,391 | 1 |
+| `spec-create` | 2 · plan | 198 | 1,806 | 6 |
+| `spec-implement` | 3 · build | 327 | 2,777 | 3 |
+| `spec-verify` | 4 · prove | 163 | 1,581 | 1 |
+| `spec-review` | 5 · review | 137 | 1,318 | 1 |
+| `spec-checkpoint` | 6 · commit | 140 | 1,168 | 0 |
+| `spec-ship` | 7 · PR | 230 | 1,412 | 0 |
 | `generative-seo` | standalone | 255 | 2,209 | 7 |
-| **Total** | | **2,110** | **18,323** | **23** |
+| **Total** | | **2,135** | **18,803** | **23** |
 
 - **8** skills: **1** setup + **6** workflow stages + **1** standalone
 - **4** tools supported natively (Claude Code, Codex CLI, Cursor, Antigravity), plus an MCP fallback
@@ -837,7 +849,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.15.0 && git push origin v1.15.0`.
+  3. Tag the release and push the tag: `git tag v1.16.0 && git push origin v1.16.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

@@ -4,6 +4,8 @@
 //
 //   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 team init       move the team's shared rules into the specs repo (team.yml) so colleagues can join
+//   spec-driven-dev setup --join=<specs repo path or git URL>   join a team that's already set up (asks nothing else)
 //   spec-driven-dev ci              write GitHub Actions that refresh GitRisk hotspots on every merge (--notify also writes the per-repo trigger)
 //   spec-driven-dev uninstall       remove the skills (all tools), the Claude Code plugin and the download cache; --all also removes the settings file
 //   spec-driven-dev doctor          check .spec-driven.yml against the real repos (exit 1 on problems)
@@ -23,6 +25,7 @@ import prompts from "prompts";  // arrow-key menus that work in PowerShell, cmd,
 import { fileURLToPath } from "node:url";
 import { scoreRepo, riskMarkdown, normWeights, weightProblems, setConfigValue, riskSummaryBlock, withRiskSummary } from "./risk.mjs";
 import { SHARE_MODES, shareState, planShare, shareTitle } from "./share.mjs";
+import { mergeConfig, overrides, splitConfig, dumpYaml, TEAM_HEADER, PERSONAL_HEADER, teamFileFor, readIf } from "./team.mjs";
 
 const ROOT = path.dirname(path.dirname(fileURLToPath(import.meta.url)));
 const SKILLS_DIR = path.join(ROOT, "plugin", "skills");
@@ -41,7 +44,7 @@ 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", "setup", "ci"].includes(command) || (command === "uninstall" && flag("yes"));
+const YES = flag("yes") || flag("y") || !process.stdin.isTTY || ["doctor", "status", "context", "risk", "risk-eval", "setup", "ci", "team"].includes(command) || (command === "uninstall" && flag("yes"));
 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).
@@ -65,7 +68,7 @@ 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 = ["share", "specs-dir", "risk", "yes", "y", "layout", "repos", "packages", "tools", "workspace", "after-approval", "skills", "global", "no-setup", "project"];
+const ANSWER_FLAGS = ["join", "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.
@@ -589,6 +592,21 @@ function configApplies(f, dir) {
   return here === real(base) || c.repos.some((r) => { const p = real(path.resolve(base, expandHome(String(r.path || "")))); return here === p || here.startsWith(p + path.sep); });
 }
 
+// The effective config: the team's rules (team.yml in the specs repo) with the personal file on top.
+function readConfig(file) {
+  const personal = parseYaml(fs.readFileSync(file, "utf8"));
+  const tf = teamFileFor(file, personal.specs_dir);
+  const team = readIf(tf);
+  const c = team ? { ...mergeConfig(personal, parseYaml(team)), _teamFile: tf, _personal: personal, _team: parseYaml(team) } : personal;
+  // Repo roles are team knowledge kept in team-repos.yml; fill them in rather than copying them into each person's file.
+  const listed = parseYaml(readIf(path.join(path.dirname(tf), "team-repos.yml")) || "").repos;
+  if (Array.isArray(listed) && Array.isArray(c.repos)) {
+    const roles = new Map(listed.map((r) => [r.name, r.role]));
+    c.repos = c.repos.map((r) => (r.role ? r : { ...r, role: roles.get(path.basename(String(r.path || "").replace(/[\\/]+$/, ""))) || r.role }));
+  }
+  return c;
+}
+
 function findConfig(dir) {
   for (let d = dir; ; d = path.dirname(d)) {
     const f = path.join(d, ".spec-driven.yml");
@@ -608,8 +626,12 @@ function doctor() {
   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}`); }
+  try { c = readConfig(file); } catch (e) { throw new Error(`${file} could not be read: ${e.message}`); }
   const problems = [], notes = [];
+  if (c._teamFile) {
+    notes.push(`team rules come from ${c._teamFile}`);
+    for (const o of overrides(c._personal, c._team)) notes.push(`your ${o.key} (${JSON.stringify(o.yours)}) overrides the team's (${JSON.stringify(o.team)}) for you only`);
+  }
   if (!["single", "monorepo", "multi-repo"].includes(c.layout)) problems.push(`layout "${c.layout}" must be single, monorepo, or multi-repo`);
   if (c.tracker && !["jira", "github", "linear", "none"].includes(c.tracker.type)) problems.push(`tracker.type "${c.tracker.type}" must be jira, github, linear, or none`);
   if (c.git?.commit_style && !["conventional", "ticket", "freeform"].includes(c.git.commit_style)) problems.push(`git.commit_style "${c.git.commit_style}" must be conventional, ticket, or freeform`);
@@ -707,7 +729,7 @@ function checkContext(specs, specsName, repoRoots, problems, notes) {
 function context() {
   const file = findConfig(DIR);
   const root = file ? path.dirname(file) : DIR;
-  const specsName = (file && parseYaml(fs.readFileSync(file, "utf8")).specs_dir) || "specs";
+  const specsName = (file && readConfig(file).specs_dir) || "specs";
   const index = path.join(root, specsName, "CONTEXT.md");
   const areas = splitList(opt("areas"));
   if (!areas.length) {
@@ -791,7 +813,7 @@ function ignoreGenerated(file) {
 
 function loadConfig() {
   const file = findConfig(DIR);
-  return { file, root: file ? path.dirname(file) : gitTop(DIR), c: file ? parseYaml(fs.readFileSync(file, "utf8")) : {} };
+  return { file, root: file ? path.dirname(file) : gitTop(DIR), c: file ? readConfig(file) : {} };
 }
 
 function risk() {
@@ -857,7 +879,7 @@ async function riskEvalCmd() {
 
 // Plain-language switches, so anyone can change them without editing YAML.
 const SETTINGS = [
-  { block: "risk", key: "enabled", flag: "risk", name: "GitRisk", about: "extra care on files with a history of bugs",
+  { block: "risk", key: "enabled", flag: "risk", team: true, name: "GitRisk", about: "extra care on files with a history of bugs",
     get: (c) => c.risk?.enabled || "on", options: [
       { value: "on", title: "On", description: "investigations, plans and reviews look harder at historically risky files" },
       { value: "off", title: "Off", description: "the skills ignore risk completely" }] },
@@ -865,7 +887,7 @@ 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",
+  { block: "context", key: "share", flag: "share", team: true, 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" },
@@ -876,18 +898,22 @@ async function settings() {
   const file = findConfig(DIR);
   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 tf = readConfig(file)._teamFile;
   const label = (s, v) => s.options.find((o) => o.value === v)?.title || 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);
+    // Team rules go to the shared team.yml when there is one; the rest stays personal.
+    const target = s.team && tf ? tf : file;
+    const updated = setConfigValue(fs.readFileSync(target, "utf8"), s.block, s.key, v);
+    fs.writeFileSync(target, updated);
+    if (target === file) text = updated;
+    console.log(`✓ ${s.name}: ${label(s, v)}  (saved in ${target}${target === tf ? ": shared with the team, commit it" : ""})`);
+    if (s.after) await s.after(file, readConfig(file), v);
   };
   const given = SETTINGS.filter((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 c = readConfig(file);
     const pick = await askSelect("Settings: pick one to change", [
       ...SETTINGS.map((s) => ({ title: `${s.name}: ${label(s, s.get(c))}`, description: s.about, value: s })),
       { title: "Done", value: null }], null);
@@ -895,7 +921,7 @@ async function settings() {
     const v = await askSelect(`${pick.name}`, pick.options, pick.get(c));
     if (v !== pick.get(c)) await save(pick, v);
   }
-  const c = parseYaml(text);
+  const c = readConfig(file);
   if (c.risk?.enabled !== "off" && !fs.existsSync(path.join(path.dirname(file), c.specs_dir || "specs", "context", "risk.md"))) {
     if (given.length || !(await askConfirm("GitRisk is on but files haven't been scored yet. Score them now? (uses git only, takes seconds)", true)))
       console.log("  GitRisk is on, but nothing is scored yet. Run: spec-driven-dev risk");
@@ -942,6 +968,56 @@ async function uninstall() {
   console.log("Done. Reinstall any time with: npx @benjaminthomas/spec-driven-dev@latest");
 }
 
+// ---------- team: shared rules in the specs repo ----------
+function teamInit() {
+  const file = findConfig(DIR);
+  if (!file) throw new Error('No .spec-driven.yml found. Say "run spec-setup" in your AI tool first.');
+  const personal = parseYaml(fs.readFileSync(file, "utf8"));
+  const tf = teamFileFor(file, personal.specs_dir);
+  if (fs.existsSync(tf)) throw new Error(`${tf} already exists. To change a team rule, edit it and commit, or say "change our branch rules" in your AI tool.`);
+  if (!specsInGit(path.dirname(file), personal.specs_dir || "specs")) console.log(`• ${path.dirname(tf)} isn't in a git repo, so team.yml can't be shared yet. Keep specs in a repo (a dedicated specs repo is best).`);
+  const { team, personal: mine } = splitConfig(personal);
+  fs.mkdirSync(path.dirname(tf), { recursive: true });
+  fs.writeFileSync(tf, TEAM_HEADER + dumpYaml(team));
+  fs.copyFileSync(file, `${file}.bak`);
+  fs.writeFileSync(file, PERSONAL_HEADER(path.relative(path.dirname(file), tf)) + dumpYaml(mine));
+  step(1, "Team rules shared", ink.cyan);
+  console.log(`✓ Wrote ${tf} (tracker, git conventions, commands, models, GitRisk, sharing)
+✓ ${file} now keeps only your local settings (the old file is ${path.basename(file)}.bak)
+Next: commit team.yml in the specs repo. Colleagues who clone it run: spec-driven-dev setup --join=<path to the specs repo>
+or say "run spec-setup" in their AI tool, which finds it and offers to join.`);
+}
+
+function join() {
+  const target = opt("join");
+  let specsDir = /^(https?:|git@|ssh:)/.test(target) ? "" : path.resolve(DIR, expandHome(target));
+  const workspace = path.resolve(DIR, expandHome(opt("workspace") || (specsDir ? path.dirname(specsDir) : DIR)));
+  if (!specsDir) {
+    const name = path.basename(target).replace(/\.git$/, "");
+    specsDir = path.join(workspace, name);
+    if (!fs.existsSync(specsDir)) execFileSync("git", ["clone", "-q", target, specsDir], { stdio: "inherit" });
+  }
+  const team = parseYaml(readIf(path.join(specsDir, "team.yml")) || "");
+  const repoList = parseYaml(readIf(path.join(specsDir, "team-repos.yml")) || "").repos;
+  if (!Object.keys(team).length && !Array.isArray(repoList)) throw new Error(`${specsDir} has no team.yml or team-repos.yml, so there's no team to join. Ask whoever set it up to run: spec-driven-dev team init`);
+  const known = Array.isArray(repoList) ? repoList : (team.repos || []);
+  const wanted = opt("repos") ? splitList(opt("repos")) : known.map((r) => r.name);
+  const have = wanted.filter((n) => isRepo(path.join(workspace, n)));
+  const missing = known.filter((r) => wanted.includes(r.name) && !have.includes(r.name));
+  if (!have.length) throw new Error(`None of the team's repos (${known.map((r) => r.name).join(", ")}) are cloned in ${workspace}. Clone the ones you work on, then join again (or pass --workspace=<folder>).`);
+  const file = path.join(workspace, ".spec-driven.yml");
+  if (fs.existsSync(file) && !flag("force")) throw new Error(`${file} already exists. Add --force to replace it with the team's setup (it's backed up first).`);
+  if (fs.existsSync(file)) fs.copyFileSync(file, `${file}.bak`);
+  const mine = { version: 1, layout: have.length > 1 ? "multi-repo" : "single", repos: have.map((n) => ({ path: n })), specs_dir: path.relative(workspace, specsDir) || ".", pipeline: { after_approval: opt("after-approval") || "stop" } };
+  if (mine.layout === "single") { delete mine.repos; }
+  fs.writeFileSync(file, PERSONAL_HEADER(path.relative(workspace, path.join(specsDir, "team.yml"))) + dumpYaml(mine));
+  if (mine.layout === "multi-repo") register(real(file), have.map((n) => real(path.join(workspace, n))));
+  step(1, "Joined the team", ink.cyan);
+  console.log(`✓ Wrote ${file} with your repos: ${have.join(", ")}
+  Team rules (tracker, branches, commits, commands, GitRisk) come from ${path.join(specsDir, "team.yml")}${Object.keys(team).length ? "" : " (not created yet: team-repos.yml only)"}.`);
+  for (const r of missing) console.log(`  • ${r.name} isn't cloned here${r.url ? `: git clone ${r.url} ${path.join(workspace, r.name)}` : ""}`);
+}
+
 // ---------- CI: refresh GitRisk hotspots on merge ----------
 function ghSlug(url) { return (String(url || "").match(/github\.com[:/]([^/\s]+\/[^/\s]+?)(?:\.git)?\/?$/) || [])[1] || ""; }
 
@@ -1052,7 +1128,7 @@ Next:
 function status() {
   const file = findConfig(DIR);
   const root = file ? path.dirname(file) : DIR;
-  const specsName = (file && parseYaml(fs.readFileSync(file, "utf8")).specs_dir) || "specs";
+  const specsName = (file && readConfig(file).specs_dir) || "specs";
   const specs = path.join(root, specsName);
   const lines = [];
   for (const name of subdirs(specs)) {
@@ -1080,14 +1156,16 @@ try {
   else if (command === "settings") await settings();
   else if (command === "uninstall") await uninstall();
   else if (command === "ci") ci();
+  else if (command === "team") { if (args.includes("init")) teamInit(); else throw new Error("Use: spec-driven-dev team init"); }
   else if (command === "risk-eval") await riskEvalCmd();
   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" && opt("join")) join();
+  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, ci, uninstall, doctor, status, context, risk, or risk-eval`);
+  else throw new Error(`Unknown command "${command}" — use install (default), setup, settings, team, ci, uninstall, doctor, status, context, risk, or risk-eval`);
   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}`);

package/bin/team.mjs

@@ -0,0 +1,92 @@
+// The team's shared rules live in the specs repo as team.yml; each person's .spec-driven.yml keeps only
+// local things (where their repos are, which ones they have, personal preferences). The effective
+// config is team.yml with the personal file on top.
+import fs from "node:fs";
+import path from "node:path";
+
+// Shared: decided once by the team. Personal: differs per machine or per person.
+export const TEAM_KEYS = ["tracker", "git", "commands", "models", "effort", "risk", "context"];
+export const PERSONAL_KEYS = ["version", "layout", "repos", "specs_dir", "pipeline"];
+const REPO_TEAM_KEYS = ["role", "git", "commands"];
+
+const isObj = (v) => v && typeof v === "object" && !Array.isArray(v);
+export function deepMerge(a, b) {
+  if (!isObj(a) || !isObj(b)) return b === undefined ? a : b;
+  const out = { ...a };
+  for (const [k, v] of Object.entries(b)) out[k] = isObj(v) && isObj(a[k]) ? deepMerge(a[k], v) : v;
+  return out;
+}
+
+// personal: the parsed .spec-driven.yml; team: the parsed team.yml (or null). Repos match by folder name.
+export function mergeConfig(personal, team) {
+  if (!team) return personal;
+  const shared = Object.fromEntries(TEAM_KEYS.filter((k) => team[k] !== undefined).map((k) => [k, team[k]]));
+  const merged = deepMerge(shared, personal);
+  const byName = new Map((Array.isArray(team.repos) ? team.repos : []).map((r) => [r.name, r]));
+  if (Array.isArray(personal.repos)) {
+    merged.repos = personal.repos.map((r) => {
+      const t = byName.get(path.basename(String(r.path || "").replace(/[\\/]+$/, "")));
+      return t ? deepMerge(Object.fromEntries(REPO_TEAM_KEYS.filter((k) => t[k] !== undefined).map((k) => [k, t[k]])), r) : r;
+    });
+  }
+  return merged;
+}
+
+// Leaves that the personal file sets differently from the team, e.g. "git.base_branch".
+export function overrides(personal, team, prefix = "") {
+  const out = [];
+  for (const k of prefix ? Object.keys(personal || {}) : TEAM_KEYS) {
+    const p = personal?.[k], t = team?.[k];
+    if (p === undefined || t === undefined) continue;
+    if (isObj(p) && isObj(t)) out.push(...overrides(p, t, `${prefix}${k}.`));
+    else if (JSON.stringify(p) !== JSON.stringify(t)) out.push({ key: `${prefix}${k}`, yours: p, team: t });
+  }
+  return out;
+}
+
+// Small YAML writer for nested maps, lists of maps and scalars (JSON strings are valid YAML scalars).
+export function dumpYaml(obj, indent = "") {
+  const scalar = (v) => (typeof v === "string" ? (/^[\w./@~-]+$/.test(v) && !/^(on|off|yes|no|true|false|null|\d.*)$/i.test(v) ? v : JSON.stringify(v)) : String(v));
+  let out = "";
+  for (const [k, v] of Object.entries(obj)) {
+    if (v === undefined || v === null || (isObj(v) && !Object.keys(v).length)) continue;
+    if (Array.isArray(v)) {
+      out += `${indent}${k}:\n`;
+      for (const item of v) {
+        if (!isObj(item)) { out += `${indent}  - ${scalar(item)}\n`; continue; }
+        const body = dumpYaml(item, `${indent}    `).replace(/^\s+/, "");
+        out += `${indent}  - ${body}`;
+      }
+    } else if (isObj(v)) out += `${indent}${k}:\n${dumpYaml(v, `${indent}  `)}`;
+    else out += `${indent}${k}: ${scalar(v)}\n`;
+  }
+  return out;
+}
+
+// Split one config into the team's part and the personal part.
+export function splitConfig(c) {
+  const team = { version: 1 };
+  for (const k of TEAM_KEYS) if (c[k] !== undefined) team[k] = c[k];
+  const repos = (Array.isArray(c.repos) ? c.repos : []).map((r) => {
+    const t = { name: path.basename(String(r.path || "").replace(/[\\/]+$/, "")) };
+    for (const k of REPO_TEAM_KEYS) if (r[k] !== undefined && r[k] !== "") t[k] = r[k];
+    return t;
+  }).filter((t) => Object.keys(t).length > 1);
+  if (repos.length) team.repos = repos;
+  const personal = {};
+  for (const k of PERSONAL_KEYS) if (c[k] !== undefined) personal[k] = c[k];
+  if (Array.isArray(personal.repos)) personal.repos = personal.repos.map((r) => ({ path: r.path }));
+  return { team, personal };
+}
+
+export const TEAM_HEADER = `# team.yml — the team's shared rules for spec-driven-dev (tracker, git conventions, commands,
+# models, GitRisk, sharing). Committed in the specs repo, so everyone works the same way. Each
+# person's .spec-driven.yml only says where their repos are; a value set there overrides this file
+# for that person. Change a rule here and commit it (or say "change our branch rules" in your AI tool).
+`;
+export const PERSONAL_HEADER = (teamFile) => `# .spec-driven.yml — your local settings: where your repos are and personal preferences.
+# The team's shared rules are in ${teamFile}. Anything you set here overrides them for you only.
+`;
+
+export const teamFileFor = (configFile, specsDir) => path.resolve(path.dirname(configFile), specsDir || "specs", "team.yml");
+export const readIf = (f) => (fs.existsSync(f) ? fs.readFileSync(f, "utf8") : null);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@benjaminthomas/spec-driven-dev",
-  "version": "1.15.0",
+  "version": "1.16.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.15.0",
+  "version": "1.16.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-checkpoint/SKILL.md

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

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

@@ -23,7 +23,7 @@ Load `.spec-driven.yml`: walk up from the current directory to the home folder,
 found wins (a `multi-repo` config only applies inside the repos it lists). If none is found, check
 `~/.spec-driven/workspaces.json`, which maps each multi-repo config to its repo paths. Use the config
 whose repos contain the current directory, because a workspace's repos can live in unrelated folders. Its values beat anything
-you would detect or assume. This skill uses `layout`/`repos` and `specs_dir`.
+you would detect or assume. If `{specs_dir}/team.yml` exists, it holds the team's shared rules (tracker, git conventions, commands, models, GitRisk, sharing): read it first, and let `.spec-driven.yml` override it. This skill uses `layout`/`repos` and `specs_dir`.
 
 **Monorepo / multi-repo:** every task names its package or repo, and its file paths are relative to that. Keep each task inside one repo. Cross-repo work becomes separate tasks, with the contract (API shape, event, schema) written into both.
 

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

@@ -29,7 +29,7 @@ Load `.spec-driven.yml`: walk up from the current directory to the home folder,
 found wins (a `multi-repo` config only applies inside the repos it lists). If none is found, check
 `~/.spec-driven/workspaces.json`, which maps each multi-repo config to its repo paths. Use the config
 whose repos contain the current directory, because a workspace's repos can live in unrelated folders. Its values beat anything
-you would detect or assume. This skill uses `layout`/`repos`, `commands` (lint/typecheck/test per repo or package), and `git.commit_style`.
+you would detect or assume. If `{specs_dir}/team.yml` exists, it holds the team's shared rules (tracker, git conventions, commands, models, GitRisk, sharing): read it first, and let `.spec-driven.yml` override it. This skill uses `layout`/`repos`, `commands` (lint/typecheck/test per repo or package), and `git.commit_style`.
 
 **Multi-repo:** create worktrees in each repo a task touches, run each repo's own commands in review, and make the batch commit in every repo that changed, using the same subject line.
 

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

@@ -36,7 +36,7 @@ Load `.spec-driven.yml`: walk up from the current directory to the home folder,
 found wins (a `multi-repo` config only applies inside the repos it lists). If none is found, check
 `~/.spec-driven/workspaces.json`, which maps each multi-repo config to its repo paths. Use the config
 whose repos contain the current directory, because a workspace's repos can live in unrelated folders. Its values beat anything
-you would detect or assume. This skill uses `layout`/`repos` (where to look and what each repo does), `tracker`, `git.remote`, `git.base_branch`, `git.branch_name`, and `specs_dir`.
+you would detect or assume. If `{specs_dir}/team.yml` exists, it holds the team's shared rules (tracker, git conventions, commands, models, GitRisk, sharing): read it first, and let `.spec-driven.yml` override it. This skill uses `layout`/`repos` (where to look and what each repo does), `tracker`, `git.remote`, `git.base_branch`, `git.branch_name`, and `specs_dir`.
 
 **Monorepo:** name the package(s) involved. **Multi-repo:** search every listed repo whose role fits the ticket, and create the work branch, with the same name, only in the repos the investigation shows need changes.
 

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

@@ -28,7 +28,7 @@ investigate → create → approve → implement → verify → review → check
 Load `.spec-driven.yml`: walk up from the current directory to the home folder, and the first one
 found wins (a `multi-repo` config only applies inside the repos it lists). If none is found, check
 `~/.spec-driven/workspaces.json`, which maps each multi-repo config to its repo paths. Use the config
-whose repos contain the current directory. Its values beat anything you would detect or assume. This
+whose repos contain the current directory. Its values beat anything you would detect or assume. If `{specs_dir}/team.yml` exists, it holds the team's shared rules (tracker, git conventions, commands, models, GitRisk, sharing): read it first, and let `.spec-driven.yml` override it. This
 skill uses `git` (base branch, PR target), `commands` (lint/typecheck/test), `models`/`effort`,
 `layout`/`repos`, and `specs_dir`.
 

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

@@ -32,11 +32,30 @@ first one found wins.
 |---|---|---|
 | `single` | the repo root | Commit it — the whole team gets the same rules |
 | `monorepo` | the repo root | Commit it |
-| `multi-repo` | the shared parent folder of the repos (usually not itself a git repo) | Personal by default; offer to also commit a copy into the repo the team treats as "home" |
+| `multi-repo` | the shared parent folder of the repos (usually not itself a git repo) | The team's rules go in `team.yml` in the specs repo (shared); this file keeps only local paths |
 
 A multi-repo config only applies inside the repos it lists. If the current repo sits under that
 folder but isn't listed, treat it as having no config (ask whether to add it).
 
+## Step 0 — Join a team that's already set up
+
+Before detecting anything, look for a team setup someone already shared: a folder next to this repo
+(or in the workspace folder) containing `team.yml` or `team-repos.yml`, or a specs repo the user
+names (a path, or a git URL to clone). If you find one, say so with what it is, and ask with a menu:
+
+> Found your team's setup in ~/Projects/soreto-specs: 5 repos, Jira STP, branches from staging.
+> `Join it (Recommended)`: use the team's rules; I'll only ask which of its repos you have here.
+> `Set up separately`: ignore it and answer everything yourself.
+
+**Joining:** ask only which of the team's repos you work on (tick boxes, from `team-repos.yml`;
+mark the ones not cloned here and offer their `git clone` command, cloning only on a yes), then run
+`spec-driven-dev setup --join=<specs repo> --repos=<chosen>` (or `npx -y @benjaminthomas/spec-driven-dev …`).
+Don't audit, don't ask about conventions, and never change the team's files: `CONTEXT.md`,
+`team.yml` and `team-repos.yml` are shared. Then run `doctor`, and finish with "You've joined. Say
+*investigate STP-123* to start." Only `team-repos.yml` and no `team.yml` (an older setup): join
+anyway, and tell the user the team's rules aren't shared yet, so the person who set it up should
+run `spec-driven-dev team init`.
+
 ## Step 1 — Detect before asking
 
 Read, don't guess. Collect a draft of every field in `references/config-template.yml`:
@@ -204,6 +223,11 @@ for the rest.
    under `repos:` where they differ from the top level.
 2. If it's inside a repo, tell the user it's meant to be committed (so teammates get the same
    rules) — don't commit it yourself.
+   **Multi-repo with specs in a repo:** run `spec-driven-dev team init` right after writing the
+   file. It moves the team's rules (tracker, git conventions, commands, models, GitRisk, sharing)
+   into `{specs_dir}/team.yml`, which is committed with the specs, and leaves only local paths in
+   `.spec-driven.yml`. Tell the user to commit `team.yml`, and that colleagues then just say
+   "run spec-setup" and choose *Join*.
 3. If `npx` is available, run `npx -y @benjaminthomas/spec-driven-dev doctor` from the config's folder. It checks
    that every branch, folder, and `npm run` script in the file really exists. Fix anything it
    reports before finishing.
@@ -249,6 +273,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` |
+| "change our branch rules", "use main for PRs" (when `team.yml` exists) | edit `team.yml`, since it's a team rule, and remind them to commit it; only change `.spec-driven.yml` if they say it's just for them |
 | "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 |
 

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

@@ -1,4 +1,6 @@
 # .spec-driven.yml — project rules for the spec-driven-dev skills.
+# Multi-repo teams: the shared parts (tracker, git, commands, models, effort, risk, context) go in
+# {specs_dir}/team.yml (spec-driven-dev team init), so colleagues can join; this file then keeps local paths.
 # Written by spec-setup from what it detected + what you confirmed. Edit freely, or re-run
 # spec-setup to update it. Every spec-* skill reads this before doing anything else.
 version: 1

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

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

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

@@ -29,7 +29,7 @@ Load `.spec-driven.yml`: walk up from the current directory to the home folder,
 found wins (a `multi-repo` config only applies inside the repos it lists). If none is found, check
 `~/.spec-driven/workspaces.json`, which maps each multi-repo config to its repo paths. Use the config
 whose repos contain the current directory, because a workspace's repos can live in unrelated folders. Its values beat anything
-you would detect or assume. This skill uses `commands.dev`, `commands.dev_url`, and `layout`/`repos`.
+you would detect or assume. If `{specs_dir}/team.yml` exists, it holds the team's shared rules (tracker, git conventions, commands, models, GitRisk, sharing): read it first, and let `.spec-driven.yml` override it. This skill uses `commands.dev`, `commands.dev_url`, and `layout`/`repos`.
 
 **Monorepo / multi-repo:** start every app or service the criteria need (e.g. the API and the frontend), each with its own `dev` command.