@benjaminthomas/spec-driven-dev 1.13.1 → 1.14.1

package/README.md

@@ -75,7 +75,8 @@ and you can change any answer as you go. It asks how the project is organised (o
 or several repos that change together), your tracker, branches and commit style, where specs live
 and whether your team shares them, then looks through the code and saves the project memory
 ([details below](#project-setup-your-teams-rules)). If Claude Code or Codex is installed, the
-installer offers to open it with "run spec-setup" already typed in.
+installer asks "Open Claude Code in soreto-shopify to set up your project?" (with your folder's name)
+and opens it with "run spec-setup" already typed in.
 
 **3. Then run each stage in order.** You can type the slash command or just say the
 words in quotes.
@@ -149,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` |
@@ -272,8 +273,9 @@ a build output. Committing it would cause merge conflicts between branches. `doc
 it's committed.
 
 When `risk.enabled` is on, the skills use it:
-- `spec-investigate` digs into high and critical files in the change surface (past fix commits,
-  dependents) and lists them as **Risk Hotspots**;
+- `spec-investigate` always looks up the files in the change surface, digs into high and critical
+  ones (past fix commits, dependents), and lists them as **Risk Hotspots**, or says it checked and
+  found none;
 - `spec-create` raises those tasks one tier and requires a test aimed at each file's past failure
   pattern;
 - `spec-implement`'s reviewer and `spec-review` check those tests and read the risky files line
@@ -644,6 +646,7 @@ 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 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
                                                   #   (--runs=3 --arms=on --timeout=20 --model=sonnet)
@@ -717,6 +720,23 @@ Each skill becomes a tool that returns its instructions, and supporting files ar
 
 ---
 
+### Uninstall
+
+```bash
+npx @benjaminthomas/spec-driven-dev@latest uninstall
+```
+
+It lists everything an install put on your machine (the skills in each AI tool, the Claude Code
+plugin, the npx download cache), then removes it after one confirmation. Your other skills stay.
+
+- **Kept by default:** your `.spec-driven.yml` settings file. Add `--all` to remove it and the
+  workspace registry (`~/.spec-driven/`) too.
+- **Never touched:** specs, `CONTEXT.md`, `team-repos.yml` and your code. They're your team's work.
+  Delete them yourself if you want them gone.
+- **In scripts or with `!` in Claude Code:** add `--yes`, since there's no terminal to confirm in.
+- **Plugin installs:** `/plugin uninstall ticket-to-pr@spec-driven-dev` in Claude Code, if the
+  command can't do it for you.
+
 ## Compatibility
 
 | Skill | Claude Code | Codex CLI | Cursor | Antigravity | Notes |
@@ -740,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 | 222 | 2,329 | 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 |
@@ -749,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,059** | **17,823** | **23** |
 
 - **8** skills: **1** setup + **6** workflow stages + **1** standalone
 - **4** tools supported natively (Claude Code, Codex CLI, Cursor, Antigravity), plus an MCP fallback
@@ -802,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.13.1 && git push origin v1.13.1`.
+  3. Tag the release and push the tag: `git tag v1.14.1 && git push origin v1.14.1`.
   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,7 @@
 //
 //   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 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
 //   spec-driven-dev context         print specs/CONTEXT.md; --areas=billing,api prints only those area files
@@ -39,7 +40,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);
+const YES = flag("yes") || flag("y") || !process.stdin.isTTY || ["doctor", "status", "context", "risk", "risk-eval", "setup"].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).
@@ -893,6 +894,45 @@ async function settings() {
   }
 }
 
+// Finds everything an install put on this machine and removes it after one confirmation.
+// Specs, CONTEXT.md and code are never touched: they're the team's work, not part of the install.
+async function uninstall() {
+  const found = [];
+  const ours = (d) => ALL_SKILLS.map((s) => path.join(d, s)).filter((f) => fs.existsSync(path.join(f, "SKILL.md")));
+  const dirs = [...new Set(Object.values(TOOLS).flatMap((t) => [path.join(HOME, t.global), path.join(DIR, t.project)]))];
+  for (const d of dirs) { const f = ours(d); if (f.length) found.push({ what: `${f.length} skills in ${d}`, paths: f }); }
+  const plugins = readJson(path.join(HOME, ".claude/plugins/installed_plugins.json"));
+  const pluginIds = Object.keys(plugins?.plugins || plugins || {}).filter((k) => /^(ticket-to-pr|spec-driven-dev)@/.test(k));
+  for (const id of pluginIds) found.push({ what: `Claude Code plugin ${id}`, plugin: id });
+  const npx = path.join(HOME, ".npm", "_npx");
+  for (const c of subdirs(npx)) if (fs.existsSync(path.join(npx, c, "node_modules", "@benjaminthomas", "spec-driven-dev")) && process.platform !== "win32")
+    found.push({ what: `npx download cache ${path.join(npx, c)}`, paths: [path.join(npx, c)] });
+  const config = findConfig(DIR);
+  const reg = readRegistry();
+  if (flag("all")) {
+    if (config) found.push({ what: `settings file ${config}`, paths: [config], config });
+    if (fs.existsSync(path.join(HOME, ".spec-driven"))) found.push({ what: `workspace registry ${path.join(HOME, ".spec-driven")}`, paths: [path.join(HOME, ".spec-driven")] });
+  }
+  step(1, "Uninstall spec-driven-dev", ink.red);
+  if (!found.length) { console.log("✓ Nothing to remove: no skills, plugin or cache from spec-driven-dev were found."); return; }
+  console.log("Found:\n" + found.map((f) => `  • ${f.what}`).join("\n"));
+  if (!flag("all") && (config || Object.keys(reg).length)) console.log(`  Kept: your settings file${config ? ` (${config})` : ""}. Add --all to remove it too.`);
+  console.log("  Never touched: specs, CONTEXT.md and your code.");
+  if (!process.stdin.isTTY && !flag("yes")) { console.log("Nothing removed. To remove the above, run: spec-driven-dev uninstall --yes"); return; }
+  if (!flag("yes") && !(await askConfirm("Remove everything listed above?", false))) { console.log("Nothing removed."); return; }
+  for (const f of found) {
+    if (f.plugin) {
+      let ok = false;
+      if (onPath("claude")) try { execFileSync("claude", ["plugin", "uninstall", f.plugin], { stdio: "ignore" }); ok = true; } catch {}
+      console.log(ok ? `✓ Removed ${f.what}` : `• Remove the plugin in Claude Code: /plugin uninstall ${f.plugin}`);
+      continue;
+    }
+    for (const p of f.paths) fs.rmSync(p, { recursive: true, force: true });
+    console.log(`✓ Removed ${f.what}`);
+  }
+  console.log("Done. Reinstall any time with: npx @benjaminthomas/spec-driven-dev@latest");
+}
+
 // Silent unless something is unfinished, so it's cheap to run at the start of a session.
 function status() {
   const file = findConfig(DIR);
@@ -923,6 +963,7 @@ try {
   else if (command === "context") context();
   else if (command === "risk") risk();
   else if (command === "settings") await settings();
+  else if (command === "uninstall") await uninstall();
   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");
@@ -930,7 +971,7 @@ try {
     if (tools.length && !flag("no-setup")) await handOver(tools);
   } else if (SETUP_IN_AGENT) handOver([], true);
   else if (command === "setup") await setup();
-  else throw new Error(`Unknown command "${command}" — use install (default), setup, settings, doctor, status, context, risk, or risk-eval`);
+  else throw new Error(`Unknown command "${command}" — use install (default), setup, settings, 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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@benjaminthomas/spec-driven-dev",
-  "version": "1.13.1",
+  "version": "1.14.1",
   "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.13.1",
+  "version": "1.14.1",
   "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,6 +123,15 @@ 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
+
+- **Real choices** (layout, keep these repos, sharing, after-approval mode) can be a menu, but only
+  with **two or more** options. A menu with one option is rejected by the tool and the user never
+  sees the question. "Other" doesn't count as an option.
+- **Open questions** (what the product does, fragile spots, direction, unwritten rules, anything
+  else to add) are plain text in **one chat message**. The user answers in their own words or says
+  "skip". Never turn an open question 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.

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

@@ -41,7 +41,9 @@ 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**. 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/repo-picker.md

@@ -0,0 +1,74 @@
+# 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.
+
+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.