@mmerterden/multi-agent-pipeline 14.2.2 → 15.0.0

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

@@ -37,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" },
 ]);
 
 /**
@@ -119,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) {
@@ -194,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.
         //
@@ -263,12 +263,23 @@ 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] };
+  return {
+    copied,
+    collided,
+    renamed,
+    plugins,
+    missing,
+    selectionSource,
+    deliveredNames: [...delivered],
+  };
 }
 
 /**

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";
 
@@ -35,7 +35,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 +46,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,
@@ -128,13 +138,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 +176,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 +355,7 @@ function runPreDeployScans(pipelineSrc) {
 }
 
 function installSkills(opts) {
-  const { pipelineSrc, dest, indexOnly, useSymlinks, platformFlag } = opts;
+  const { pipelineSrc, dest, indexOnly, useSymlinks } = opts;
   console.log("  [Claude Code] Installing skills...");
 
   // Same symlink guard as the other owned trees: never prune or copy through
@@ -343,40 +371,49 @@ 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. Without a manifest
+  // nothing is guessed; the stale copy then outlives this install and the user
+  // can clean it via uninstall --claude.
+  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
+  // 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 +447,69 @@ 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 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;
+}
+
 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";
 
@@ -269,7 +277,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 +402,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`