@mmerterden/multi-agent-pipeline 14.2.2 → 15.1.0

package/docs/ecosystem.md

@@ -5,7 +5,7 @@ separately, wired together at install time and at run time:
 
 | Repo | What it owns | Ships as |
 |---|---|---|
-| **`multi-agent-pipeline`** (this repo) | Orchestration: the 8-phase flow, the 49 slash commands, quality gates, review/triage, cross-CLI parity | npm package (`@mmerterden/multi-agent-pipeline`), installs itself onto Claude Code / Copilot CLI / Codex CLI |
+| **`multi-agent-pipeline`** (this repo) | Orchestration: the 8-phase flow, the 51 slash commands, quality gates, review/triage, cross-CLI parity | npm package (`@mmerterden/multi-agent-pipeline`), installs itself onto Claude Code / Copilot CLI / Codex CLI |
 | **`multi-agent-plugins`** | Stack knowledge: per-platform component/lifecycle skills (iOS, Android, Frontend, Backend) + shared knowledge | Claude Code marketplace, 5 independently-versioned plugins |
 | **`dev-toolkit-mcp`** | The pipeline's hands on devices and browsers: 80 MCP tools across 6 categories (simulator/emulator control, accessibility audit, store compliance, web automation, Figma-vs-mock design audit, an agent-DSL batch runner) | npm package, registered as a standard stdio MCP server on every host |
 
@@ -18,17 +18,17 @@ Either can be swapped or removed without touching the other two's source.
 graph LR
     subgraph PIPE ["multi-agent-pipeline (orchestrator)"]
         direction TB
-        PHASES["8 phases · 49 commands"]
+        PHASES["8 phases · 51 commands"]
         GATES["deterministic gates + review triage"]
     end
 
     subgraph PLUG ["multi-agent-plugins (stack knowledge)"]
         direction TB
-        IOSP["ai-ios-engineering-toolkit"]
-        ANDP["ai-android-engineering-toolkit"]
-        FEP["ai-frontend-engineering-toolkit"]
+        IOSP["ai-ios-toolkit"]
+        ANDP["ai-android-toolkit"]
+        FEP["ai-frontend-toolkit"]
         BEP["ai-backend-toolkit"]
-        COMP["ai-common-engineering-toolkit"]
+        COMP["ai-common-toolkit"]
     end
 
     subgraph DTK ["dev-toolkit-mcp (device/browser hands)"]
@@ -63,8 +63,8 @@ only those:
 graph TD
     CC["Claude Code<br/>~/.claude/commands/multi-agent/<br/>(source of truth)"]
 
-    CC -->|"Step 2: copy + reformat<br/>49 sub-command skills"| COP["Copilot CLI<br/>~/.copilot/skills/"]
-    CC -->|"Step 2b: transform<br/>(install.js --codex)"| COD["Codex CLI<br/>1 router skill + 49 refs<br/>+ 8 agent TOML"]
+    CC -->|"Step 2: copy + reformat<br/>51 sub-command skills"| COP["Copilot CLI<br/>~/.copilot/skills/"]
+    CC -->|"Step 2b: transform<br/>(install.js --codex)"| COD["Codex CLI<br/>1 router skill + 51 refs<br/>+ 8 agent TOML"]
     CC -->|"Step 3: genericize<br/>(strip personal data)"| REPO["multi-agent-pipeline repo<br/>pipeline/"]
     CC -->|"Step 4: version + feature sync"| WEB["Website<br/>projects.ts / i18n.tsx"]
 
@@ -75,28 +75,28 @@ graph TD
     CC -.->|"sync only SHIPS this,<br/>never authors it"| SYNC3D
     SYNC3D -.-> DTK2
 
-    REPO -->|"npm publish"| NPM["GitHub Packages"]
+    REPO -->|"npm publish"| NPM["npm registry (public)"]
     WEB -->|"git push → auto-deploy"| VERCEL["Vercel"]
     PLUGREPO -->|"git push"| MKT["Claude Code marketplace"]
-    DTK2 -->|"npm publish"| NPM2["GitHub Packages<br/>(private)"]
+    DTK2 -->|"npm publish"| NPM2["npm registry<br/>(public)"]
 
     style CC fill:#f9f,stroke:#333
     style DTK2 fill:#dff,stroke:#333,stroke-dasharray: 5 5
 ```
 
 **Why `dev-toolkit-mcp` is drawn differently.** The other four targets are *derived*
-from the Claude Code source — sync writes their content. `dev-toolkit-mcp` is not:
+from the Claude Code source - sync writes their content. `dev-toolkit-mcp` is not:
 it's a separate codebase developed on its own schedule. Sync's Step 3d only
 *detects* whether it moved (dirty tree, unpushed commits, untagged version), runs
-**its own** gate suite, and ships it — commit, tag, `npm publish`. If the pipeline
+**its own** gate suite, and ships it - commit, tag, `npm publish`. If the pipeline
 needs a tool that toolkit doesn't have yet, that's a two-repo change: add the tool
 in `dev-toolkit-mcp`, ship it, then bump the minimum version pin back in
-`cross-cli-contract.md` (see §4).
+`cross-cli-contract.md` (see section 4).
 
 **Also not generated: the plugins' own authored skills.** `build-stack-plugins.mjs`
 only rebuilds each plugin's `knowledge/` folder from `pipeline/skills/shared/external/`.
-The plugins' lifecycle skills — `create-component`, `evolve-component`,
-`figma-utility`, `code-connect`, `branch-and-pr`, `fix-bug`, and the rest — are
+The plugins' lifecycle skills - `create-component`, `evolve-component`,
+`figma-utility`, `code-connect`, `branch-and-pr`, `fix-bug`, and the rest - are
 hand-authored *inside* `multi-agent-plugins` and are never touched by sync.
 
 ---
@@ -105,13 +105,13 @@ hand-authored *inside* `multi-agent-plugins` and are never touched by sync.
 
 ```mermaid
 graph TD
-    EXT["pipeline/skills/shared/external/<br/>150 skills — single authoring source<br/>(the pipeline's own phases read these too)"]
+    EXT["pipeline/skills/shared/external/<br/>151 skills - single authoring source<br/>(the pipeline's own phases read these too)"]
 
-    EXT -->|"cross-stack skills"| COMMONP["ai-common-engineering-toolkit<br/>10 skills · v0.2.3"]
-    EXT -->|"Apple/Xcode-only"| IOSP["ai-ios-engineering-toolkit<br/>145 skills · v0.6.0"]
-    EXT -->|"Android/Kotlin-only"| ANDP["ai-android-engineering-toolkit<br/>29 skills · v0.1.3"]
+    EXT -->|"cross-stack skills"| COMMONP["ai-common-toolkit<br/>10 skills · v0.2.3"]
+    EXT -->|"Apple/Xcode-only"| IOSP["ai-ios-toolkit<br/>145 skills · v0.6.0"]
+    EXT -->|"Android/Kotlin-only"| ANDP["ai-android-toolkit<br/>29 skills · v0.1.3"]
     EXT -->|"backend-only"| BEP["ai-backend-toolkit<br/>32 skills · v0.1.4"]
-    EXT -->|"web/frontend-only"| FEP["ai-frontend-engineering-toolkit<br/>24 skills · v0.1.3"]
+    EXT -->|"web/frontend-only"| FEP["ai-frontend-toolkit<br/>24 skills · v0.1.3"]
 
     COMMONP --> BUMP{"skill set<br/>changed?"}
     IOSP --> BUMP
@@ -128,9 +128,9 @@ graph TD
 
 A skill counted in more than one platform plugin (a cross-stack knowledge skill
 plus, say, an iOS-specific one) is why the plugins' skill counts sum to more than
-the 150-skill source: `ai-common` skills are vendored into every stack plugin's
+the 151-skill source: `ai-common` skills are vendored into every stack plugin's
 `knowledge/`, not deduplicated across them. Versioning is per-plugin and
-patch-only from this generator — a repo enabling only `ai-ios-engineering-toolkit`
+patch-only from this generator - a repo enabling only `ai-ios-toolkit`
 never pulls an Android-only change.
 
 **Consumption is pull, not push.** A consumer repo enables a stack plugin once
@@ -150,9 +150,9 @@ measurements behind this table):
 
 | | Claude Code | Copilot CLI | Codex CLI |
 |---|---|---|---|
-| **Pipeline commands** | 49 slash-command skills, native | 49 skills, `multi-agent-{cmd}` naming, copied in | 1 router skill (`multi-agent`) + 49 command specs as reference files — Codex silently truncates its skills block past a few dozen entries, so sub-commands are not peer skills here |
-| **Stack plugins** | Marketplace plugin, loaded natively, resolved by `.claude/settings.json` enabled-list | Enabled plugin's authored skills copied flat into `~/.copilot/skills/`; `knowledge/` **not** re-copied (already delivered via `shared/external`) | Copied as reference files under `~/.codex/multi-agent-refs/skills/`, plugin-prefixed on name clash (e.g. `architecture` → `ai-ios-engineering-toolkit-architecture`) |
-| **Component dispatch (Phase 3)** | Marketplace plugin's `create-component`/`create-screen` skill via the Skill tool | No plugin loader — falls back to local frozen `figma-*` skill copies | Not part of the enforced parity axis; classification + state-shape must match, skill *inventory* does not |
+| **Pipeline commands** | 51 slash-command skills, native | 51 skills, `multi-agent-{cmd}` naming, copied in | 1 router skill (`multi-agent`) + 51 command specs as reference files - Codex silently truncates its skills block past a few dozen entries, so sub-commands are not peer skills here |
+| **Stack plugins** | Marketplace plugin, loaded natively, resolved by `.claude/settings.json` enabled-list | Enabled plugin's authored skills copied flat into `~/.copilot/skills/`; `knowledge/` **not** re-copied (already delivered via `shared/external`) | Copied as reference files under `~/.codex/multi-agent-refs/skills/`, plugin-prefixed on name clash (e.g. `architecture` → `ai-ios-toolkit-architecture`) |
+| **Component dispatch (Phase 3)** | Marketplace plugin's `create-component`/`create-screen` skill via the Skill tool | No plugin loader - the enabled stack plugin's authored skills (incl. `create-component`) are copied flat into `~/.copilot/skills/` at install time (the old frozen `figma-*` copies are pruned, they were never a fallback) | Not part of the enforced parity axis; classification + state-shape must match, skill *inventory* does not |
 | **dev-toolkit-mcp** | `claude mcp add dev-toolkit -- npx -y @mmerterden/dev-toolkit-mcp` | `copilot mcp add dev-toolkit -- npx -y @mmerterden/dev-toolkit-mcp` | `codex mcp add dev-toolkit -- npx -y @mmerterden/dev-toolkit-mcp` (skipped with a warning if `codex` isn't on `PATH`) |
 
 `smoke-cross-cli-behavior.sh` and `smoke-codex-install.sh` gate the axes that **do**
@@ -170,7 +170,7 @@ other:
 graph TD
     START["Task running: Phase 3 (Dev)"]
     START -->|"taskType !== component"| TDD["Standard TDD loop<br/>(pipeline's own code)"]
-    START -->|"taskType === component<br/>+ figmaUrl present"| VALIDATE["ai-ios-engineering-toolkit:figma-validate<br/>(registry, Code Connect, token compliance)"]
+    START -->|"taskType === component<br/>+ figmaUrl present"| VALIDATE["ai-ios-toolkit:figma-validate<br/>(registry, Code Connect, token compliance)"]
     VALIDATE -->|pass| DISPATCH["Skill tool →<br/>create-component / create-screen<br/>/ evolve-component (dual-name fallback)"]
     VALIDATE -->|fail| HALT1["halt Phase 3, surface why"]
     DISPATCH --> REPORT1["plugin returns build/test status →<br/>dispatch layer writes state.phases['3'].subphases[]"]
@@ -196,9 +196,9 @@ hard stop, per `component-dispatch.md`).
 **Phase 5 (and design-check / store-ready) → dev-toolkit** is a long-lived MCP
 session, not a one-shot call: the same stdio server process answers many tool
 calls across a phase (boot simulator once, then screenshot/tap/screenshot/tap...).
-Several pipeline skills pin a **minimum toolkit version** for a specific tool —
+Several pipeline skills pin a **minimum toolkit version** for a specific tool -
 e.g. `apple-archive-compliance` requires `ios_app_store_audit` from
-`dev-toolkit-mcp ≥ v2.9.0` — enforced in `cross-cli-contract.md` and checked by
+`dev-toolkit-mcp ≥ v2.9.0` - enforced in `cross-cli-contract.md` and checked by
 `/multi-agent:sync` Step 3d before any dev-toolkit release ships (a version bump
 that drops or renames a tool a pipeline skill depends on is a **major** bump, by
 that step's own contract).
@@ -221,8 +221,8 @@ that step's own contract).
 - **Pipeline ↔ plugins boundary = Skill tool, one direction.** The pipeline
   classifies (`taskType`, `componentScope`) and tracks state; it never reads or
   writes plugin-internal files. This is why a corporate marketplace can ship a
-  same-named plugin (`ai-ios-engineering-toolkit:create-ui-component` vs the public
-  `create-component`) and dispatch still resolves correctly — the dual-name
+  same-named plugin (`ai-ios-toolkit:create-ui-component` vs the public
+  `create-component`) and dispatch still resolves correctly - the dual-name
   fallback lives in the pipeline, the implementation stays entirely in whichever
   plugin is enabled.
 - **Pipeline ↔ dev-toolkit boundary = MCP protocol, versioned contract.** The
@@ -233,5 +233,5 @@ that step's own contract).
   contract.
 - **Neither boundary is symmetric.** The pipeline depends on both other repos being
   present *for specific task types* (component work, UI testing) but functions
-  without either — a non-component bugfix task never touches the plugin marketplace,
+  without either - a non-component bugfix task never touches the plugin marketplace,
   and a task with no UI-testing step never opens the MCP connection.

package/docs/features.md

@@ -45,14 +45,14 @@ Build commands, test runners, lint tools, and review focus areas all adapt to th
 
 ### Stack Selection (marketplace plugins)
 
-Stack skill sets ship as versioned plugins in the `multi-agent-plugins` marketplace. Selecting a stack enables the matching plugin(s) in the current repo's `.claude/settings.json` `enabledPlugins` - no skill copying, no session restart tricks, no directory shuffling. The `ai-common-engineering-toolkit` (accessibility audit, humanizer, Firebase) is always enabled alongside the stack plugin.
+Stack skill sets ship as versioned plugins in the `multi-agent-plugins` marketplace. Selecting a stack enables the matching plugin(s) in the current repo's `.claude/settings.json` `enabledPlugins` - no skill copying, no session restart tricks, no directory shuffling. The `ai-common-toolkit` (accessibility audit, humanizer, Firebase) is always enabled alongside the stack plugin.
 
 ```bash
-/multi-agent:stack ios         # ai-ios-engineering-toolkit (SwiftUI, Xcode, HIG)
-/multi-agent:stack android     # ai-android-engineering-toolkit (Compose, Gradle, Hilt)
+/multi-agent:stack ios         # ai-ios-toolkit (SwiftUI, Xcode, HIG)
+/multi-agent:stack android     # ai-android-toolkit (Compose, Gradle, Hilt)
 /multi-agent:stack mobile      # iOS + Android combined
 /multi-agent:stack backend     # ai-backend-toolkit (spec-driven APIs)
-/multi-agent:stack frontend    # ai-frontend-engineering-toolkit (React/TSX)
+/multi-agent:stack frontend    # ai-frontend-toolkit (React/TSX)
 /multi-agent:stack fullstack   # backend + frontend
 /multi-agent:stack all         # every stack plugin
 ```
@@ -273,7 +273,7 @@ Turn a recurring, project-specific job into a first-class `/multi-agent:<name>`
 
 ### Figma / Component Generation (dispatched to marketplace plugins)
 
-Component + Figma-to-code work is no longer bundled in this repo. When Phase 0 classifies a task as `component`, Phase 3 dispatches it to the per-stack marketplace plugins (`ai-ios-engineering-toolkit` / `ai-android-engineering-toolkit` in the `multi-agent-plugins` marketplace) via the Skill tool. The plugin's component skill generates `{Name}Configuration.swift`, `{Name}View.swift`, `{Name}+Modifiers.swift`, `{Name}.figma.swift`, and `FIGMA.md` with a variant matrix, then runs a 14-item pre-commit checklist covering design tokens, accessibility, tests, and Code Connect.
+Component + Figma-to-code work is no longer bundled in this repo. When Phase 0 classifies a task as `component`, Phase 3 dispatches it to the per-stack marketplace plugins (`ai-ios-toolkit` / `ai-android-toolkit` in the `multi-agent-plugins` marketplace) via the Skill tool. The plugin's component skill generates `{Name}Configuration.swift`, `{Name}View.swift`, `{Name}+Modifiers.swift`, `{Name}.figma.swift`, and `FIGMA.md` with a variant matrix, then runs a 14-item pre-commit checklist covering design tokens, accessibility, tests, and Code Connect.
 
 The plugin's cross-cutting integration skills feed component detection + implementation when the design triggers them (content: form / price / ui-patterns; interaction: navigation / overlays / bottom-sheets). Each is native-SwiftUI-first and reads project specifics (token namespaces, component paths, UI systems) from `figma-config`, including the optional `ui.navigationSystem` / `ui.overlaySystem` / `ui.sheetSystem` hooks (absent -> stock SwiftUI), so the same capabilities work on any SwiftUI codebase. The plugin's evolve-component skill reconciles an existing component against current Figma (drift-heal) and additively extends it, behind a human gate.
 

package/index.js

@@ -53,13 +53,18 @@ if (command === "--version" || command === "-v" || command === "version") {
     npx @mmerterden/multi-agent-pipeline install --codex      Install for Codex CLI
     npx @mmerterden/multi-agent-pipeline install --all        Claude + Copilot + Codex
     npx @mmerterden/multi-agent-pipeline install --link       Use symlinks (saves tokens, dev mode)
+    npx @mmerterden/multi-agent-pipeline install --dry-run    Preview what would be written, write nothing
+    npx @mmerterden/multi-agent-pipeline install --index-only Ship only the skills index (dynamic skill loading)
+    npx @mmerterden/multi-agent-pipeline install --prune-external  Also remove pre-v15 catalog copies that differ from the shipped catalog
 
   Uninstall (token-preserving - Keychain/Credential Manager untouched):
     npx @mmerterden/multi-agent-pipeline uninstall            Interactive: remove from all installed targets
     npx @mmerterden/multi-agent-pipeline uninstall --yes      Skip prompt
     npx @mmerterden/multi-agent-pipeline uninstall --dry-run  Report what would be removed
     npx @mmerterden/multi-agent-pipeline uninstall --claude   Only Claude Code
+    npx @mmerterden/multi-agent-pipeline uninstall --copilot  Only Copilot CLI
     npx @mmerterden/multi-agent-pipeline uninstall --codex    Only Codex CLI
+    npx @mmerterden/multi-agent-pipeline uninstall --all-data ALSO remove pipeline settings + logs/state/metrics
     npx @mmerterden/multi-agent-pipeline uninstall --cursor   Legacy pre-v10.7 adapter-file cleanup (also --copilot-chat / --antigravity; --target=<path> overrides cwd)
 
   Help:
@@ -68,7 +73,7 @@ if (command === "--version" || command === "-v" || command === "version") {
 
   Options:
     --no-color           Disable colored output
-    --target=<path>      Target dir for legacy adapter cleanup on uninstall (defaults to cwd)
+    --target=<path>      Target dir override (install and legacy-adapter cleanup on uninstall; defaults to cwd)
     --platform=ios|android|all   Filter external skills by platform (default: all)
 
   After installation:

package/install/_codex-agents.mjs

@@ -24,8 +24,17 @@ import { ensureDir, ensureRealDir, isDryRun, writeFile } from "./_common.mjs";
  * The pipeline's ladder is `fable -> opus -> sonnet -> haiku`. Codex offers no
  * Anthropic models, so each tier maps onto an OpenAI model plus an effort
  * setting: effort carries the depth distinction that the model id carries on
- * Claude Code. Keep this table in sync with the Codex column of the Phase 4
- * reviewer matrix and with `pipeline/scripts/cost-table.json`.
+ * Claude Code.
+ *
+ * This table resolves a persona's DEFAULT tier, which is not the same thing as
+ * a per-slot override. Phase 4 dispatches Reviewer 3 with an explicit
+ * `gpt-5.6` @ `medium` (see `phases/phase-4-review.md`, `claude-md-template.md`
+ * and `reviewer-output.schema.json`, which all state that value) even though
+ * the persona's own tier is `sonnet` and resolves here to `gpt-5.4`. That is
+ * deliberate: the Codex panel buys its diversity from effort, so two slots
+ * share a model at different efforts while a third changes model. Do not
+ * "reconcile" the two by editing either side without deciding which behavior
+ * you want, and keep this table in sync with `pipeline/scripts/cost-table.json`.
  */
 export const CODEX_TIER_MAP = Object.freeze({
   fable: { model: "gpt-5.6", reasoning_effort: "xhigh" },

package/install/_common.mjs

@@ -10,11 +10,15 @@
  */
 
 import {
+  chmodSync,
   cpSync,
   existsSync,
   lstatSync,
   mkdirSync,
+  readFileSync,
   readdirSync,
+  realpathSync,
+  renameSync,
   rmSync,
   statSync,
   symlinkSync,
@@ -87,7 +91,7 @@ export function ensureRealDir(dir) {
  * @param {string} agentsSrc - pipeline/agents source directory
  * @returns {Set<string>}
  */
-export function pipelineAgentFileNames(agentsSrc) {
+function pipelineAgentFileNames(agentsSrc) {
   const names = new Set();
   if (existsSync(agentsSrc)) {
     for (const entry of readdirSync(agentsSrc, { withFileTypes: true })) {
@@ -266,7 +270,7 @@ export function pruneLegacyMultiAgentSkills(skillsDir) {
  *
  * @type {ReadonlyArray<{dir: string, root?: "claude"|"home", reason: string}>}
  */
-export const ABANDONED_TREES = Object.freeze([
+const ABANDONED_TREES = Object.freeze([
   {
     dir: "eval",
     reason: "eval corpora; the harnesses that read them are maintainer-only and no longer ship",
@@ -279,6 +283,24 @@ export const ABANDONED_TREES = Object.freeze([
   },
 ]);
 
+/**
+ * Registry of command renames. Command names are an interface: users type
+ * them, docs and saved routines reference them, and Copilot installs derive
+ * `multi-agent-<name>` skill dirs from them. A shipped name may only ever
+ * disappear by being recorded here as `oldName: newName` - the
+ * install-lifecycle test compares the shipped tree against its committed
+ * snapshot and fails on any removal that has no rename entry, so a command
+ * cannot vanish between versions by accident.
+ *
+ * @type {Readonly<Record<string, string>>}
+ */
+export const COMMAND_RENAMES = Object.freeze({
+  delete: "uninstall",
+  // v15.0.0: "continue local work through the pipeline tail" reads as a resume
+  // variant, not a shipping action (the command opens the PR but does not merge).
+  ship: "resume-local",
+});
+
 /**
  * Remove trees an older install left behind.
  *
@@ -404,7 +426,50 @@ export function writeFile(path, content) {
     console.log(`    [dry-run] would write ${path}`);
     return;
   }
-  writeFileSync(path, content);
+  atomicWrite(path, content);
+}
+
+/**
+ * tmp + rename so a crash mid-write can never leave a truncated file behind -
+ * several call sites rewrite host config the CLI needs in order to start
+ * (`~/.claude/settings.json`, `copilot-instructions.md`).
+ *
+ * Two properties a naive rename would silently destroy on co-owned files:
+ *
+ * - **symlinks**: users keep these files in a dotfiles repo and symlink them
+ *   in. Renaming over the link replaces it with a regular file, so the
+ *   dotfiles copy goes stale and the next dotfiles apply reverts our edits.
+ *   Resolve the link first and write through it.
+ * - **mode**: a rename installs the tmp file's default 0644 over whatever the
+ *   user set (0600 on a settings file holding tokens is a real case). Carry
+ *   the existing mode across.
+ *
+ * @param {string} path
+ * @param {string} content
+ */
+export function atomicWrite(path, content) {
+  let target = path;
+  try {
+    if (lstatSync(path).isSymbolicLink()) target = realpathSync(path);
+  } catch {
+    // Missing file: nothing to preserve, write the path as given.
+  }
+  let mode;
+  try {
+    mode = statSync(target).mode & 0o777;
+  } catch {
+    mode = undefined;
+  }
+  const tmp = `${target}.tmp-${process.pid}`;
+  writeFileSync(tmp, content);
+  if (mode !== undefined) {
+    try {
+      chmodSync(tmp, mode);
+    } catch {
+      // Best effort: a failed chmod must not lose the write.
+    }
+  }
+  renameSync(tmp, target);
 }
 
 /**
@@ -457,3 +522,44 @@ export function wipeDir(dir) {
     /* non-fatal */
   }
 }
+
+
+/**
+ * @param {string} a
+ * @param {string} b
+ * @returns {boolean} true when both trees have identical entries and file bytes
+ */
+export function dirsIdentical(a, b) {
+  const namesA = readdirSync(a).sort();
+  const namesB = readdirSync(b).sort();
+  if (namesA.length !== namesB.length || namesA.some((n, i) => n !== namesB[i])) return false;
+  for (const name of namesA) {
+    const pa = join(a, name);
+    const pb = join(b, name);
+    const sa = statSync(pa);
+    const sb = statSync(pb);
+    if (sa.isDirectory() !== sb.isDirectory()) return false;
+    if (sa.isDirectory()) {
+      if (!dirsIdentical(pa, pb)) return false;
+    } else if (!readFileSync(pa).equals(readFileSync(pb))) {
+      return false;
+    }
+  }
+  return true;
+}
+
+/**
+ * Same `local-only: true` frontmatter convention the command wrappers use:
+ * a dir carrying it is the user's and no prune path may take it.
+ *
+ * @param {string} dir
+ * @returns {boolean}
+ */
+export function isLocalOnlySkill(dir) {
+  try {
+    const skill = join(dir, "SKILL.md");
+    return existsSync(skill) && /^local-only:\s*true\s*$/m.test(readFileSync(skill, "utf-8"));
+  } catch {
+    return true;
+  }
+}

package/install/_dev-only-files.mjs

@@ -64,7 +64,6 @@ const DEV_ONLY_TOOLING = Object.freeze([
   "validate-schemas.mjs", // validates the repo's own schema files, needs ajv
   "sync-parity-check.sh",
   "benchmark-phase-0.sh",
-  "test-gap-rules", // rule corpus for the repo's own test-gap gate
 ]);
 
 /** Eval harnesses (`eval-*.mjs`) read `pipeline/eval/**`, which never ships. */

package/install/_platform-filter.mjs

@@ -1,132 +1,73 @@
 /**
- * Platform classification + filtered copy for the external skill catalog.
+ * Stack partition + delivery manifest for the external skill catalog.
  *
- * The `--platform=ios|android|all` flag narrows `pipeline/skills/shared/external/`
- * to the requested platform. Generic skills always copy regardless of filter.
+ * The pre-v15 prefix classifier and its filtered-copy path
+ * (`classifyExternalSkill` / `copyExternalSkillsFiltered`) were removed once the
+ * routing table (`_stack-routing.mjs`) became the single source of stack
+ * affinity - `partitionExternalSkillsByPlugins` is what every installer uses.
  *
  * @module install/_platform-filter
  */
 
-import { readdirSync } from "fs";
+import { readdirSync, writeFileSync } from "fs";
 import { join } from "path";
-import { copyDir, countFiles, ensureDir } from "./_common.mjs";
+import { isDryRun } from "./_common.mjs";
+import { routeSkill } from "../pipeline/scripts/_stack-routing.mjs";
 
-/**
- * Heuristic prefix lists - intentionally loose so new skills added to
- * `shared/external/` are classified by name (no manifest required). A skill
- * that doesn't match either list is treated as "generic" and copies for every
- * platform.
- */
-const IOS_PREFIXES = [
-  "swift",
-  "swiftui",
-  "ios",
-  "apple",
-  "xcode",
-  "uikit",
-  "watchkit",
-  "passkit",
-  "storekit",
-  "healthkit",
-  "activitykit",
-  "weatherkit",
-  "pencilkit",
-  "callkit",
-  "eventkit",
-  "homekit",
-  "mapkit",
-  "musickit",
-  "permissionkit",
-  "speech",
-  "metrickit",
-  "widgetkit",
-  "vision",
-  "app-store",
-  "app-clips",
-  "app-intents",
-  "app-tracking",
-  "hig-",
-  "coreml",
-  "core-nfc",
-  "core-bluetooth",
-  "core-motion",
-  "cloudkit",
-  "live-activities",
-  "realitykit",
-  "tipkit",
-  "alarmkit",
-  "energykit",
-  "natural-language",
-  "authentication",
-  "background-processing",
-  "contacts",
-  "device-integrity",
-  "debugging-instruments",
-  "macos-",
-  "ios-",
-  "photos-camera",
-  "push-notifications",
-  "shareplay",
-  "apple-on-device",
-  "swiftdata",
-  "swift-",
-];
-
-const ANDROID_PREFIXES = [
-  "android",
-  "kotlin",
-  "jetpack",
-  "compose",
-  "room",
-  "retrofit",
-  "gradle",
-  "material",
-  "play-store",
-];
+/** Uninstall reads this to know exactly which external skill dirs are ours to remove. */
+export const EXTERNAL_SKILLS_MANIFEST = ".external-skills-manifest.json";
 
 /**
- * Classify an external skill directory name into its platform affinity.
+ * Enabled-stack partition of the external skill catalog.
+ *
+ * The prefix classifier above only knows ios/android/generic, so it cannot
+ * express "backend toolkit not enabled". Routing can: `routeSkill` is the same
+ * table `build-stack-plugins.mjs` ships plugins with, so filtering by it keeps
+ * a host's local copy byte-aligned with what the enabled plugins would serve on
+ * Claude Code. Unrouted skills are kept - dropping a skill no table claims
+ * would make it unreachable everywhere.
  *
- * @param {string} skillName - directory name under `shared/external/`
- * @returns {"ios" | "android" | "generic"}
+ * @param {string} externalSrc - absolute path to `pipeline/skills/shared/external/`
+ * @param {string[]} enabledPluginNames - e.g. ["ai-ios-toolkit", "ai-common-toolkit"]
+ * @returns {{ keep: string[], skipped: string[] }}
  */
-export function classifyExternalSkill(skillName) {
-  const lower = skillName.toLowerCase();
-  if (IOS_PREFIXES.some((p) => lower.startsWith(p))) return "ios";
-  if (ANDROID_PREFIXES.some((p) => lower.startsWith(p))) return "android";
-  return "generic";
+export function partitionExternalSkillsByPlugins(externalSrc, enabledPluginNames) {
+  const keep = [];
+  const skipped = [];
+  for (const e of readdirSync(externalSrc, { withFileTypes: true })) {
+    if (!e.isDirectory()) continue;
+    const plugins = routeSkill(e.name);
+    if (plugins.length === 0 || plugins.some((p) => enabledPluginNames.includes(p))) {
+      keep.push(e.name);
+    } else {
+      skipped.push(e.name);
+    }
+  }
+  return { keep, skipped };
 }
 
 /**
- * Platform-filtered copy of `shared/external/` skills.
+ * Record exactly which external skill dirs THIS install delivered.
  *
- * @param {string} externalSrc - absolute path to `pipeline/skills/shared/external/`
- * @param {string} dest - absolute path to target install dir
- * @param {{ platformFlag: "ios"|"android"|"all", useSymlinks?: boolean }} opts
- * @returns {{ copied: number, skipped: number }}
+ * Uninstall needs to remove the distributed catalog without touching
+ * user-authored skill dirs that happen to share a name. The shipped
+ * `.skills-index.json` cannot answer that: it is the full catalog, so it lists
+ * platform-filtered skills that were never installed, and a newer package's
+ * tree lists skills the installed version never shipped. Both cases would make
+ * uninstall delete a user's own directory. Same contract as
+ * `.plugin-skills-manifest.json` for plugin-delivered skills.
+ *
+ * @param {string} dest
+ * @param {string[]} names
  */
-export function copyExternalSkillsFiltered(externalSrc, dest, opts) {
-  const { platformFlag, useSymlinks = false } = opts;
-  if (platformFlag === "all") {
-    copyDir(externalSrc, dest, { useSymlinks });
-    return { copied: countFiles(externalSrc), skipped: 0 };
-  }
-
-  ensureDir(dest);
-  let copied = 0;
-  let skipped = 0;
-  for (const entry of readdirSync(externalSrc, { withFileTypes: true })) {
-    if (!entry.isDirectory()) continue;
-    const classification = classifyExternalSkill(entry.name);
-    const shouldCopy = classification === "generic" || classification === platformFlag;
-    const src = join(externalSrc, entry.name);
-    const dst = join(dest, entry.name);
-    if (shouldCopy) {
-      copyDir(src, dst, { useSymlinks });
-      copied += countFiles(src);
-    } else {
-      skipped += 1;
-    }
+export function writeExternalSkillsManifest(dest, names) {
+  if (isDryRun()) return;
+  try {
+    writeFileSync(
+      join(dest, EXTERNAL_SKILLS_MANIFEST),
+      JSON.stringify([...names].sort(), null, 2) + "\n",
+    );
+  } catch {
+    /* best-effort - a missing manifest just means uninstall falls back */
   }
-  return { copied, skipped };
 }