@chankov/agent-skills 0.2.0 → 0.3.0

package/bin/lib/bootstrap.js

@@ -0,0 +1,254 @@
+// bootstrap.js — drop the minimum installer artifacts a coding agent needs
+// to recognize `/setup-agent-skills` and `/doctor-agent-skills`.
+//
+// The CLI's `init` calls this before the handoff message. Without it, a
+// fresh workspace has no `.claude/commands/setup-agent-skills.md`, `.pi/prompts/setup-agent-skills.md`,
+// etc., so the agent has no idea what `/setup-agent-skills` is and the whole hand-off
+// breaks silently.
+//
+// What we bootstrap (per agent):
+//   - The `setup` slash command (so the user can invoke it)
+//   - The `doctor` slash command (same)
+//   - The `guided-workspace-setup` skill body (the slash command says
+//     "load this skill" — the skill must be present somewhere the agent
+//     auto-discovers)
+//
+// What we do NOT bootstrap:
+//   - Any of the user-facing skills (spec-driven-development,
+//     test-driven-development, …). Those are picked by the user inside
+//     /setup-agent-skills, by design. The CLI never decides the workspace's catalogue
+//     for the user.
+//
+// Method:
+//   `copy`    — safe default; works for npx caches that may be cleaned
+//   `symlink` — leaner; only safe when the source root is stable
+//               (global install / git clone). Warning printed if the
+//               source path looks like an npx cache.
+
+import { existsSync, mkdirSync, copyFileSync, symlinkSync, unlinkSync, lstatSync, rmSync, readdirSync, rmdirSync } from "node:fs";
+import { dirname, join, relative } from "node:path";
+
+// (agent → list of {kind, src, dest}) — kind is just for the report.
+//
+// All installer slash commands are namespaced with `-agent-skills` so they
+// don't collide with workspace-defined or other-tool slash commands. The
+// short names (setup, doctor, as-setup, as-doctor) were used in 0.2.0 and
+// earlier — cleanupLegacyNames() removes those if found.
+function plan({ agent, sourceRoot, workspace }) {
+  const skillSrc = join(sourceRoot, "skills", "guided-workspace-setup", "SKILL.md");
+
+  switch (agent) {
+    case "claude-code":
+      return [
+        { kind: "command", src: join(sourceRoot, ".claude/commands/setup-agent-skills.md"),
+          dest: join(workspace, ".claude/commands/setup-agent-skills.md") },
+        { kind: "command", src: join(sourceRoot, ".claude/commands/doctor-agent-skills.md"),
+          dest: join(workspace, ".claude/commands/doctor-agent-skills.md") },
+        { kind: "skill",   src: skillSrc,
+          dest: join(workspace, ".claude/skills/guided-workspace-setup/SKILL.md") },
+      ];
+
+    case "pi":
+      return [
+        { kind: "prompt", src: join(sourceRoot, ".pi/prompts/setup-agent-skills.md"),
+          dest: join(workspace, ".pi/prompts/setup-agent-skills.md") },
+        { kind: "prompt", src: join(sourceRoot, ".pi/prompts/doctor-agent-skills.md"),
+          dest: join(workspace, ".pi/prompts/doctor-agent-skills.md") },
+        // pi auto-discovers skills from .pi/skills/ and .agents/skills/ —
+        // we use .pi/skills/ to avoid polluting a shared .agents/ dir if
+        // the user has other tools there.
+        { kind: "skill",  src: skillSrc,
+          dest: join(workspace, ".pi/skills/guided-workspace-setup/SKILL.md") },
+      ];
+
+    case "opencode":
+      // OpenCode discovers skills + commands from ~/.config/opencode/ (global)
+      // and references AGENTS.md. A project-local bootstrap is awkward — we
+      // drop the command file into .opencode/commands/ (which OpenCode does
+      // load from the project) and the skill alongside it, then flag the
+      // AGENTS.md gap for the user.
+      return [
+        { kind: "command", src: join(sourceRoot, ".opencode/commands/as-setup-agent-skills.md"),
+          dest: join(workspace, ".opencode/commands/as-setup-agent-skills.md") },
+        { kind: "command", src: join(sourceRoot, ".opencode/commands/as-doctor-agent-skills.md"),
+          dest: join(workspace, ".opencode/commands/as-doctor-agent-skills.md") },
+        { kind: "skill",   src: skillSrc,
+          dest: join(workspace, ".opencode/skills/guided-workspace-setup/SKILL.md") },
+      ];
+
+    default:
+      throw new Error(`bootstrap: unknown agent "${agent}"`);
+  }
+}
+
+// Files that were the bootstrap targets in 0.2.0 and earlier (pre-rename).
+// Removed during bootstrap so a workspace upgraded from 0.2.0 doesn't end
+// up with both the old and new slash commands.
+function legacyPaths({ agent, workspace }) {
+  switch (agent) {
+    case "claude-code":
+      return [
+        join(workspace, ".claude/commands/setup.md"),
+        join(workspace, ".claude/commands/doctor.md"),
+      ];
+    case "pi":
+      return [
+        join(workspace, ".pi/prompts/setup.md"),
+        join(workspace, ".pi/prompts/doctor.md"),
+      ];
+    case "opencode":
+      return [
+        join(workspace, ".opencode/commands/as-setup.md"),
+        join(workspace, ".opencode/commands/as-doctor.md"),
+      ];
+    default:
+      return [];
+  }
+}
+
+/**
+ * Run the bootstrap.
+ *
+ * @param {object} opts
+ * @param {string} opts.agent       claude-code | opencode | pi
+ * @param {string} opts.sourceRoot  Absolute path to the installed package
+ * @param {string} opts.workspace   Absolute path to the target workspace
+ * @param {"copy"|"symlink"} opts.method
+ * @param {boolean} [opts.dryRun]
+ * @returns {{written:Array, skipped:Array, warnings:Array}}
+ */
+export function bootstrap({ agent, sourceRoot, workspace, method, dryRun = false }) {
+  const items = plan({ agent, sourceRoot, workspace });
+  const written = [], skipped = [], removed = [], warnings = [];
+
+  // Warn if the user asked for symlink against an unstable source.
+  if (method === "symlink" && /\/\.npm\/_npx\//.test(sourceRoot)) {
+    warnings.push(
+      "--method symlink against an npx cache path: links will break when " +
+      "the cache is cleaned. Consider --method copy or install globally " +
+      "with `npm install -g @chankov/agent-skills`.",
+    );
+  }
+
+  // Clean up pre-0.3.0 file names if present — they were renamed to
+  // *-agent-skills so they don't collide with other slash commands.
+  for (const oldPath of legacyPaths({ agent, workspace })) {
+    if (!existsSync(oldPath) && !isSymlink(oldPath)) continue;
+    if (dryRun) {
+      removed.push(oldPath);
+      continue;
+    }
+    try {
+      unlinkSync(oldPath);
+      removed.push(oldPath);
+    } catch (err) {
+      warnings.push(`could not remove legacy file ${relative(workspace, oldPath)}: ${err.message}`);
+    }
+  }
+
+  for (const item of items) {
+    if (!existsSync(item.src)) {
+      warnings.push(`missing source: ${relative(sourceRoot, item.src)} (skipping ${item.kind})`);
+      continue;
+    }
+
+    if (dryRun) {
+      written.push({ ...item, method });
+      continue;
+    }
+
+    try {
+      mkdirSync(dirname(item.dest), { recursive: true });
+
+      // Always replace — the bootstrap is installer scaffolding, not user
+      // data. If we left it stale, an upgraded package would still hand off
+      // to the old /setup-agent-skills command. Step 6 of guided-workspace-setup explicitly
+      // never offers these files in the install menu, so we are the only
+      // mechanism that refreshes them.
+      if (existsSync(item.dest) || isSymlink(item.dest)) {
+        unlinkSync(item.dest);
+      }
+
+      if (method === "symlink") {
+        symlinkSync(item.src, item.dest);
+      } else {
+        // copyFileSync handles plain files; for the SKILL.md case the source
+        // may have sibling support files in some skills — but
+        // guided-workspace-setup is a single-file skill, so copyFileSync is
+        // fine. Switch to cpSync if that ever changes.
+        copyFileSync(item.src, item.dest);
+      }
+      written.push({ ...item, method });
+    } catch (err) {
+      skipped.push({ ...item, error: err.message });
+    }
+  }
+
+  return { written, skipped, removed, warnings };
+}
+
+/**
+ * Remove every bootstrap artifact this module knows how to write. Called
+ * by guided-workspace-setup at the end of Step 10 unless the user chose
+ * to keep the installer commands. After cleanup, the only way back to
+ * /setup-agent-skills is to re-run `npx @chankov/agent-skills init`.
+ *
+ * The same `agent` value must be supplied that was used at bootstrap time —
+ * we don't have a tracking file, so we delete based on the plan map.
+ *
+ * @param {object} opts
+ * @param {string} opts.agent
+ * @param {string} opts.workspace
+ * @param {boolean} [opts.dryRun]
+ * @returns {{removed:string[], kept:string[], warnings:string[]}}
+ */
+export function cleanupInstaller({ agent, workspace, dryRun = false }) {
+  const planned = plan({ agent, sourceRoot: workspace, workspace });
+  const removed = [], kept = [], warnings = [];
+
+  for (const item of planned) {
+    if (!existsSync(item.dest) && !isSymlink(item.dest)) {
+      kept.push(item.dest); // already gone — count it as a no-op, not an error
+      continue;
+    }
+    if (dryRun) {
+      removed.push(item.dest);
+      continue;
+    }
+    try {
+      const lst = lstatSync(item.dest);
+      if (lst.isDirectory() && !lst.isSymbolicLink()) {
+        rmSync(item.dest, { recursive: true });
+      } else {
+        unlinkSync(item.dest);
+      }
+      removed.push(item.dest);
+
+      // If we removed the only file in a parent directory we created
+      // (.claude/skills/guided-workspace-setup/), prune the directory too.
+      pruneEmptyDirsUpTo(dirname(item.dest), workspace);
+    } catch (err) {
+      warnings.push(`could not remove ${relative(workspace, item.dest)}: ${err.message}`);
+    }
+  }
+
+  return { removed, kept, warnings };
+}
+
+function pruneEmptyDirsUpTo(dir, workspace) {
+  // Walk upward removing empty parent dirs until we hit a non-empty one or
+  // the workspace root. Never delete the workspace itself.
+  try {
+    while (dir !== workspace && dir.startsWith(workspace)) {
+      const entries = readdirSync(dir);
+      if (entries.length > 0) return;
+      rmdirSync(dir);
+      dir = dirname(dir);
+    }
+  } catch { /* prune is best-effort */ }
+}
+
+function isSymlink(path) {
+  try { return lstatSync(path).isSymbolicLink(); }
+  catch { return false; }
+}

package/bin/lib/doctor.js

@@ -1,6 +1,6 @@
 // Doctor scan — deterministic preflight extracted from
 // guided-workspace-setup Step 5. Both `agent-skills doctor` (CLI) and the
-// `/doctor` slash command call into this so behaviour cannot drift.
+// `/doctor-agent-skills` slash command call into this so behaviour cannot drift.
 //
 // Two classes of findings:
 //   1. Broken symlinks — links whose source has been moved, renamed, or deleted

package/docs/getting-started.md

@@ -14,7 +14,7 @@ Each skill is a Markdown file (`SKILL.md`) that describes a specific engineering
 |---|---|---|
 | **Most users** — you want to use the skills in your projects | `npx @chankov/agent-skills init` | One command; semver updates; cross-platform; no source dir to babysit. See [docs/npm-install.md](npm-install.md). |
 | **Claude Code users** — you live in Claude Code and want plugin-managed updates | `/plugin marketplace add chankov/agent-skills` | Best UX inside Claude Code; marketplace handles the lifecycle. |
-| **Skill authors / contributors** — you want to edit the skills and have changes flow into every connected workspace | `git clone` + `symlink` mode in `/setup` | Edit-in-place; every connected workspace sees the change instantly. |
+| **Skill authors / contributors** — you want to edit the skills and have changes flow into every connected workspace | `git clone` + `symlink` mode in `/setup-agent-skills` | Edit-in-place; every connected workspace sees the change instantly. |
 
 All three converge on the same `guided-workspace-setup` skill — they only differ in how the source files reach your workspace. None is being deprecated.
 
@@ -124,7 +124,7 @@ The `.claude/commands/` directory contains slash commands for Claude Code:
 
 | Command | Skill Invoked |
 |---------|---------------|
-| `/setup` | guided-workspace-setup |
+| `/setup-agent-skills` | guided-workspace-setup |
 | `/spec` | spec-driven-development |
 | `/plan` | planning-and-task-breakdown |
 | `/build` | incremental-implementation + test-driven-development |

package/docs/npm-install.md

@@ -31,18 +31,41 @@ So:
 # In the workspace you want to configure:
 npx @chankov/agent-skills init
 # Then open your coding agent in this directory and run:
-#   /setup
+#   /setup-agent-skills
 ```
 
 That's it. `npx` fetches the package, the CLI detects your coding agent and
-prints the next-step command, and `/setup` runs the full guided install
+prints the next-step command, and `/setup-agent-skills` runs the full guided install
 inside your agent.
 
 ## Commands
 
 ### `npx @chankov/agent-skills init`
 
-Materializes the package and hands off to `/setup`.
+Materializes the package, **bootstraps the installer artifacts** into the
+workspace (so the agent has a `/setup-agent-skills` and `/doctor-agent-skills` command to invoke),
+and hands off to `/setup-agent-skills`.
+
+What `init` writes per agent:
+
+| Agent | Files written to the workspace |
+|---|---|
+| `claude-code` | `.claude/commands/setup-agent-skills.md`, `.claude/commands/doctor-agent-skills.md`, `.claude/skills/guided-workspace-setup/SKILL.md` |
+| `pi` | `.pi/prompts/setup-agent-skills.md`, `.pi/prompts/doctor-agent-skills.md`, `.pi/skills/guided-workspace-setup/SKILL.md` |
+| `opencode` | `.opencode/commands/as-setup-agent-skills.md`, `.opencode/commands/as-doctor-agent-skills.md`, `.opencode/skills/guided-workspace-setup/SKILL.md` |
+
+These are **just the plumbing** — the slash commands, plus the skill they
+invoke. The actual catalogue (spec-driven-development, code-reviewer,
+test-engineer, pi extensions, …) is picked by you inside `/setup-agent-skills`. Re-run
+`init` to refresh the plumbing after a package upgrade; bootstrap files
+are always overwritten because they're scaffolding, not user data.
+
+After `/setup-agent-skills` finishes its install pass, **the bootstrap files
+are removed by default** so they don't clutter your agent's slash-command
+list. Re-run `npx @chankov/agent-skills init` whenever you want
+`/setup-agent-skills` back. To keep them in place across runs, reply `keep`
+to the Step 9 confirmation prompt — the skill will record
+`keep-installer: true` in `.ai/agent-skills-setup.md`.
 
 | Flag | Default | Purpose |
 |------|---------|---------|
@@ -60,7 +83,7 @@ npx @chankov/agent-skills init --workspace ~/projects/foo --method symlink
 
 Deterministic preflight scan — walks every install-target directory, lists
 broken symlinks and stale persona references, and offers fixes. Same scan
-that `/doctor` runs inside the agent.
+that `/doctor-agent-skills` runs inside the agent.
 
 | Flag | Default | Purpose |
 |------|---------|---------|
@@ -78,13 +101,13 @@ npx @chankov/agent-skills doctor -y
 Reads the workspace's `.ai/agent-skills-setup.md`, compares the recorded
 package version against the installed package version, and prints the next
 step. The actual diff-aware refresh runs inside the coding agent via
-`/setup`.
+`/setup-agent-skills`.
 
 ```bash
 # Upgrade the package itself first, then check the delta:
 npm install -g @chankov/agent-skills@latest
 npx agent-skills update --workspace .
-# Then open your agent and run /setup to review per-artifact diffs.
+# Then open your agent and run /setup-agent-skills to review per-artifact diffs.
 ```
 
 ## Versioning
@@ -137,7 +160,7 @@ npm is the recommended path for most users. The other two stay supported:
 - **[Claude Code plugin marketplace](../README.md#quick-start)** — best UX
   inside Claude Code. Same skills, marketplace-managed updates.
 - **Git clone + symlinks** — best for skill authors and contributors. Clone
-  the repo, run `/setup` from there, choose `symlink` in Step 8. Updates
+  the repo, run `/setup-agent-skills` from there, choose `symlink` in Step 8. Updates
   flow through `git pull`. Symlinks need Developer Mode on Windows.
 
 All three paths converge on the same `guided-workspace-setup` skill — the
@@ -153,7 +176,7 @@ npx --yes @chankov/agent-skills@latest init --agent claude-code --method copy --
 ```
 
 `doctor` accepts `--yes` for non-interactive repair. Note that the
-LLM-driven `/setup` flow is not CI-runnable by design — confirmation gates
+LLM-driven `/setup-agent-skills` flow is not CI-runnable by design — confirmation gates
 exist precisely so a human approves every write.
 
 ## Receiving update notifications
@@ -182,15 +205,15 @@ If the cache is stale, a detached background process refreshes it for the
 
 ### 2. Claude Code session-start hook
 
-When `hooks/session-start.sh` is installed (offered in Group 18 of `/setup`),
+When `hooks/session-start.sh` is installed (offered in Group 18 of `/setup-agent-skills`),
 every new Claude Code session runs the check with a 3-second wall-clock cap.
 If an upgrade is available, the banner is injected into the session context
 so Claude can mention it on its first turn — e.g. *"Note: agent-skills 0.2.0
-is available; want me to apply it via `/setup`?"*
+is available; want me to apply it via `/setup-agent-skills`?"*
 
 ### 3. pi extension (`agent-skills-update-check`)
 
-When installed (offered in Group 10 of `/setup`), the extension fires on the
+When installed (offered in Group 10 of `/setup-agent-skills`), the extension fires on the
 first `agent_start` event of each pi session and emits a `ctx.ui.notify`
 message in the pi UI if a newer version is published. Reads the same cache
 as the CLI — no double-fetching.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@chankov/agent-skills",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Production-grade engineering skills for AI coding agents. Ships skills, agent personas, slash commands, and pi extensions, with a thin CLI that hands off to the LLM-driven guided setup.",
   "keywords": [
     "ai",

package/skills/guided-workspace-setup/SKILL.md

@@ -108,7 +108,7 @@ Present findings in a single table:
 
 Then ask, multi-select: which fixes to apply now. Apply only the picked ones; record skipped items so the install menu can surface them again. Append a `## doctor-runs` line to `.ai/agent-skills-setup.md` with the date, agent, phase (`preflight`), and `repaired` / `deleted` / `skipped` counts.
 
-The doctor scan is also exposed standalone as `/doctor` — running it outside a setup pass is this same scan-and-repair flow without the rest of the install menu.
+The doctor scan is also exposed standalone as `/doctor-agent-skills` — running it outside a setup pass is this same scan-and-repair flow without the rest of the install menu.
 
 ### 6. Present the install menu
 
@@ -207,6 +207,8 @@ Ask `copy` or `symlink` for this run.
 
 Present the full set as one summary table — artifacts to add, update, and remove; their resolved target paths; the chosen install method; and the changes to both `.ai/` files. When the version delta from Step 4 is non-empty, lead the summary with a one-line "Changes since `v<recorded>` → `v<current>`" block sourced from `CHANGELOG.md` (only the entries between the two versions, not the full file). Ask the user to confirm, and write nothing until they do.
 
+**Installer cleanup line.** The summary always ends with one line stating that the installer slash commands (`/setup-agent-skills`, `/doctor-agent-skills` — or `/as-*-agent-skills` for OpenCode — plus the `guided-workspace-setup` skill body) will be removed after apply, so they do not pollute the user's slash-command list. Add the verbatim suffix: *"Reply `keep` to leave them in place; re-run `npx @chankov/agent-skills init` later if removed."* If the user replies `keep`, record `keep-installer: true` in `## workspace-summary` and skip Step 10b. Otherwise the default is to remove them.
+
 ### 10. Apply the setup
 
 Apply the changes: create directories, add or update selected artifacts, and remove deselected ones — **bound by the removal-scope rule from Step 6**. Before deleting any target, verify both conditions: (a) the name is in the agent-skills inventory and (b) the item is either listed in `## install-status` or is a symlink resolving into the source repo. If either check fails, skip the deletion silently and log the path under a "Skipped — not owned by agent-skills" line in the final report.
@@ -217,10 +219,36 @@ For settings files (`.claude/settings.json` and equivalents), edit only the agen
 
 Then write both `.ai/` files: the agreed override sections from Step 7 into `.ai/agent-skills-overrides.md`, and the install record — artifacts, target paths, method, **package version**, date — into `.ai/agent-skills-setup.md`. The `version:` line in `## workspace-summary` is set to the package version from Step 2; this is what the next re-run will compare against to compute the version delta.
 
+### 10b. Remove the installer artifacts (unless the user said `keep`)
+
+After Step 10 has written the catalogue + the `.ai/` files, the installer files dropped by `npx @chankov/agent-skills init` — the `setup-agent-skills` / `doctor-agent-skills` slash commands and the `guided-workspace-setup` skill body itself — are no longer needed in the workspace. They were bootstrap plumbing, not part of the user's permanent install. Leaving them in place pollutes the agent's slash-command list and confuses re-runs (which should always go through `init`, not a stale local copy).
+
+Default behaviour:
+
+- **`keep-installer: true` in `## workspace-summary`** → skip this step. The files stay.
+- **Otherwise** → run the cleanup. Delete every file the bootstrap wrote for the chosen agent:
+
+| Agent | Files removed |
+|---|---|
+| `claude-code` | `.claude/commands/setup-agent-skills.md`, `.claude/commands/doctor-agent-skills.md`, `.claude/skills/guided-workspace-setup/SKILL.md` |
+| `pi` | `.pi/prompts/setup-agent-skills.md`, `.pi/prompts/doctor-agent-skills.md`, `.pi/skills/guided-workspace-setup/SKILL.md` |
+| `opencode` | `.opencode/commands/as-setup-agent-skills.md`, `.opencode/commands/as-doctor-agent-skills.md`, `.opencode/skills/guided-workspace-setup/SKILL.md` |
+
+After deleting, prune any directories that were created solely for these files (e.g. `.claude/skills/guided-workspace-setup/`) — never prune a directory that contains other files.
+
+Note: the skill body file you are removing here is the same file the agent is *currently executing*. Filesystem removal does not interrupt the in-memory copy — finish this step, then Step 11, then return as normal.
+
+If `cleanupInstaller` is available via the CLI (`npx @chankov/agent-skills cleanup-installer --agent <agent> --workspace <path>`), invoking it is equivalent to the manual deletions above; either path is acceptable. Failures (permission denied, file already gone) are logged but do not abort the apply.
+
 ### 11. Verify and report
 
 Re-scan the install-target directories one more time and confirm: every selected artifact exists at its target path, every deselected one is gone, and zero broken symlinks remain. Also re-read `.ai/agent-skills-setup.md` and verify the `version:` line matches the package version from Step 2 — a mismatch here means the apply pass did not stamp the new version, and must be corrected before the next re-run computes the wrong delta. If the post-apply scan surfaces any new breakage, treat it as a doctor finding and offer the same repair options as Step 5, then append a second `## doctor-runs` line with `phase: postflight`. List what changed, point the user at `.ai/agent-skills-overrides.md` and `.ai/agent-skills-setup.md`, and suggest loading `using-agent-skills` first in their next session.
 
+Close the report with one line explaining the installer-cleanup outcome:
+
+- If Step 10b ran: *"Installer slash commands removed from your workspace. Re-run `npx @chankov/agent-skills init` if you need `/setup-agent-skills` back."*
+- If Step 10b was skipped (`keep-installer: true`): *"Installer slash commands kept in place per your choice. `/setup-agent-skills` and `/doctor-agent-skills` remain available."*
+
 ## Common Rationalizations
 
 | Rationalization | Reality |
@@ -237,10 +265,13 @@ Re-scan the install-target directories one more time and confirm: every selected
 | "I'll record the full install detail in the overrides file too — one place is simpler." | Other skills load the overrides file on every run. Install detail belongs only in `agent-skills-setup.md`; padding the overrides file taxes every later session. |
 | "There's an unfamiliar skill in `.claude/skills/` — the user must have forgotten to uncheck it, I'll remove it." | The removal scope rule exists exactly to prevent this. If the name is not in the agent-skills inventory or not in `## install-status`, it is user-owned; leave it alone and log it as skipped. |
 | "The user wants a clean workspace — I'll prune custom hooks and unrelated MCP entries from `settings.json` too." | Setting-file edits are limited to agent-skills' own hook registrations. Touching anything else silently deletes work that does not belong to this skill. |
-| "`/setup` and `/doctor` are useful — I'll install them into the workspace so the user can re-run them locally." | They are installer commands; they ship with the source agent-skills repo and act on workspaces from there. Installing them into a target duplicates the install surface and gives the target a path to manipulate itself. |
+| "`/setup-agent-skills` and `/doctor-agent-skills` are useful — I'll re-install them at the end of apply so the user can re-run them locally." | They are installer commands that the CLI bootstraps and the skill itself cleans up in Step 10b by default. Keeping them is opt-in via `keep` in Step 9. Re-installing them silently undoes the cleanup the user implicitly chose. |
 | "The recorded version differs from the current — I'll just refresh everything to the new source without showing the diff." | Conflicting upgrades (user-modified copy + source changed upstream) require the three-way diff to be shown in Step 6, with the row pre-unchecked. Refreshing silently overwrites work the user did between versions. |
 | "The `.versions/<recorded>/` snapshot is missing — I'll pretend the installed copy matches the recorded source and refresh anyway." | A missing snapshot means we cannot compute the three-way diff. The skill must fall back to "treat installed copy as canonical" and surface the missing snapshot in the row's status so the user can decide — never pretend a diff exists. |
 | "The workspace has no `version:` line — I'll silently stamp the current version and move on." | A pre-versioning workspace must be flagged in Step 4 and the user prompted: stamp the current version (assume copies match) or wipe and reinstall. Silent stamping hides a real decision. |
+| "The user didn't say anything about the installer cleanup line — I'll leave the installer files in place to be safe." | The default is to remove. Step 9's confirmation line explicitly states the cleanup will happen unless the user replies `keep`. Silence is consent for the default, not opt-out from it. |
+| "I'll add `setup-agent-skills` and `doctor-agent-skills` to the install menu so the user can pick whether to keep them." | They are still installer-only and excluded from the menu. The keep-vs-remove choice is the single Step 9 line, not a menu group — adding them to the menu re-opens the pollution we just fixed. |
+| "The skill is currently executing; deleting its own file in Step 10b will crash mid-run." | The agent loads the skill into memory at the start of execution. Removing the file on disk does not unload the in-memory copy — Steps 10b and 11 complete normally before control returns. |
 
 ## Red Flags
 
@@ -265,6 +296,10 @@ Re-scan the install-target directories one more time and confirm: every selected
 - A `conflicting upgrade` row pre-checked, or the three-way diff omitted for it.
 - A pre-versioning workspace stamped with the current version without prompting the user first.
 - The post-apply `version:` line not matching the package version from Step 2.
+- Step 9 summary missing the installer-cleanup line, or the line stated `keep` as the default.
+- Installer files (`setup-agent-skills`, `doctor-agent-skills`, the `guided-workspace-setup` skill body) left in place without a recorded `keep-installer: true`.
+- `setup-agent-skills` or `doctor-agent-skills` shown as install-menu rows.
+- Step 11 report omitting the one-line installer-cleanup outcome.
 
 ## Verification
 
@@ -287,6 +322,9 @@ After completing the workflow, confirm:
 - [ ] When the version delta was non-empty, Step 9's summary led with the "Changes since v<recorded> → v<current>" block sourced from `CHANGELOG.md`.
 - [ ] Every `conflicting upgrade` row was rendered with its three-way diff in Step 6 and was not pre-checked.
 - [ ] A pre-versioning workspace was flagged in Step 4 and the user was prompted to stamp or wipe — not silently stamped.
+- [ ] Step 9 summary ended with the installer-cleanup line: states remove-by-default and offers `keep` as the opt-out.
+- [ ] Step 10b ran (or was explicitly skipped because `keep-installer: true`); the installer files are absent from the workspace unless the user opted to keep them.
+- [ ] Step 11 report includes the one-line installer-cleanup outcome.
 - [ ] No broken symlinks remain in any of the scanned install-target directories.
 - [ ] No YAML config references a removed persona name.
 - [ ] No secrets were written to either `.ai/` file.