@mmerterden/multi-agent-pipeline 14.2.1 → 15.0.0

package/docs/ecosystem.md

@@ -0,0 +1,237 @@
+# Ecosystem: Pipeline × Marketplace Plugins × Dev-Toolkit MCP
+
+This pipeline is not one repo. It's three, each owned separately, each versioned
+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 50 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 |
+
+None of the three depends on the others at the code level. They compose through two
+narrow contracts: the **Skill tool** (pipeline → plugin, at Phase 3) and the **MCP
+protocol** (pipeline skills → dev-toolkit, at Phase 5 / design-check / store-ready).
+Either can be swapped or removed without touching the other two's source.
+
+```mermaid
+graph LR
+    subgraph PIPE ["multi-agent-pipeline (orchestrator)"]
+        direction TB
+        PHASES["8 phases · 50 commands"]
+        GATES["deterministic gates + review triage"]
+    end
+
+    subgraph PLUG ["multi-agent-plugins (stack knowledge)"]
+        direction TB
+        IOSP["ai-ios-toolkit"]
+        ANDP["ai-android-toolkit"]
+        FEP["ai-frontend-toolkit"]
+        BEP["ai-backend-toolkit"]
+        COMP["ai-common-toolkit"]
+    end
+
+    subgraph DTK ["dev-toolkit-mcp (device/browser hands)"]
+        direction TB
+        DEV["Device Control (58)"]
+        A11Y["Accessibility Audit (2)"]
+        STORE["Store Compliance (5)"]
+        WEB["Web Automation (8)"]
+        DESIGN["Design Audit (6)"]
+        AGENTDSL["Agent DSL (1)"]
+    end
+
+    PHASES -->|"Phase 3: Skill tool<br/>taskType===component"| PLUG
+    PHASES -->|"Phase 5 / design-check /<br/>store-ready: MCP tool calls"| DTK
+    GATES -.->|"Phase 4 Security Auditor"| STORE
+
+    style PIPE fill:#ffd,stroke:#333
+    style PLUG fill:#dfd,stroke:#333
+    style DTK fill:#dff,stroke:#333
+```
+
+---
+
+## 1. Authoring flow: one source of truth, five sync targets
+
+`~/.claude/` on the maintainer's machine is authoritative. Everything else is a
+derived, synced, or independently-shipped artifact. `/multi-agent:sync` is the one
+command that walks all five targets in order, detects which are stale, and updates
+only those:
+
+```mermaid
+graph TD
+    CC["Claude Code<br/>~/.claude/commands/multi-agent/<br/>(source of truth)"]
+
+    CC -->|"Step 2: copy + reformat<br/>50 sub-command skills"| COP["Copilot CLI<br/>~/.copilot/skills/"]
+    CC -->|"Step 2b: transform<br/>(install.js --codex)"| COD["Codex CLI<br/>1 router skill + 50 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"]
+
+    REPO -->|"Step 3c: build-stack-plugins.mjs<br/>rebuilds knowledge/ from<br/>shared/external"| PLUGREPO["multi-agent-plugins repo<br/>(5 stack plugins)"]
+
+    DTK2["dev-toolkit-mcp repo<br/>(own codebase, own gates,<br/>NOT generated from Claude)"]
+    SYNC3D["Step 3d: detect movement →<br/>gate → commit → publish"]
+    CC -.->|"sync only SHIPS this,<br/>never authors it"| SYNC3D
+    SYNC3D -.-> DTK2
+
+    REPO -->|"npm publish"| NPM["GitHub Packages"]
+    WEB -->|"git push → auto-deploy"| VERCEL["Vercel"]
+    PLUGREPO -->|"git push"| MKT["Claude Code marketplace"]
+    DTK2 -->|"npm publish"| NPM2["GitHub Packages<br/>(private)"]
+
+    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:
+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
+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 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
+hand-authored *inside* `multi-agent-plugins` and are never touched by sync.
+
+---
+
+## 2. Plugin marketplace build: one authoring source, five versioned artifacts
+
+```mermaid
+graph TD
+    EXT["pipeline/skills/shared/external/<br/>150 skills - single authoring source<br/>(the pipeline's own phases read these too)"]
+
+    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-toolkit<br/>24 skills · v0.1.3"]
+
+    COMMONP --> BUMP{"skill set<br/>changed?"}
+    IOSP --> BUMP
+    ANDP --> BUMP
+    BEP --> BUMP
+    FEP --> BUMP
+    BUMP -->|yes| PATCH["bump that plugin's<br/>patch version"]
+    BUMP -->|no| SKIP["idempotent no-op"]
+
+    PATCH --> CONSUMER["/multi-agent:update<br/>→ claude marketplace update multi-agent-plugins"]
+
+    style EXT fill:#ffd,stroke:#333
+```
+
+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
+`knowledge/`, not deduplicated across them. Versioning is per-plugin and
+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
+(`/multi-agent:stack ios`, writing the enabled-plugins list into
+`.claude/settings.json`) and picks up new plugin versions only when it runs
+`/multi-agent:update`, which calls `claude marketplace update multi-agent-plugins`.
+Publishing a new plugin version does not retroactively change anything already
+running in a consumer's session.
+
+---
+
+## 3. Per-host delivery: the same three repos, three different shapes
+
+The three repos land differently on each host, because each host's skill-loading
+behavior is different (see `pipeline/multi-agent-refs/cross-cli-contract.md` for the
+measurements behind this table):
+
+| | Claude Code | Copilot CLI | Codex CLI |
+|---|---|---|---|
+| **Pipeline commands** | 50 slash-command skills, native | 50 skills, `multi-agent-{cmd}` naming, copied in | 1 router skill (`multi-agent`) + 50 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 - falls back to local frozen `figma-*` skill copies | 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**
+have to match (phase labels, placeholder vocabulary, output schemas, command↔skill
+parity count); the table above marks the axes that are allowed to diverge by design.
+
+---
+
+## 4. Runtime: what actually happens during a task
+
+Two independent hand-offs happen inside a single pipeline run, neither aware of the
+other:
+
+```mermaid
+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-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[]"]
+
+    REPORT1 --> P4["Phase 4: Review"]
+    P4 --> P5["Phase 5: Test"]
+
+    P5 -->|"UI bug hunt / manual-test /<br/>design-check / store-ready"| MCP["MCP tool call over stdio<br/>e.g. ios_xcodebuild, design_visual_compare,<br/>ios_app_store_audit"]
+    MCP --> DTKPROC["dev-toolkit-mcp process<br/>(npx @mmerterden/dev-toolkit-mcp)"]
+    DTKPROC -->|"result: screenshot / xcresult ID /<br/>18-rule audit verdict"| P5
+
+    style DISPATCH fill:#dfd,stroke:#333
+    style MCP fill:#dff,stroke:#333
+    style HALT1 fill:#fdd,stroke:#333
+```
+
+**Phase 3 → plugin** is a one-shot delegation: the plugin skill does its own
+lifecycle (test → code → build → wiki) and reports back a coarse
+`component-build` result; the pipeline does not re-implement any of that logic, and
+a plugin failure counts against the pipeline's own retry cap (`retryCount === 3` →
+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 -
+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
+`/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).
+
+### dev-toolkit-mcp's 80 tools, by category
+
+| Category | Tools | Primary pipeline consumers |
+|---|---|---|
+| Device Control | 58 | `/multi-agent:test`, `test-dark-mode`, `test-accessibility`, `test-dynamic-type`, `test-screenshots`, `manual-test`, `design-check` |
+| Accessibility Audit | 2 | `test-accessibility` |
+| Store Compliance | 5 | `store-ready`, `testflight-validation`, `apple-archive-compliance` skill, Phase 4 Security Auditor |
+| Web Automation | 8 | frontend-stack UI testing (via `test`) |
+| Design Audit | 6 | `design-check` (mock-mode vs Figma conformance) |
+| Autonomous Agent DSL | 1 | any skill that needs a scripted multi-step device flow in one round trip |
+
+---
+
+## 5. Why the boundary is drawn where it is
+
+- **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-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
+  pipeline never shells out to `xcrun simctl` or `adb` directly; every device/browser
+  action is a declared MCP tool call with a minimum-version pin. That's what lets
+  `dev-toolkit-mcp` ship on its own release cadence (its own gates, its own
+  `npm publish`) without a pipeline release, as long as pinned tools keep their
+  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,
+  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

@@ -59,7 +59,9 @@ if (command === "--version" || command === "-v" || command === "version") {
     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:

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,14 @@
  */
 
 import {
+  chmodSync,
   cpSync,
   existsSync,
   lstatSync,
   mkdirSync,
   readdirSync,
+  realpathSync,
+  renameSync,
   rmSync,
   statSync,
   symlinkSync,
@@ -279,6 +282,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 +425,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);
 }
 
 /**

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

@@ -7,9 +7,13 @@
  * @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 { copyDir, countFiles, ensureDir, isDryRun } from "./_common.mjs";
+import { routeSkill } from "../pipeline/scripts/_stack-routing.mjs";
+
+/** Uninstall reads this to know exactly which external skill dirs are ours to remove. */
+export const EXTERNAL_SKILLS_MANIFEST = ".external-skills-manifest.json";
 
 /**
  * Heuristic prefix lists - intentionally loose so new skills added to
@@ -107,26 +111,88 @@ export function classifyExternalSkill(skillName) {
  */
 export function copyExternalSkillsFiltered(externalSrc, dest, opts) {
   const { platformFlag, useSymlinks = false } = opts;
+  const allNames = readdirSync(externalSrc, { withFileTypes: true })
+    .filter((e) => e.isDirectory())
+    .map((e) => e.name);
+
   if (platformFlag === "all") {
     copyDir(externalSrc, dest, { useSymlinks });
+    writeExternalSkillsManifest(dest, allNames);
     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 delivered = [];
+  for (const name of allNames) {
+    const classification = classifyExternalSkill(name);
     const shouldCopy = classification === "generic" || classification === platformFlag;
-    const src = join(externalSrc, entry.name);
-    const dst = join(dest, entry.name);
+    const src = join(externalSrc, name);
+    const dst = join(dest, name);
     if (shouldCopy) {
       copyDir(src, dst, { useSymlinks });
       copied += countFiles(src);
+      delivered.push(name);
     } else {
       skipped += 1;
     }
   }
+  writeExternalSkillsManifest(dest, delivered);
   return { copied, skipped };
 }
+
+/**
+ * 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} 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 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 };
+}
+
+/**
+ * Record exactly which external skill dirs THIS install delivered.
+ *
+ * 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 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 */
+  }
+}

package/install/_plugin-skills.mjs

@@ -24,9 +24,12 @@
  * @module install/_plugin-skills
  */
 
-import { existsSync, readFileSync, readdirSync, statSync } from "fs";
+import { existsSync, readFileSync, readdirSync, statSync, writeFileSync } from "fs";
 import { join } from "path";
 
+/** Uninstall reads this to know exactly which delivered skill dirs are ours to remove. */
+export const PLUGIN_SKILLS_MANIFEST = ".plugin-skills-manifest.json";
+
 import { copyDir, countFiles, ensureDir, ensureRealDir, isDryRun, wipeDir } from "./_common.mjs";
 
 /** Subtrees a plugin authors itself. `knowledge/` is generated, so it is excluded. */
@@ -34,11 +37,11 @@ export const AUTHORED_GROUPS = Object.freeze(["index", "reference", "workflow",
 
 /** Stack plugins, and the platform each belongs to. */
 export const STACK_PLUGINS = Object.freeze([
-  { name: "ai-ios-engineering-toolkit", platform: "ios" },
-  { name: "ai-android-engineering-toolkit", platform: "android" },
-  { name: "ai-frontend-engineering-toolkit", platform: "all" },
+  { name: "ai-ios-toolkit", platform: "ios" },
+  { name: "ai-android-toolkit", platform: "android" },
+  { name: "ai-frontend-toolkit", platform: "all" },
   { name: "ai-backend-toolkit", platform: "all" },
-  { name: "ai-common-engineering-toolkit", platform: "all" },
+  { name: "ai-common-toolkit", platform: "all" },
 ]);
 
 /**
@@ -116,7 +119,7 @@ export function pluginsToDeliver(home, platformFlag) {
       const settings = JSON.parse(readFileSync(settingsPath, "utf-8"));
       const enabled = Object.entries(settings.enabledPlugins || {})
         .filter(([, on]) => on === true)
-        // keys look like `ai-ios-engineering-toolkit@multi-agent-plugins`
+        // keys look like `ai-ios-toolkit@multi-agent-plugins`
         .map(([k]) => k.split("@")[0])
         .filter((n) => STACK_PLUGINS.some((p) => p.name === n));
       if (enabled.length > 0) {
@@ -191,7 +194,7 @@ export function installAuthoredPluginSkills(opts) {
         // That is not a duplicate: the pipeline's `architecture` is a generic ADR
         // framework while the iOS plugin's is that stack's structural rules, and the
         // same holds for `backlog`. Claude Code reaches both because its loader
-        // namespaces plugin skills (`ai-ios-engineering-toolkit:architecture`); the
+        // namespaces plugin skills (`ai-ios-toolkit:architecture`); the
         // copy hosts had no namespace, so the stack-specific version was silently
         // unreachable on exactly the repos that need it most.
         //
@@ -254,7 +257,29 @@ export function installAuthoredPluginSkills(opts) {
         `clone {owner}/multi-agent-plugins or enable them in Claude Code to deliver their skills`,
     );
   }
-  return { copied, collided, renamed, plugins, missing, selectionSource };
+  // Uninstall has no way to know which of ~100 flat skill dirs came from a
+  // plugin delivery pass rather than the pipeline's own PIPELINE_CORE_SKILL_DIRS
+  // allowlist - it silently left all of them behind. Persist exactly the names
+  // this pass delivered so uninstall can remove precisely those, nothing more.
+  if (!isDryRun()) {
+    try {
+      writeFileSync(
+        join(dest, PLUGIN_SKILLS_MANIFEST),
+        JSON.stringify([...delivered], null, 2) + "\n",
+      );
+    } catch {
+      /* best-effort - a missing manifest just means uninstall skips this cleanup */
+    }
+  }
+  return {
+    copied,
+    collided,
+    renamed,
+    plugins,
+    missing,
+    selectionSource,
+    deliveredNames: [...delivered],
+  };
 }
 
 /**