@benjaminthomas/spec-driven-dev 1.13.0 → 1.14.0

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.
@@ -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 |
@@ -741,7 +761,7 @@ skips that step rather than failing.
 | Skill | Stage | SKILL.md lines | Words | Supporting files |
 |---|---|---:|---:|---:|
 | `spec-setup` | 0 · configure | 210 | 2,201 | 3 |
-| `spec-investigate` | 1 · understand | 385 | 3,325 | 1 |
+| `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 |
@@ -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,045** | **17,653** | **22** |
+| **Total** | | **2,047** | **17,695** | **22** |
 
 - **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.0 && git push origin v1.13.0`.
+  3. Tag the release and push the tag: `git tag v1.14.0 && git push origin v1.14.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,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).
@@ -167,17 +168,24 @@ async function install() {
 // happen in the AI tool. Claude Code and Codex can be opened with the request already typed in.
 const LAUNCHERS = [["claude", "Claude Code"], ["codex", "Codex"]];
 async function handOver(tools, onlySetup) {
+  // The folder says where the AI tool opens; "project" says what gets set up (it can span several repos).
   const name = path.basename(gitTop(DIR));
-  step(onlySetup ? 1 : 2, `Set up ${name} in your AI tool`, ink.magenta);
-  console.log(`
-${onlySetup ? "Setup happens in your AI tool now, so it can read the code and you can change any answer as you go." : "Skills installed."}
-Next: set up ${name}. In your AI tool, say "run spec-setup". It asks how the project is organised
-(single repo, monorepo, or several repos), your tracker, branches and whether to share specs,
-then looks through the code. Start a new session if your tool doesn't recognise it yet.${onlySetup ? `
-For scripts and CI: spec-driven-dev setup --yes [--layout=… --repos=… --share=…]` : ""}`);
-  const launcher = LAUNCHERS.find(([bin]) => (onlySetup || tools.includes(bin)) && onPath(bin));
-  if (!launcher || !process.stdin.isTTY || YES || onlySetup) return;
-  if (!(await askConfirm(`Open ${launcher[1]} here now and start it? (takes a few minutes, uses your ${launcher[1]} plan)`, true))) return;
+  const what = "It first asks how your project is organised: one repo, a monorepo, or several repos that change together.";
+  const next = `Next: in ${name}, open your AI tool and say "run spec-setup".\n${what}
+Then it asks about your tracker, branches and sharing, and looks through the code.
+Start a new session if your tool doesn't recognise it yet.`;
+  step(onlySetup ? 1 : 2, "Set up your project in your AI tool", ink.magenta);
+  if (onlySetup) {
+    console.log(`Setup happens in your AI tool now, so it can read the code and you can change any answer as you go.\n${next}\nFor scripts and CI: spec-driven-dev setup --yes [--layout=… --repos=… --share=…]`);
+    return;
+  }
+  const launcher = LAUNCHERS.find(([bin]) => tools.includes(bin) && onPath(bin));
+  if (!launcher || !process.stdin.isTTY || YES) { console.log(`Skills installed.\n${next}`); return; }
+  // The question carries the explanation, so there's no paragraph to read twice.
+  if (!(await askConfirm(`Open ${launcher[1]} in ${name} to set up your project? ${what} (A few minutes, on your ${launcher[1]} plan.)`, true))) {
+    console.log(next);
+    return;
+  }
   const { spawnSync } = await import("node:child_process");
   spawnSync(launcher[0], ["run spec-setup"], { cwd: DIR, stdio: "inherit" });
 }
@@ -886,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);
@@ -916,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");
@@ -923,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.0",
+  "version": "1.14.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.13.0",
+  "version": "1.14.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-investigate/SKILL.md

@@ -84,12 +84,14 @@ Use it only when `.spec-driven.yml` has `risk.enabled: on`, or has no `risk:` bl
 file, compute scores, or mention risk. That keeps on/off comparisons (`spec-driven-dev risk-eval`)
 clean.
 
-1. Once you know the change surface, look up its files: `spec-driven-dev risk --files=a,b` (or
+1. **Required, not optional:** once you know the change surface, and before writing the report, look up its files: `spec-driven-dev risk --files=a,b` (or
    `npx -y @benjaminthomas/spec-driven-dev risk --files=…`), or find them in `risk.md`. Without the
    CLI, approximate a file's history with `git log --since="2 years ago" --format=%s -- <file>`.
 2. For each **high** or **critical** file in the surface, look harder: read its last ~10 commit
    subjects and the diffs of its last 1–2 fix commits, and check its dependents. Write what keeps
    breaking there in the report's **Risk Hotspots** section.
+   The report's **Risk Hotspots** section must exist when risk is on: list the high/critical files,
+   or write "none of the touched files are high or critical (checked)" so a reader knows it was done.
 3. A score is a reason to look harder, never evidence. Hotspot findings still need their
    VERIFIED / INFERRED labels.
 4. **New files** (added in the last 90 days with fewer than 3 commits, or not committed yet) show as tier `new`: too little