@benjaminthomas/spec-driven-dev 1.14.0 → 1.14.2

package/README.md

@@ -150,7 +150,7 @@ before it writes the file. If any skill finds no config, it runs this setup firs
 | What it asks | Detected from | Example answer |
 |---|---|---|
 | How the project is organised | git repos and workspace files (`pnpm-workspace.yaml`, `turbo.json`, `nx.json`, `go.work`, …). A Shopify app's `extensions/` count as one app | `single`, `monorepo`, or `multi-repo` |
-| *multi-repo:* which repos you work on | git repos nearby, grouped by GitHub owner, plus the team's `team-repos.yml` | `soreto-shopify, reverb-backend` |
+| *multi-repo:* which repos you work on | each repo's purpose, evidence of how it connects to this one (env vars, API calls, docs), your recent commits, and `team-repos.yml`; it recommends a selection with reasons | `soreto-shopify, reverb-backend` |
 | *multi-repo:* where specs live | (you choose) | a dedicated specs repo, a code repo, or this machine only |
 | Issue tracker | ticket keys in branch names and commits | Jira, key `STP` |
 | Base branch / PR target | default branch, `staging`/`develop`, recent PR targets | `staging` |
@@ -760,7 +760,7 @@ skips that step rather than failing.
 
 | Skill | Stage | SKILL.md lines | Words | Supporting files |
 |---|---|---:|---:|---:|
-| `spec-setup` | 0 · configure | 210 | 2,201 | 3 |
+| `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 |
@@ -769,7 +769,7 @@ skips that step rather than failing.
 | `spec-checkpoint` | 6 · commit | 140 | 1,144 | 0 |
 | `spec-ship` | 7 · PR | 230 | 1,388 | 0 |
 | `generative-seo` | standalone | 255 | 2,209 | 7 |
-| **Total** | | **2,047** | **17,695** | **22** |
+| **Total** | | **2,110** | **18,323** | **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 +822,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.0 && git push origin v1.14.0`.
+  3. Tag the release and push the tag: `git tag v1.14.2 && git push origin v1.14.2`.
   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

@@ -20,7 +20,7 @@ import path from "node:path";
 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 { scoreRepo, riskMarkdown, normWeights, weightProblems, setConfigValue, riskSummaryBlock, withRiskSummary } from "./risk.mjs";
 import { SHARE_MODES, shareState, planShare, shareTitle } from "./share.mjs";
 
 const ROOT = path.dirname(path.dirname(fileURLToPath(import.meta.url)));
@@ -818,6 +818,11 @@ function risk() {
   const out = path.join(specs, "context", "risk.md");
   fs.writeFileSync(out, riskMarkdown({ rows, repos: scored, weights, since, top: Number(opt("top")) || 40 }));
   ignoreGenerated(out);
+  const ctx = path.join(specs, "CONTEXT.md");
+  if (fs.existsSync(ctx)) {
+    fs.writeFileSync(ctx, withRiskSummary(fs.readFileSync(ctx, "utf8"), riskSummaryBlock(rows, new Date().toISOString().slice(0, 10))));
+    console.log(`  Updated the "Risk hotspots" summary in ${path.relative(DIR, ctx) || ctx}, which is shared with the team.`);
+  }
   const count = (t) => rows.filter((r) => r.tier === t).length;
   console.log(`✓ Scored ${rows.length} files from ${scored.reduce((t, s) => t + s.commits, 0)} commits → ${path.relative(DIR, out) || out}`);
   console.log(`  ${count("critical")} critical · ${count("high")} high · ${count("medium")} medium · ${count("new")} new. Top 5:`);

package/bin/risk.mjs

@@ -167,3 +167,18 @@ export function setConfigValue(text, blockName, key, value) {
   const body = line.test(block[0]) ? block[0].replace(line, `$1${value}`) : block[0].replace(new RegExp(`^${blockName}:.*\\n`), `$&  ${key}: ${value}\n`);
   return text.replace(block[0], body);
 }
+
+// A short, committed summary inside CONTEXT.md, so the hotspots are part of the shared project memory
+// (risk.md itself is gitignored: it's regenerated on every run). Replaced in place between markers.
+const RB = "<!-- risk:start (written by spec-driven-dev risk; don't edit) -->", RE = "<!-- risk:end -->";
+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).`,
+    ...(top.length ? top.map((r) => `- \`${r.file}\` ${r.score} ${r.tier}`) : ["- No high or critical files."]), RE].join("\n");
+}
+export function withRiskSummary(text, block) {
+  const i = text.indexOf(RB), j = text.indexOf(RE);
+  if (i >= 0 && j > i) return text.slice(0, i) + block + text.slice(j + RE.length);
+  return `${text.replace(/\n*$/, "")}\n\n${block}\n`;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@benjaminthomas/spec-driven-dev",
-  "version": "1.14.0",
+  "version": "1.14.2",
   "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.0",
+  "version": "1.14.2",
   "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

@@ -51,10 +51,13 @@ Read, don't guess. Collect a draft of every field in `references/config-template
      multi-repo workspace). The same goes for any repo whose "packages" are plug-ins of one app.
    - **Ask when one repo works with others.** Even inside a single repo, ask once: "Does this repo
      change together with other repos (for example a backend)?" A yes means `multi-repo`.
-   - Not inside a git repo, but sibling folders are git repos → candidate `multi-repo`. Group them
-     by remote owner (`git remote get-url origin`) and show the groups — the user picks which repos
-     belong together. Never assume every folder in the parent belongs. Always also ask whether
-     repos in **other folders** belong (e.g. `~/clients/billing`). Check each path is a git repo,
+   - Not inside a git repo, but sibling folders are git repos → candidate `multi-repo`.
+   - **Choosing the repos is a required question for `multi-repo`, never a detection.** Someone new
+     doesn't know what `soreto-melissa` is, so never show bare folder names. Follow
+     `references/repo-picker.md`: say what each candidate repo is, show evidence of how it connects
+     to the current repo, note whether the user commits to it, and recommend a selection with a
+     reason per repo. Ask once, and don't write the config until they've answered. Always also
+     offer repos in **other folders** (e.g. `~/clients/billing`). Check each path is a git repo,
      and store paths inside the workspace as relative and paths outside it as absolute.
    - The repos of one workspace can live in unrelated places (`/Projects/frontend`,
      `~/Work/backend`, `/srv/database`). Put the config in their shared parent folder, or in
@@ -120,16 +123,76 @@ Read, don't guess. Collect a draft of every field in `references/config-template
    Store the answer as `context.share`. A dedicated specs repo is shared by nature: set
    `context.share: all`.
 
+## How to ask
+
+Two kinds of question, asked two different ways:
+
+1. **Choices** (layout and repos, sharing, specs location, after-approval mode, a guessed command):
+   use the host's **interactive question tool** when it has one (Claude Code: `AskUserQuestion`).
+   - Up to 4 questions per call; each needs **2 to 4 options** (a one-option question is rejected
+     and the user never sees it; "Other" is added automatically and doesn't count).
+   - Put the recommended option first and end its label with "(Recommended)". Put the evidence in
+     each option's description (e.g. "called via BACKBONE_URL, app/services/x.ts:105").
+   - **Layout and repos are two separate calls, always** (Step 2). Never ask layout together with
+     other questions.
+   - **Repos are never offered as preset bundles** ("+backend +melissa", "all four"); bundles don't
+     scale and stop people mixing their own. Ask in two calls:
+     1. **Layout first**, on its own: "Single repo" vs "Several repos that change together"
+        (vs "Monorepo" when it fits), recommendation first with the evidence.
+     2. **Only if several:** a `multiSelect` question with **one option per repo**: label = repo
+        name (the recommended ones first, marked "(Recommended)"), description = what it is plus the
+        link evidence. At most 4 options. The menu can't show the rest, so the **question text** must
+        end by naming the other repos found ("Also found: a, b, c (no code link).") and saying how to
+        add them: "To add any of these, or a repo from another folder, choose *Type something* and
+        enter names or paths, e.g. `a, ~/Work/billing`." Put the remaining choices (specs location,
+        sharing, pipeline) in this same call.
+   - If the tool isn't available (or a call fails), ask the same choices as a short numbered list
+     in text instead. Never drop a question.
+2. **Open questions** (what the product does, fragile spots, direction, unwritten rules): plain text
+   in **one chat message**, asked **after** the choices are answered. Never turn these into a menu.
+
 ## Step 2 — Confirm in one round
 
 Show the draft as a short table grouped by layout, tracker, git, commands, and specs location.
-Mark each value **detected** (with where it came from) or **guess**. Then ask only about guesses
-and conflicts — in one message, not a drip of questions. Typical ones:
+Mark each value **detected** (with where it came from) or **guess**. Then ask in exactly this order
+(interactive question tool when there is one; see How to ask):
+
+**Call 1: layout, alone. Nothing else in this call.** Use these option labels exactly; no repo names
+in them:
+- `Single repo`: "Only <this repo>." (+ the evidence for or against)
+- `Several repos`: "<this repo> changes together with other repos. You'll pick which next."
+- `Monorepo`: only when workspace markers were found.
+
+Recommend one (first, with "(Recommended)") and put the evidence in the question text.
+
+**Call 2: repos (only if the answer was `Several repos`).** The repo tick-box list (`multiSelect`, one
+option per repo, see `references/repo-picker.md`) and where specs live (a dedicated specs repo, inside
+one code repo, or this machine only).
+
+**Call 3: git conventions, always, even when detected.** These decide how every branch and commit is
+made, and detection can be wrong, so confirm them. Four questions, the detected value first with its
+evidence in the description, then the common alternatives:
+- **Base branch** (work starts from): e.g. `staging (Recommended)`: "16 of the last 20 merged PRs";
+  `main`; `develop`. In multi-repo, say which repos differ ("staging; soreto-cms has none, uses main").
+- **PR target**: usually the same as the base branch.
+- **Branch names**: e.g. `STP-123 (Recommended)` (bare ticket id, seen in recent branches);
+  `feat/STP-123-short-name`; `feat/short-name`.
+- **Commit style**: e.g. `STP-123: message (Recommended)`; `feat: message`; free text. In multi-repo,
+  name any repo that uses a different style.
+
+**Call 4: tracker, team and pipeline.** The tracker, confirmed like the git conventions (e.g.
+`Jira, key STP (Recommended)`: "STP-123 in recent branches", `GitHub Issues`, `Linear`, `None`), then
+sharing (if specs are inside a repo), after approval (stop / run straight through), and any command
+that's a guess (e.g. typecheck). At most 4; a guessed command that doesn't fit goes in the summary as
+"I'll use X, say if that's wrong".
+
+Then the open questions, as plain text (see How to ask).
+
+Typical things to flag in the descriptions:
 
-- "Your repos default to `master`, but recent PRs targeted `staging`. Cut work from `staging`?"
-- "Recent branches are bare ticket IDs (`STP-282`). Keep that, or use `fix/STP-282-short-slug`?"
-- "These 6 repos share the `acme` GitHub org. Do they form one workspace for the pipeline?"
-- "Where should specs live — this folder's `specs/`, or inside one repo so they go through PRs?"
+- "Your repos default to `master`, but recent PRs targeted `staging`."
+- "Recent branches are bare ticket IDs (`STP-282`)."
+- "These 6 repos share the `acme` GitHub org."
 
 If the user says "just use the defaults", accept the detected values and the template defaults
 for the rest.

package/plugin/skills/spec-setup/references/audit.md

@@ -41,7 +41,10 @@ never ask again.
 ## 3. Discovery questions (one round)
 
 Show the draft map first, with each line marked **detected** (with its source) or **guess**. Then
-ask only what the code can't answer, in one message:
+ask only what the code can't answer, as **plain text in one message**, after the setup choices have
+been answered. These are open questions, so
+never put them in a menu or multiple-choice tool (a menu needs two or more real options, and these
+have none). The user replies in their own words, or "skip":
 
 - What does the product do, and who uses it?
 - Which areas are legacy, frozen, or off-limits?

package/plugin/skills/spec-setup/references/context-template.md

@@ -54,8 +54,18 @@ Project: existing · audited at a1b2c3d (2026-11-10) · graph: none
 
 ## Specs
 - {stp-123: retry failed webhooks, touched billing (2026-11-10)}
+
+<!-- risk:start (written by spec-driven-dev risk; don't edit) -->
+## Risk hotspots
+GitRisk on 2026-11-10: 0 critical · 8 high · 30 medium. Full table: context/risk.md (regenerate: spec-driven-dev risk).
+- `app/services/billing.ts` 61.7 high
+<!-- risk:end -->
 ```
 
+The **Risk hotspots** block is written by `spec-driven-dev risk` (setup, every batch, checkpoint) and
+replaced in place, so don't edit it. It's the shared part of GitRisk: `context/risk.md` itself is
+gitignored because it's regenerated on every run.
+
 ## context/<area>.md
 
 ```markdown

package/plugin/skills/spec-setup/references/repo-picker.md

@@ -0,0 +1,79 @@
+# Choosing the repos of a multi-repo workspace
+
+People can't choose from folder names alone, and every team's machine looks different. Do the
+homework first, then recommend a selection with reasons. Work from evidence, never from the names.
+
+## 1. Find candidates (any folder layout)
+
+- Git repos below the workspace folder. Start two levels down; go deeper only when the layout calls
+  for it (`~/code/github.com/<org>/<repo>`, `~/work/<client>/<repo>`). Skip worktrees (their `.git`
+  is a file), `node_modules`, vendor and build folders.
+- Repos in `{specs_dir}/team-repos.yml` if it exists, including ones not cloned here.
+- Repos the user names from other folders, and git submodules of the current repo.
+- **Lots of repos?** Don't list them all. Rank by the evidence below and show the top 8 or so, then
+  "N other repos found, name any you want added".
+
+## 2. For each candidate, gather (cheap commands; read only what's needed)
+
+**What it is**, in one line. The first that exists:
+1. `team-repos.yml` role.
+2. README's first heading and paragraph. Skip boilerplate from a framework template.
+3. Manifest description: `package.json`, `pyproject.toml`, `Cargo.toml`, `go.mod` module path,
+   `pom.xml`/`build.gradle` artifact, `composer.json`.
+4. `AGENTS.md`/`CLAUDE.md` first lines.
+5. Its shape: main folders and entry point (e.g. "a Go service with `cmd/worker`").
+
+**How it connects to the current repo.** Search the current repo (and the candidate) for any of
+these, and quote one piece of evidence with `path:line`:
+
+| Link | What to look for |
+|---|---|
+| Runtime calls | the candidate's name, hostnames, base-URL env vars, API paths, in code, `.env.example`, config |
+| Contracts | OpenAPI/Swagger clients, GraphQL schemas, gRPC/protobuf files, generated SDKs naming the other service |
+| Packages | one repo depends on the other's package (npm, PyPI, Go module, Maven, NuGet, internal registry) |
+| Infrastructure | `docker-compose` services, Kubernetes/Helm manifests, Terraform, CI jobs that check out the other repo |
+| Messages and data | queue or topic names, event names, a shared database or schema both mention |
+| Code layout | git submodules, shared generated code, copied types |
+| Docs | `README`, `AGENTS.md`, architecture docs saying "calls X" or "consumed by Y". A passing mention ("unlike X") is not a link |
+
+**Whether the user works on it:** `git log --since=90.days --author="$(git config user.email)"
+--oneline | wc -l`. Use it as a hint only. A new team member has no commits anywhere, so recommend
+from code links and `team-repos.yml` alone, and don't mention commits.
+
+**Owner:** `git remote get-url origin`. Same organisation is weak evidence, never enough alone.
+
+## 3. Recommend, then ask once
+
+Group the candidates:
+- **I'd include**: the current repo, plus repos with a real link (any row above). Give the reason
+  and the evidence for each.
+- **Probably not needed for this repo**: the rest, each with a short why ("no link found").
+- **No links found at all?** Say so plainly and ask the user to describe which repos change together
+  with this one. Some systems connect only through a shared database or a message queue the code
+  doesn't name.
+
+Ask it with the host's interactive question tool when there is one: after the layout question, a
+`multiSelect` question with **one option per repo** (never bundles of repos), the recommended ones
+first, evidence in each option's description, 2–4 options. End the question text with the other
+repos found by name and how to add them ("choose *Type something* and enter names or paths, e.g.
+`old-admin, ~/Work/billing`"), since the menu only shows 4. Otherwise as text.
+Shape of the question, with placeholders rather than real names:
+
+> I found 6 repos under ~/code/github.com/acme. Based on the code, I'd include:
+> - ✓ **orders-api**: this repo, the orders REST service (FastAPI)
+> - ✓ **payments-worker**: a Go worker. `docker-compose.yml:31` runs it next to this API, and both
+>   use the `payment.requested` queue (`app/events.py:12`)
+> - ✓ **storefront-web**: React app. Its generated client `src/api/orders.ts` is built from this
+>   repo's OpenAPI spec
+>
+> Probably not needed for this repo:
+> - **design-tokens**, **marketing-site**, **old-admin**: no link to orders-api found
+>
+> Keep these three, or add any of the others (or a repo from another folder)? You can change this
+> any time: "add old-admin to the workspace".
+
+Rules:
+- Never pick for the user silently, and never include a repo because it's in the same folder.
+- Someone new should be able to answer "yes". An expert can adjust.
+- Fewer repos is better: investigations search every listed repo, so extra ones cost tokens.
+- Write nothing until they answer, and show the chosen repos again in the final summary.