@benjaminthomas/spec-driven-dev 1.14.2 → 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`,
@@ -294,6 +304,20 @@ Off means every skill ignores risk completely.
 hypothesis: change them under `risk.weights` in `.spec-driven.yml` once you've backtested them
 against your own past bugs.
 
+**Keep the hotspots current on every merge (GitHub Actions).** With a dedicated specs repo on GitHub:
+
+```bash
+spec-driven-dev ci --notify
+```
+
+This writes `.github/workflows/gitrisk.yml` into the specs repo, plus, with `--notify`, a small
+`gitrisk-notify.yml` into each code repo on your machine. When something lands on a repo's base
+branch, it pings the specs repo, which checks out every repo in `team-repos.yml` with full history,
+runs `risk`, and commits the **Risk hotspots** in `CONTEXT.md` only when they changed. A date-only
+change isn't committed. It also runs nightly, and on demand from the Actions tab. You add one secret,
+`GITRISK_TOKEN` (read access to the code repos, write access to the specs repo), and commit the
+workflow files yourself. The command prints the exact steps.
+
 **Does it change what the agent does?** `spec-driven-dev risk-eval --tickets=tickets.md` runs each
 ticket twice, in fresh clones with risk on and off, through investigate and create on the same
 model. It then compares what the agent did:
@@ -646,6 +670,9 @@ 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
 spec-driven-dev risk-eval --tickets=tickets.md    # compare agent behaviour with the risk signal on vs off
@@ -760,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
@@ -822,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.14.2 && git push origin v1.14.2`.
+  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,9 @@
 //
 //   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)
 //   spec-driven-dev status          list specs with unfinished work and each one's "Resume here" next step
@@ -22,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");
@@ -40,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"].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).
@@ -64,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.
@@ -588,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");
@@ -607,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`);
@@ -706,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) {
@@ -790,11 +813,14 @@ 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() {
-  const { root, c } = loadConfig();
+  const loaded = loadConfig();
+  const { root } = loaded;
+  // CI has no personal .spec-driven.yml: --repos and --specs-dir describe the checkout instead.
+  const c = opt("repos") ? { ...loaded.c, layout: "multi-repo", repos: splitList(opt("repos")).map((p) => ({ path: p })), specs_dir: opt("specs-dir") || loaded.c.specs_dir } : loaded.c;
   const bad = weightProblems(c.risk?.weights);
   if (bad.length) throw new Error(bad.join("; "));
   const weights = normWeights(c.risk?.weights), since = opt("since") || c.risk?.since || "2 years ago";
@@ -853,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" }] },
@@ -861,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" },
@@ -872,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);
@@ -891,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");
@@ -938,11 +968,167 @@ 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] || ""; }
+
+function ciFiles({ specsSlug, repos, version }) {
+  const checkouts = repos.map((r) => `      - uses: actions/checkout@v4
+        with:
+          repository: ${r.slug}
+          path: ${r.name}
+          fetch-depth: 0          # full history: GitRisk reads git log
+          token: \${{ secrets.GITRISK_TOKEN }}`).join("\n");
+  const specs = `# Refreshes the "Risk hotspots" block in CONTEXT.md from every team repo's git history.
+# Written by \`spec-driven-dev ci\`. Re-run that command after adding a repo to team-repos.yml.
+# Needs a repository secret GITRISK_TOKEN: a token that can read the code repos and write to this repo.
+name: GitRisk
+on:
+  repository_dispatch:
+    types: [code-merged]      # sent by each code repo's gitrisk-notify workflow
+  schedule:
+    - cron: "0 3 * * *"       # nightly safety net
+  workflow_dispatch:
+permissions:
+  contents: write
+concurrency:
+  group: gitrisk
+  cancel-in-progress: true
+jobs:
+  score:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          path: specs
+          token: \${{ secrets.GITRISK_TOKEN }}
+${checkouts}
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+      - name: Score files from git history
+        run: npx -y @benjaminthomas/spec-driven-dev@${version} risk --dir=. --repos=${repos.map((r) => r.name).join(",")} --specs-dir=specs
+      - name: Commit when the hotspots changed (not for a date-only change)
+        working-directory: specs
+        run: |
+          git add CONTEXT.md .gitignore
+          if git diff --cached --quiet -I '^Updated [0-9-]+$'; then echo "Hotspots unchanged"; exit 0; fi
+          git -c user.name="gitrisk[bot]" -c user.email="gitrisk@users.noreply.github.com" commit -m "chore: refresh GitRisk hotspots"
+          git push
+`;
+  const notify = (branch) => `# Tells the specs repo to refresh GitRisk hotspots when work lands here.
+# Written by \`spec-driven-dev ci --notify\`. Needs the same GITRISK_TOKEN secret in this repo.
+name: GitRisk notify
+on:
+  push:
+    branches: [${branch}]
+jobs:
+  notify:
+    runs-on: ubuntu-latest
+    steps:
+      - run: gh api repos/${specsSlug}/dispatches -f event_type=code-merged
+        env:
+          GH_TOKEN: \${{ secrets.GITRISK_TOKEN }}
+`;
+  return { specs, notify };
+}
+
+function ci() {
+  const { root, c } = loadConfig();
+  if (!c.layout) throw new Error('No .spec-driven.yml found. Say "run spec-setup" in your AI tool first.');
+  const specs = path.resolve(root, c.specs_dir || "specs");
+  const g = specsInGit(root, c.specs_dir || "specs");
+  if (!g) throw new Error(`${specs} isn't inside a git repo, so there's nowhere to run CI. Keep specs in a repo (a dedicated specs repo is best).`);
+  const specsSlug = ghSlug(run("git", ["remote", "get-url", "origin"], g.top));
+  if (!specsSlug) throw new Error(`The specs repo at ${g.top} has no GitHub remote yet. Push it first, e.g.: gh repo create <org>/<name> --private --source ${g.top} --push`);
+  const team = parseYaml(fs.existsSync(path.join(specs, "team-repos.yml")) ? fs.readFileSync(path.join(specs, "team-repos.yml"), "utf8") : "").repos;
+  const list = (Array.isArray(team) && team.length ? team : (c.repos || []).map((r) => ({ name: path.basename(String(r.path)), url: run("git", ["remote", "get-url", "origin"], path.resolve(root, expandHome(String(r.path)))) })))
+    .map((r) => ({ name: r.name, slug: ghSlug(r.url) })).filter((r) => r.name && r.name !== path.basename(g.top));
+  const missing = list.filter((r) => !r.slug);
+  if (missing.length) throw new Error(`No GitHub URL for ${missing.map((r) => r.name).join(", ")}. Add a "url:" for each in team-repos.yml.`);
+  if (!list.length) throw new Error("No code repos to score. List them in team-repos.yml or your workspace.");
+  const version = JSON.parse(fs.readFileSync(path.join(ROOT, "package.json"), "utf8")).version;
+  const { specs: specsYml, notify } = ciFiles({ specsSlug, repos: list, version });
+  if (g.rel) throw new Error(`Specs live inside ${g.top}, a code repo. The CI step needs a dedicated specs repo, so its commits don't land in a code repo. Move specs with spec-setup, or use: spec-driven-dev risk after merges.`);
+  const wf = path.join(g.top, ".github", "workflows", "gitrisk.yml");
+  fs.mkdirSync(path.dirname(wf), { recursive: true });
+  fs.writeFileSync(wf, specsYml);
+  step(1, "GitRisk on every merge", ink.cyan);
+  console.log(`✓ Wrote ${wf}\n  Scores ${list.map((r) => r.name).join(", ")} nightly, on demand, and whenever a code repo pings it.`);
+  const wrote = [];
+  for (const r of (c.repos || [])) {
+    const dir = path.resolve(root, expandHome(String(r.path)));
+    if (!flag("notify") || !isRepo(dir) || real(dir) === real(g.top)) continue;
+    const branch = r.git?.base_branch && r.git.base_branch !== "default" ? r.git.base_branch : c.git?.base_branch && c.git.base_branch !== "default" ? c.git.base_branch : run("git", ["symbolic-ref", "--short", "refs/remotes/origin/HEAD"], dir).replace(/^origin\//, "") || "main";
+    const f = path.join(dir, ".github", "workflows", "gitrisk-notify.yml");
+    fs.mkdirSync(path.dirname(f), { recursive: true });
+    fs.writeFileSync(f, notify(branch));
+    wrote.push(`${path.basename(dir)} (on ${branch})`);
+  }
+  if (wrote.length) console.log(`✓ Wrote .github/workflows/gitrisk-notify.yml in: ${wrote.join(", ")}`);
+  else console.log("• Add --notify to also write the small trigger workflow into each code repo on this machine, so a merge refreshes the hotspots straight away.");
+  console.log(`
+Next:
+  1. Create a GitHub token (fine-grained): read access to ${list.map((r) => r.name).join(", ")}; contents: read & write on ${specsSlug}.
+  2. Add it as a secret named GITRISK_TOKEN in ${specsSlug}${wrote.length ? " and in each code repo" : ""}:  gh secret set GITRISK_TOKEN -R ${specsSlug}
+  3. Commit and push the workflow file(s). Nothing was committed for you.
+  4. Try it: gh workflow run GitRisk -R ${specsSlug}`);
+}
+
 // Silent unless something is unfinished, so it's cheap to run at the start of a session.
 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)) {
@@ -969,14 +1155,17 @@ try {
   else if (command === "risk") risk();
   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, 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/risk.mjs

@@ -174,7 +174,7 @@ const RB = "<!-- risk:start (written by spec-driven-dev risk; don't edit) -->",
 export function riskSummaryBlock(rows, date) {
   const top = rows.filter((r) => r.tier === "critical" || r.tier === "high").slice(0, 5);
   const counts = ["critical", "high", "medium"].map((t) => `${rows.filter((r) => r.tier === t).length} ${t}`).join(" · ");
-  return [RB, "## Risk hotspots", `GitRisk on ${date}: ${counts}. Full table: context/risk.md (regenerate: spec-driven-dev risk).`,
+  return [RB, "## Risk hotspots", `Updated ${date}`, `${counts}. Full table: context/risk.md (regenerate: spec-driven-dev risk).`,
     ...(top.length ? top.map((r) => `- \`${r.file}\` ${r.score} ${r.tier}`) : ["- No high or critical files."]), RE].join("\n");
 }
 export function withRiskSummary(text, block) {

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.14.2",
+  "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.14.2",
+  "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.