@mmerterden/multi-agent-pipeline 14.2.2 → 15.1.0

package/install/_plugin-skills.mjs

@@ -33,15 +33,15 @@ 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. */
-export const AUTHORED_GROUPS = Object.freeze(["index", "reference", "workflow", "tools"]);
+const AUTHORED_GROUPS = Object.freeze(["index", "reference", "workflow", "tools"]);
 
 /** 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" },
+const STACK_PLUGINS = Object.freeze([
+  { 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" },
 ]);
 
 /**
@@ -71,7 +71,7 @@ function semverCompare(a, b) {
  * @param {string} pluginName
  * @returns {{path: string, source: string}|null}
  */
-export function resolvePluginSkills(home, pluginName) {
+function resolvePluginSkills(home, pluginName) {
   const checkout = join(home, "multi-agent-plugins", "plugins", pluginName, "skills");
   if (existsSync(checkout)) return { path: checkout, source: "local checkout" };
 
@@ -104,22 +104,27 @@ export function resolvePluginSkills(home, pluginName) {
  * A flat copy of all of them is last-write-wins, so an iOS repo could end up running
  * the Android `create-component`.
  *
- * So the enabled list in Claude Code's settings is the source of truth; the
- * `--platform` flag is only the fallback for a machine that has no Claude Code
- * settings to read.
+ * So the enabled list in Claude Code's settings is the source of truth, and it is
+ * read where `/multi-agent:stack` writes it: the invoking repo's
+ * `.claude/settings.json` first, the user-global `~/.claude/settings.json` second.
+ * The `--platform` flag is only the fallback for a machine with neither.
  *
  * @param {string} home
  * @param {"ios"|"android"|"all"} platformFlag
  * @returns {{names: string[], source: string}}
  */
 export function pluginsToDeliver(home, platformFlag) {
-  const settingsPath = join(home, ".claude", "settings.json");
-  if (existsSync(settingsPath)) {
+  const candidates = [
+    { path: join(process.cwd(), ".claude", "settings.json"), label: "./.claude/settings.json" },
+    { path: join(home, ".claude", "settings.json"), label: "~/.claude/settings.json" },
+  ];
+  for (const { path: settingsPath, label } of candidates) {
+    if (!existsSync(settingsPath)) continue;
     try {
       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) {
@@ -127,10 +132,10 @@ export function pluginsToDeliver(home, platformFlag) {
         // collision the first delivery wins, and the stack-specific version is the
         // one the repo actually wants.
         const ordered = STACK_PLUGINS.map((p) => p.name).filter((n) => enabled.includes(n));
-        return { names: ordered, source: "enabledPlugins in ~/.claude/settings.json" };
+        return { names: ordered, source: `enabledPlugins in ${label}` };
       }
     } catch {
-      /* unreadable settings fall through to the platform default */
+      /* unreadable settings fall through to the next candidate */
     }
   }
   const names = STACK_PLUGINS.filter(
@@ -194,7 +199,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.
         //
@@ -263,35 +268,30 @@ export function installAuthoredPluginSkills(opts) {
   // 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");
+      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] };
-}
-
-/**
- * Names already present in a flat skills directory, so a second delivery pass does
- * not overwrite what the pipeline itself installed.
- *
- * @param {string} dir
- * @returns {Set<string>}
- */
-export function existingSkillNames(dir) {
-  if (!existsSync(dir)) return new Set();
-  return new Set(
-    readdirSync(dir, { withFileTypes: true })
-      .filter((e) => e.isDirectory())
-      .map((e) => e.name),
-  );
+  return {
+    copied,
+    collided,
+    renamed,
+    plugins,
+    missing,
+    selectionSource,
+    deliveredNames: [...delivered],
+  };
 }
 
 /**
  * Skill names the PIPELINE owns, derived from its source tree.
  *
- * This is what `skipNames` should be. Callers used to pass
- * `existingSkillNames(dest)` - a snapshot of whatever was already installed - which
+ * This is what `skipNames` should be. Callers used to pass a snapshot of
+ * whatever was already installed (a now-deleted `existingSkillNames(dest)`) - which
  * did protect pipeline skills from being shadowed by a plugin, but also meant a
  * plugin skill was copied exactly once and then frozen: on the second install its
  * own name was "already there", so it was skipped, forever. A stale plugin skill

package/install/claude.mjs

@@ -14,7 +14,7 @@
  * @module install/claude
  */
 
-import { existsSync, readFileSync, readdirSync, rmSync, statSync, writeFileSync } from "fs";
+import { existsSync, readFileSync, readdirSync, renameSync, rmSync } from "fs";
 import { join, dirname } from "path";
 import { execSync } from "child_process";
 
@@ -25,9 +25,11 @@ import {
   copyFile,
   copySkillsIndex,
   countFiles,
+  dirsIdentical,
   ensureDir,
   ensureRealDir,
   isDryRun,
+  isLocalOnlySkill,
   pruneAbandonedTrees,
   pruneLegacyMultiAgentSkills,
   pruneOrphanSkillFiles,
@@ -35,7 +37,7 @@ import {
   wipeDir,
   writeFile,
 } from "./_common.mjs";
-import { copyExternalSkillsFiltered } from "./_platform-filter.mjs";
+import { EXTERNAL_SKILLS_MANIFEST } from "./_platform-filter.mjs";
 import { DEV_ONLY_SCRIPTS, countDevOnlyFiles } from "./_dev-only-files.mjs";
 import { registerMcpServer } from "./_mcp-register.mjs";
 
@@ -46,6 +48,16 @@ import { registerMcpServer } from "./_mcp-register.mjs";
  */
 export const LEGACY_PRE_COMMIT_MATCHER = "Bash(git commit:*)";
 
+/**
+ * The only skills installed locally on Claude Code. Everything else reaches
+ * Claude Code through the marketplace plugins (`ai-<stack>-toolkit`), namespaced
+ * by the plugin loader. These two stay local by policy: they are pipeline-owned
+ * compliance catalogs that may carry audit rules not meant for the public
+ * marketplace, and `scripts/uninstall.mjs` (PIPELINE_CORE_SKILL_DIRS) already
+ * treats exactly this pair as pipeline-owned.
+ */
+export const PIPELINE_LOCAL_SKILLS = ["apple-archive-compliance", "google-play-compliance"];
+
 /**
  * @param {{
  *   home: string,
@@ -53,10 +65,11 @@ export const LEGACY_PRE_COMMIT_MATCHER = "Bash(git commit:*)";
  *   indexOnly: boolean,
  *   useSymlinks: boolean,
  *   platformFlag: "ios"|"android"|"all",
+ *   pruneExternal?: boolean,
  * }} ctx
  */
 export function installClaude(ctx) {
-  const { home, pipelineSrc, indexOnly, useSymlinks, platformFlag } = ctx;
+  const { home, pipelineSrc, indexOnly, useSymlinks, platformFlag, pruneExternal } = ctx;
 
   const CLAUDE_COMMANDS = join(home, ".claude", "commands");
   const CLAUDE_AGENTS = join(home, ".claude", "agents");
@@ -84,7 +97,7 @@ export function installClaude(ctx) {
   installSchemas(pipelineSrc, CLAUDE_SCHEMAS, useSymlinks);
   installLib(pipelineSrc, CLAUDE_LIB, useSymlinks);
   runPreDeployScans(pipelineSrc);
-  installSkills({ pipelineSrc, dest: CLAUDE_SKILLS, indexOnly, useSymlinks, platformFlag });
+  installSkills({ pipelineSrc, dest: CLAUDE_SKILLS, indexOnly, useSymlinks, platformFlag, pruneExternal });
   ensureClaudeMd(home, pipelineSrc);
   ensurePreferences(PREFS_PATH, pipelineSrc);
   configureSettings(home);
@@ -128,13 +141,16 @@ function installCommands(pipelineSrc, dest, useSymlinks) {
   //
   // Preserve local-only alias wrappers (frontmatter `local-only: true`) across
   // the wipe. They live ONLY under ~/.claude (never in pipeline/commands, and
-  // never synced), so without this snapshot+restore they would be destroyed on
-  // every install/update. Pipeline never ships these names, so restore is safe.
-  const preservedWrappers = snapshotLocalOnlyWrappers(ownedCmdDir);
+  // never synced), so without this stash+restore they would be destroyed on
+  // every install/update. The stash is an on-disk rename, not an in-memory
+  // snapshot: the only copy of user-authored content stays on disk at every
+  // instant, so an install interrupted between wipe and restore loses nothing,
+  // and the next run adopts any leftover stash.
+  const wrapperStash = stashLocalOnlyWrappers(ownedCmdDir);
   wipeDir(ownedCmdDir);
 
   copyDir(commandsSrc, dest, { useSymlinks });
-  const restored = restoreLocalOnlyWrappers(ownedCmdDir, preservedWrappers);
+  const restored = unstashLocalOnlyWrappers(ownedCmdDir, wrapperStash);
   console.log(`    -> ${countFiles(commandsSrc)} files copied to ${dest}`);
   if (restored > 0) {
     console.log(`    -> preserved ${restored} local-only alias wrapper(s)`);
@@ -163,36 +179,51 @@ function localizeCommandDescriptions(pipelineSrc, ownedCmdDir) {
   }
 }
 
-// Snapshot single-level command dirs whose SKILL.md declares `local-only: true`
-// (their files are read into memory) so installCommands can restore them after
-// the namespace wipe.
-function snapshotLocalOnlyWrappers(ownedCmdDir) {
-  const out = [];
-  if (!existsSync(ownedCmdDir)) return out;
+// Move command dirs whose SKILL.md declares `local-only: true` into an on-disk
+// stash beside the namespace, so installCommands can restore them after the
+// namespace wipe. Returns the stash path.
+function stashLocalOnlyWrappers(ownedCmdDir) {
+  const stashDir = join(dirname(ownedCmdDir), ".multi-agent-wrapper-stash");
+  if (isDryRun() || !existsSync(ownedCmdDir)) return stashDir;
   for (const name of readdirSync(ownedCmdDir)) {
     const dir = join(ownedCmdDir, name);
     const skill = join(dir, "SKILL.md");
     if (!existsSync(skill)) continue;
     if (!/^local-only:\s*true\s*$/m.test(readFileSync(skill, "utf-8"))) continue;
-    const files = readdirSync(dir)
-      .filter((f) => statSync(join(dir, f)).isFile())
-      .map((f) => ({ rel: f, content: readFileSync(join(dir, f), "utf-8") }));
-    out.push({ name, files });
+    ensureDir(stashDir);
+    const target = join(stashDir, name);
+    if (existsSync(target)) rmSync(target, { recursive: true, force: true });
+    renameSync(dir, target);
   }
-  return out;
+  return stashDir;
 }
 
-// Restore snapshotted local-only wrappers, but never clobber a real command the
-// pipeline just installed under the same name. Returns the count restored.
-function restoreLocalOnlyWrappers(ownedCmdDir, preserved) {
+// Restore stashed local-only wrappers (including any leftover from an earlier
+// interrupted run), but never clobber a real command the pipeline just
+// installed under the same name. Returns the count restored.
+function unstashLocalOnlyWrappers(ownedCmdDir, stashDir) {
+  if (isDryRun() || !existsSync(stashDir)) return 0;
   let n = 0;
-  for (const w of preserved) {
-    const dir = join(ownedCmdDir, w.name);
-    if (existsSync(dir)) continue; // pipeline shipped a real command with this name
-    ensureDir(dir);
-    for (const f of w.files) writeFileSync(join(dir, f.rel), f.content);
+  for (const name of readdirSync(stashDir)) {
+    const from = join(stashDir, name);
+    const to = join(ownedCmdDir, name);
+    if (existsSync(to)) {
+      // The pipeline now ships a real command under a name the user's wrapper
+      // was using, so the wrapper cannot be restored. Say whose content is
+      // being dropped: /multi-agent:save writes exactly these, and a release
+      // claiming a new name would otherwise delete a saved routine in silence.
+      console.log(
+        `    -> WARNING: dropped local-only wrapper '${name}' - this release ships a command ` +
+          `with that name. Re-save it under a different name if you still need it.`,
+      );
+      rmSync(from, { recursive: true, force: true });
+      continue;
+    }
+    ensureDir(ownedCmdDir);
+    renameSync(from, to);
     n++;
   }
+  rmSync(stashDir, { recursive: true, force: true });
   return n;
 }
 
@@ -327,7 +358,7 @@ function runPreDeployScans(pipelineSrc) {
 }
 
 function installSkills(opts) {
-  const { pipelineSrc, dest, indexOnly, useSymlinks, platformFlag } = opts;
+  const { pipelineSrc, dest, indexOnly, useSymlinks, pruneExternal } = opts;
   console.log("  [Claude Code] Installing skills...");
 
   // Same symlink guard as the other owned trees: never prune or copy through
@@ -343,40 +374,57 @@ function installSkills(opts) {
   }
 
   const sharedCoreSrc = join(pipelineSrc, "skills", "shared", "core");
-  const sharedExternalSrc = join(pipelineSrc, "skills", "shared", "external");
 
   let claudeSkillCount = 0;
 
-  if (existsSync(sharedCoreSrc)) {
-    copyDir(sharedCoreSrc, dest, { useSymlinks });
-    claudeSkillCount += countFiles(sharedCoreSrc);
+  // Claude Code no longer receives a local copy of the stack skills. The
+  // marketplace plugins (`ai-<stack>-toolkit`) are its only stack-skill source -
+  // a local copy duplicated ~110 skills against the enabled plugins (~10k
+  // tokens/session) and shadowed the plugin the moment it went stale. Only the
+  // two pipeline-owned compliance catalogs stay local (PIPELINE_LOCAL_SKILLS);
+  // they are deliberately not published to the marketplace.
+  ensureDir(dest);
+  for (const name of PIPELINE_LOCAL_SKILLS) {
+    const from = join(sharedCoreSrc, name);
+    if (!existsSync(from)) continue;
+    if (!useSymlinks) wipeDir(join(dest, name));
+    copyDir(from, join(dest, name), { useSymlinks });
+    claudeSkillCount += countFiles(from);
   }
 
-  if (existsSync(sharedExternalSrc)) {
-    const { copied, skipped } = copyExternalSkillsFiltered(sharedExternalSrc, dest, {
-      platformFlag,
-      useSymlinks,
-    });
-    claudeSkillCount += copied;
-    if (skipped > 0) {
-      console.log(
-        `    -> --platform=${platformFlag} filter skipped ${skipped} external skill dir(s)`,
-      );
-    }
+  // Single-standard enforcement: Claude Code invokes pipeline commands via
+  // the `/multi-agent:*` slash-command namespace, so prune duplicate skill
+  // dirs left by older installs that copied shared/core wholesale. This used
+  // to live inside the external-copy branch; it must run unconditionally or
+  // the 51 multi-agent-* dirs return on the first install after a migration.
+  const pruned = pruneLegacyMultiAgentSkills(dest);
+  if (pruned > 0) {
+    console.log(
+      `    -> pruned ${pruned} legacy multi-agent-* skill dirs (slash commands cover these)`,
+    );
+  }
 
-    // Single-standard enforcement: Claude Code invokes pipeline commands via
-    // the `/multi-agent:*` slash-command namespace, so prune duplicate skill
-    // dirs that come from the shared/external/ tree.
-    const pruned = pruneLegacyMultiAgentSkills(dest);
-    if (pruned > 0) {
-      claudeSkillCount -= pruned;
-      console.log(
-        `    -> pruned ${pruned} legacy multi-agent-* skill dirs (slash commands cover these)`,
-      );
-    }
+  // Migration prune: an older install delivered the full external catalog here.
+  // Its manifest names exactly what was delivered, so removal is manifest-scoped -
+  // user-authored skills in the same directory are untouched.
+  const migrated = pruneManifestDeliveredSkills(dest);
+  if (migrated > 0) {
+    console.log(
+      `    -> migration: removed ${migrated} stack skill dir(s) previously copied here (now plugin-only)`,
+    );
   }
 
-  // Figma component skills moved to the ai-<platform>-engineering-toolkit marketplace
+  // Pre-manifest installs (<= v14.x) never wrote that manifest, so the branch
+  // above cannot fire for them and the full 151-dir catalog would outlive every
+  // upgrade. For those, prune by proof instead of by name: a dir byte-identical
+  // to the shipped catalog contains nothing of the user's and goes now; a dir
+  // that differs is kept unless --prune-external explicitly opts in (and even
+  // then a `local-only: true` SKILL.md keeps it).
+  migratePreManifestExternalSkills(dest, join(pipelineSrc, "skills", "shared", "external"), {
+    pruneExternal: Boolean(pruneExternal),
+  });
+
+  // Figma component skills moved to the ai-<platform>-toolkit marketplace
   // plugin and are no longer bundled here. Prune any stale copies left by a
   // pre-migration install so the installed tree stays consistent.
   for (const sub of ["figma-ios", "figma-android", "figma-common", "figma-to-component"]) {
@@ -410,21 +458,163 @@ function installSkills(opts) {
     console.log(`    -> pruned ${orphans} stale flat skill file(s) from an older layout`);
   }
 
-  console.log(`    -> ${claudeSkillCount} skill files installed to ${dest}`);
+  console.log(`    -> ${claudeSkillCount} skill files installed to ${dest} (stack skills: marketplace plugins)`);
 
-  // Keep the shared skills index README in sync.
-  const sharedReadmeSrc = join(pipelineSrc, "skills", "shared", "README.md");
-  if (existsSync(sharedReadmeSrc)) {
-    const claudeReadme = join(dest, "README.md");
+  // The shared skills README described the full local catalog; with the catalog
+  // gone it would document skills that are not here. Drop it, including copies
+  // an older install left behind.
+  const claudeReadme = join(dest, "README.md");
+  if (existsSync(claudeReadme) && !isDryRun()) {
     try {
-      copyFile(sharedReadmeSrc, claudeReadme);
-      console.log(`    -> updated ${claudeReadme}`);
+      rmSync(claudeReadme);
+      console.log(`    -> removed ${claudeReadme} (local catalog no longer installed)`);
     } catch {
       /* non-fatal */
     }
   }
 }
 
+/**
+ * Remove the external stack skills an older install copied into `dest`, scoped
+ * strictly to the delivery manifest that install wrote. NOTICE files rode along
+ * with the external catalog, so they go with it.
+ *
+ * @param {string} dest - the installed skills directory
+ * @returns {number} directories removed
+ */
+function pruneManifestDeliveredSkills(dest) {
+  const manifestPath = join(dest, EXTERNAL_SKILLS_MANIFEST);
+  if (!existsSync(manifestPath)) return 0;
+  if (isDryRun()) {
+    console.log(`    [dry-run] would remove externally-delivered skills named in ${manifestPath}`);
+    return 0;
+  }
+  let removed = 0;
+  try {
+    const names = JSON.parse(readFileSync(manifestPath, "utf-8"));
+    for (const name of Array.isArray(names) ? names : []) {
+      // The manifest is untrusted input feeding a recursive rmSync: a name
+      // carrying a path separator or leading dot would escape the skills dir
+      // (join normalizes "../x"), so only plain directory names pass.
+      if (typeof name !== "string" || /[/\\]/.test(name) || name.startsWith(".")) continue;
+      // The two local compliance catalogs are never external-delivered, but a
+      // corrupted manifest must not be able to take them out.
+      if (PIPELINE_LOCAL_SKILLS.includes(name)) continue;
+      const dir = join(dest, name);
+      if (!existsSync(dir)) continue;
+      try {
+        rmSync(dir, { recursive: true, force: true });
+        removed++;
+      } catch {
+        /* non-fatal */
+      }
+    }
+    for (const entry of readdirSync(dest)) {
+      if (entry.startsWith("NOTICE-") && entry.endsWith(".md")) {
+        try {
+          rmSync(join(dest, entry));
+        } catch {
+          /* non-fatal */
+        }
+      }
+    }
+    rmSync(manifestPath, { force: true });
+  } catch {
+    /* unreadable manifest: leave everything in place rather than guess */
+  }
+  return removed;
+}
+
+/**
+ * Migration for pre-manifest installs (<= v14.x): the external catalog was
+ * copied here with no delivery manifest, so ours and the user's are told apart
+ * by content, not by name. Byte-identical to the shipped catalog = provably
+ * ours, removed. Different = kept, reported, and removable only via the
+ * explicit `--prune-external` flag (which still honors `local-only: true`).
+ *
+ * @param {string} dest - the installed skills directory
+ * @param {string} externalSrc - absolute path to `pipeline/skills/shared/external/`
+ * @param {{ pruneExternal: boolean }} opts
+ */
+function migratePreManifestExternalSkills(dest, externalSrc, opts) {
+  if (!existsSync(externalSrc) || !existsSync(dest)) return;
+  const { pruneExternal } = opts;
+  let identical = 0;
+  let flagged = 0;
+  const leftover = [];
+  for (const entry of readdirSync(externalSrc, { withFileTypes: true })) {
+    const name = entry.name;
+    if (PIPELINE_LOCAL_SKILLS.includes(name)) continue;
+    const stale = join(dest, name);
+    if (!existsSync(stale)) continue;
+
+    // NOTICE-*.md files rode along with the catalog as plain files.
+    if (!entry.isDirectory()) {
+      if (!/^NOTICE-.*\.md$/.test(name)) continue;
+      if (isDryRun()) {
+        console.log(`    [dry-run] would prune stale ${name} (pre-manifest catalog copy)`);
+        continue;
+      }
+      try {
+        rmSync(stale, { force: true });
+        identical++;
+      } catch {
+        /* non-fatal */
+      }
+      continue;
+    }
+
+    let provablyOurs;
+    try {
+      provablyOurs = dirsIdentical(join(externalSrc, name), stale);
+    } catch {
+      provablyOurs = false;
+    }
+    if (provablyOurs) {
+      if (isDryRun()) {
+        console.log(`    [dry-run] would prune ${name}/ (identical to shipped catalog)`);
+        identical++;
+        continue;
+      }
+      try {
+        rmSync(stale, { recursive: true, force: true });
+        identical++;
+      } catch {
+        /* non-fatal */
+      }
+    } else if (pruneExternal && !isLocalOnlySkill(stale)) {
+      if (isDryRun()) {
+        console.log(`    [dry-run] would prune ${name}/ (--prune-external)`);
+        flagged++;
+        continue;
+      }
+      try {
+        rmSync(stale, { recursive: true, force: true });
+        flagged++;
+      } catch {
+        /* non-fatal */
+      }
+    } else {
+      leftover.push(name);
+    }
+  }
+  if (identical > 0) {
+    console.log(
+      `    -> migration: pruned ${identical} pre-manifest catalog entr(ies) identical to the shipped catalog (now plugin-only)`,
+    );
+  }
+  if (flagged > 0) {
+    console.log(`    -> --prune-external: removed ${flagged} catalog-named skill dir(s) that had local differences`);
+  }
+  if (leftover.length > 0) {
+    console.log(
+      `    note: ${leftover.length} skill dir(s) share catalog names but differ from the shipped catalog - kept ` +
+        `(cannot tell an older delivery from user edits). Remove them too with: node install.js --claude --prune-external`,
+    );
+  }
+}
+
+
 function ensureClaudeMd(home, pipelineSrc) {
   console.log("  [Claude Code] Checking CLAUDE.md template...");
   const CLAUDE_MD = join(home, ".claude", "CLAUDE.md");

package/install/codex.mjs

@@ -34,7 +34,15 @@ import {
 import { DEV_ONLY_SCRIPTS, countDevOnlyFiles } from "./_dev-only-files.mjs";
 import { registerMcpServer } from "./_mcp-register.mjs";
 import { installCodexAgents } from "./_codex-agents.mjs";
-import { installAuthoredPluginSkills, pipelineOwnedSkillNames } from "./_plugin-skills.mjs";
+import {
+  installAuthoredPluginSkills,
+  pipelineOwnedSkillNames,
+  pluginsToDeliver,
+} from "./_plugin-skills.mjs";
+import {
+  partitionExternalSkillsByPlugins,
+  writeExternalSkillsManifest,
+} from "./_platform-filter.mjs";
 import { generateCodexInstructions } from "./_codex-instructions.mjs";
 import { mergeManagedBlock } from "./_managed-block.mjs";
 
@@ -44,9 +52,6 @@ export const AGENTS_MD_START_MARKER = "# Multi-Agent Development Pipeline";
 /** Explicit end marker written after the pipeline section. */
 export const AGENTS_MD_END_MARKER = "<!-- multi-agent-pipeline:codex-instructions:end -->";
 
-/** Re-exported for the uninstaller and the Codex install smoke. */
-export { MCP_SERVER_NAME } from "./_mcp-register.mjs";
-
 /**
  * `$HOME/.claude/...` path rewrites applied to every file installed into the
  * Codex tree.
@@ -269,7 +274,7 @@ function pruneLegacyCommandSkills(skillsDir) {
 }
 
 /**
- * Install the reference tree: the shared `multi-agent-refs/` docs plus the 42
+ * Install the reference tree: the shared `multi-agent-refs/` docs plus every
  * sub-command specs, all path-rewritten. These are read on demand and never
  * enter the skills block.
  */
@@ -394,7 +399,24 @@ function installSkillRefs(pipelineSrc, dest, home, platformFlag) {
   wipeDir(dest);
 
   let count = 0;
-  if (existsSync(externalSrc)) count += copyTreeRewritten(externalSrc, dest);
+  if (existsSync(externalSrc)) {
+    // Active-stack filter (same contract as Copilot): Codex used to receive all
+    // 151 external skills regardless of stack - platformFlag only shaped the
+    // authored-plugin delivery below. The enabled-plugin set from
+    // ~/.claude/settings.json now bounds this copy too, so a Claude+Codex user
+    // sees one consistent stack surface across both hosts. The manifest makes
+    // the delivery inspectable; the wholesale wipeDir above already handles
+    // staleness on every install.
+    const { names: enabled, source: selectionSource } = pluginsToDeliver(home, platformFlag);
+    const { keep, skipped } = partitionExternalSkillsByPlugins(externalSrc, enabled);
+    for (const name of keep) {
+      count += copyTreeRewritten(join(externalSrc, name), join(dest, name));
+    }
+    writeExternalSkillsManifest(dest, keep);
+    console.log(
+      `    -> stack filter (${selectionSource}): ${keep.length} kept, ${skipped.length} skipped`,
+    );
+  }
 
   // `shared/core` also holds two skills that are NOT pipeline sub-commands:
   // apple-archive-compliance and google-play-compliance. Copying only `external`