@mmerterden/multi-agent-pipeline 13.2.0 → 13.3.0

package/CHANGELOG.md

@@ -16,6 +16,56 @@ Internal file-layout changes that don't affect the slash-command surface are sti
 
 ## [Unreleased]
 
+## [13.3.0] - 2026-07-28
+
+### Added
+
+- **Copilot CLI and Codex CLI now carry the stack plugin's authored skills.** Claude Code
+  loads `multi-agent-plugins` natively; the other two hosts could not, and the contract
+  papered over it by claiming Copilot kept standalone `figma-*` copies as a "frozen
+  fallback". `install/copilot.mjs` pruned exactly those directories, so Copilot had
+  **zero** plugin-authored skills: `create-screen`, `figma-validate`, `figma-review`,
+  `component`, `state` and `navigation` were all absent, and a component task on Copilot
+  had nothing to dispatch to. New shared `install/_plugin-skills.mjs` delivers the
+  `index` / `reference` / `workflow` / `tools` groups to both hosts - as skills on
+  Copilot, as reference files on Codex, where the skills block truncates silently.
+- Plugin selection reads `enabledPlugins` from `~/.claude/settings.json` rather than
+  copying every stack plugin. A flat copy of all five is last-write-wins, and `fix-bug`
+  plus `branch-and-pr` exist in four of them while `component`, `state` and
+  `create-component` exist in three - an iOS repo could have ended up running the
+  Android `create-component`. The `--platform` flag is now only the fallback for a
+  machine with no Claude Code settings to read.
+- `test/stack-content-sync.test.mjs` - three cases locking content propagation,
+  content-only version bumps, and no-op idempotence in the stack-plugin generator.
+
+### Fixed
+
+- **`build-stack-plugins.mjs` never propagated content edits.** It copied a skill only
+  when the skill *set* changed, so editing a routed skill in `shared/external` reached
+  no plugin while the generator reported "all plugins up to date" - which read as
+  confirmation. This falsified the single-authoring-source guarantee the whole
+  `shared/external` design rests on. Found by converting banned punctuation in
+  `ios-coding-standard` and seeing the plugin copy keep all 188 banned characters with a
+  differing `rules.yml`. Fixing it also surfaced 37 stale skill descriptions across four
+  plugins, still missing the "Use when ..." routing clause that decides whether a skill
+  is matched at all: those plugins had been serving worse descriptions than the source
+  for as long as the routing clause existed.
+- `build-stack-plugins.mjs` now accepts `--key=value` as well as `--key value`. The `=`
+  form fell through to the default, so a run aimed at a throwaway checkout silently
+  retargeted the user's real marketplace and reported success.
+- `smoke-install-layout.sh` asserts plugin-skill parity against a seeded probe plugin,
+  so the check cannot pass vacuously in an isolated `HOME` the way it did on first write.
+
+### Changed
+
+- `cross-cli-contract.md` §1.1 replaced the false "frozen fallback" claim with a
+  per-host delivery table: native plugin load on Claude Code, installer-delivered skills
+  on Copilot CLI, installer-delivered refs on Codex CLI. Parity is asserted on the
+  reference set, not the skill set, because Codex ships one router skill by design.
+- `codex-instructions.md` gained a "the skills are on disk, not in the list" section
+  with an `ls` / `grep` / `head` discovery recipe: only 5 of Codex's skill entries render
+  descriptions, so the 193 delivered refs are reachable but not description-matched.
+
 ## [13.2.0] - 2026-07-28
 
 The iOS coding standard reaches all three hosts, and works outside the pipeline.

package/install/_plugin-skills.mjs

@@ -0,0 +1,246 @@
+/**
+ * Stack-plugin skill delivery for the hosts that cannot load a marketplace plugin.
+ *
+ * Claude Code loads `{owner}/multi-agent-plugins` natively, so it gets all of a
+ * stack plugin's skills. The other two hosts do not:
+ *
+ * - **Copilot CLI** has no plugin loader at all. The contract used to say it kept
+ *   standalone `figma-*` copies as a "frozen fallback", but `install/copilot.mjs`
+ *   pruned exactly those directories, so in practice Copilot had **zero**
+ *   plugin-authored skills - `create-screen`, `figma-validate`, `figma-review`,
+ *   `component`, `state` and `navigation` were all absent. A component task on
+ *   Copilot therefore had nothing to dispatch to.
+ * - **Codex CLI** can install the plugin, but it lists plugin skills by name only
+ *   (measured: all 76 plugin-provided skills render with an empty description while
+ *   the 5 system skills render theirs), and its skills block truncates silently
+ *   once it overflows. So Codex takes the same skills as **reference files**.
+ *
+ * What is copied, and what is deliberately not: a stack plugin's `knowledge/` tree
+ * is generated from the pipeline's own `skills/shared/external`, which the installer
+ * already lays down on Claude Code and Copilot CLI. Copying it again would duplicate
+ * ~5 MB the host already has. Only the plugin's **authored** lifecycle skills are
+ * copied - `index`, `reference/`, `workflow/`, `tools/` - which is 56 files.
+ *
+ * @module install/_plugin-skills
+ */
+
+import { existsSync, readFileSync, readdirSync, statSync } from "fs";
+import { join } from "path";
+
+import { copyDir, countFiles, ensureDir, ensureRealDir, isDryRun } 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"]);
+
+/** 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-backend-toolkit", platform: "all" },
+  { name: "ai-common-engineering-toolkit", platform: "all" },
+]);
+
+/**
+ * Compare two semver-ish directory names, newest last.
+ * @param {string} a
+ * @param {string} b
+ */
+function semverCompare(a, b) {
+  const pa = a.split(".").map((n) => parseInt(n, 10) || 0);
+  const pb = b.split(".").map((n) => parseInt(n, 10) || 0);
+  for (let i = 0; i < Math.max(pa.length, pb.length); i++) {
+    const d = (pa[i] || 0) - (pb[i] || 0);
+    if (d !== 0) return d;
+  }
+  return a.localeCompare(b);
+}
+
+/**
+ * Find a plugin's `skills/` directory.
+ *
+ * A local checkout is preferred over the host's plugin cache: the checkout is what
+ * `/multi-agent:sync` rebuilds, so it is the newest thing on disk, while the cache
+ * only advances when the marketplace is refreshed. Cache dirs are version-named, so
+ * the newest is picked rather than whichever `readdir` happened to return first.
+ *
+ * @param {string} home
+ * @param {string} pluginName
+ * @returns {{path: string, source: string}|null}
+ */
+export function resolvePluginSkills(home, pluginName) {
+  const checkout = join(home, "multi-agent-plugins", "plugins", pluginName, "skills");
+  if (existsSync(checkout)) return { path: checkout, source: "local checkout" };
+
+  const cacheRoot = join(home, ".claude", "plugins", "cache", "multi-agent-plugins", pluginName);
+  if (existsSync(cacheRoot)) {
+    const versions = readdirSync(cacheRoot)
+      .filter((v) => {
+        try {
+          return statSync(join(cacheRoot, v)).isDirectory();
+        } catch {
+          return false;
+        }
+      })
+      .sort(semverCompare);
+    for (const v of versions.reverse()) {
+      const p = join(cacheRoot, v, "skills");
+      if (existsSync(p)) return { path: p, source: `plugin cache ${v}` };
+    }
+  }
+  return null;
+}
+
+/**
+ * Which plugins to deliver.
+ *
+ * **Enabled set first, platform second.** Claude Code activates only the plugins a
+ * repo enables, so delivering every stack plugin to another host would give it MORE
+ * than Claude Code has - and worse, it would collide: `fix-bug` and `branch-and-pr`
+ * exist in four stack plugins, `component`, `state` and `create-component` in three.
+ * 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.
+ *
+ * @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)) {
+    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`
+        .map(([k]) => k.split("@")[0])
+        .filter((n) => STACK_PLUGINS.some((p) => p.name === n));
+      if (enabled.length > 0) {
+        // Deterministic order, stack plugin before the shared one: on a name
+        // 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" };
+      }
+    } catch {
+      /* unreadable settings fall through to the platform default */
+    }
+  }
+  const names = STACK_PLUGINS.filter(
+    (p) => p.platform === "all" || platformFlag === "all" || p.platform === platformFlag,
+  ).map((p) => p.name);
+  return { names, source: `--platform=${platformFlag} default (no enabled plugin list found)` };
+}
+
+/**
+ * Copy the authored lifecycle skills of every applicable stack plugin into a flat
+ * destination, one directory per skill.
+ *
+ * Flat rather than group-nested because that is how both hosts discover skills:
+ * `<dest>/<skill-name>/SKILL.md`. The group is an authoring detail.
+ *
+ * @param {object} opts
+ * @param {string} opts.home
+ * @param {string} opts.dest - flat skills directory
+ * @param {"ios"|"android"|"all"} opts.platformFlag
+ * @param {string} opts.label - host label for log lines
+ * @param {Set<string>} [opts.skipNames] - skill names the host already has
+ * @returns {{copied: number, skipped: number, plugins: string[], missing: string[]}}
+ */
+export function installAuthoredPluginSkills(opts) {
+  const { home, dest, platformFlag, label, skipNames = new Set() } = opts;
+  const { names: wanted, source: selectionSource } = pluginsToDeliver(home, platformFlag);
+
+  let copied = 0;
+  let skipped = 0;
+  let collided = 0;
+  const plugins = [];
+  const missing = [];
+  // Names delivered in THIS pass, so a later plugin cannot overwrite an earlier
+  // one's skill of the same name.
+  const delivered = new Set();
+
+  for (const pluginName of wanted) {
+    const resolved = resolvePluginSkills(home, pluginName);
+    if (!resolved) {
+      missing.push(pluginName);
+      continue;
+    }
+    let perPlugin = 0;
+    for (const group of AUTHORED_GROUPS) {
+      const groupDir = join(resolved.path, group);
+      if (!existsSync(groupDir)) continue;
+
+      // `index` is a single skill directory, the others hold one per child.
+      const entries =
+        group === "index"
+          ? existsSync(join(groupDir, "SKILL.md"))
+            ? [{ name: "index", from: groupDir }]
+            : []
+          : readdirSync(groupDir, { withFileTypes: true })
+              .filter((e) => e.isDirectory())
+              .map((e) => ({ name: e.name, from: join(groupDir, e.name) }));
+
+      for (const { name, from } of entries) {
+        if (skipNames.has(name)) {
+          skipped++;
+          continue;
+        }
+        if (delivered.has(name)) {
+          collided++;
+          continue;
+        }
+        delivered.add(name);
+        const to = join(dest, name);
+        ensureDir(dest);
+        copyDir(from, to, {});
+        copied += countFiles(from);
+        perPlugin++;
+      }
+    }
+    if (perPlugin > 0) plugins.push(`${pluginName} (${resolved.source}, ${perPlugin} skills)`);
+  }
+
+  if (isDryRun()) {
+    console.log(`    [dry-run] would copy authored plugin skills into ${dest}`);
+  }
+  console.log(`    -> ${label}: delivering from ${selectionSource}`);
+  for (const p of plugins) console.log(`    -> ${label}: ${p}`);
+  if (collided > 0) {
+    console.log(
+      `    -> ${label}: ${collided} name collision(s) resolved in favour of the earlier plugin`,
+    );
+  }
+  if (skipped > 0) {
+    console.log(`    -> ${label}: skipped ${skipped} skill(s) the host already carries`);
+  }
+  if (missing.length > 0) {
+    console.log(
+      `    -> ${label}: ${missing.length} plugin(s) not on disk (${missing.join(", ")}); ` +
+        `clone {owner}/multi-agent-plugins or enable them in Claude Code to deliver their skills`,
+    );
+  }
+  return { copied, skipped, collided, plugins, missing, selectionSource };
+}
+
+/**
+ * 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),
+  );
+}
+
+export { ensureRealDir };

package/install/codex.mjs

@@ -33,6 +33,7 @@ import {
 } from "./_common.mjs";
 import { DEV_ONLY_SCRIPTS, countDevOnlyFiles } from "./_dev-only-files.mjs";
 import { installCodexAgents } from "./_codex-agents.mjs";
+import { existingSkillNames, installAuthoredPluginSkills } from "./_plugin-skills.mjs";
 import { generateCodexInstructions } from "./_codex-instructions.mjs";
 import { mergeManagedBlock } from "./_managed-block.mjs";
 
@@ -168,12 +169,11 @@ export function toCodexSkill(raw, name) {
  * }} ctx
  */
 export function installCodex(ctx) {
-  // `indexOnly` and `platformFlag` are intentionally not read. Both exist to
-  // shrink the 428-file external skills tree, which this target never installs:
-  // Codex gets one router skill, so there is nothing for either flag to reduce.
-  // Documented rather than silently dropped, so a future reader does not "fix"
-  // it by wiring flags that would have no effect.
-  const { home, pipelineSrc, useSymlinks } = ctx;
+  // `indexOnly` is intentionally not read: it exists to reduce the skills tree to
+  // its index, and this target delivers skills as reference files rather than as
+  // block entries, so there is nothing for it to shrink. `platformFlag` IS used -
+  // it selects which stack plugin's authored skills are delivered.
+  const { home, pipelineSrc, useSymlinks, platformFlag } = ctx;
 
   const CODEX_DIR = join(home, ".codex");
   const CODEX_SKILLS = join(CODEX_DIR, "skills");
@@ -184,6 +184,7 @@ export function installCodex(ctx) {
   const CODEX_LIB = join(CODEX_DIR, "lib");
   const CODEX_SCHEMAS = join(CODEX_DIR, "schemas");
   const CODEX_RULES = join(CODEX_DIR, "rules");
+  const CODEX_SKILL_REFS = join(CODEX_MA_REFS, "skills");
 
   console.log("  [Codex CLI] Installing pipeline orchestrator...");
   ensureDir(CODEX_DIR);
@@ -192,6 +193,7 @@ export function installCodex(ctx) {
   installRefs(pipelineSrc, CODEX_MA_REFS);
   installPersonas(pipelineSrc, CODEX_AGENTS);
   installPrompt(CODEX_PROMPTS);
+  installSkillRefs(pipelineSrc, CODEX_SKILL_REFS, home, platformFlag);
   installScripts(pipelineSrc, CODEX_SCRIPTS, useSymlinks);
   installTree("lib", pipelineSrc, CODEX_LIB, useSymlinks);
   installTree("schemas", pipelineSrc, CODEX_SCHEMAS, useSymlinks);
@@ -357,6 +359,44 @@ function installPrompt(promptsDir) {
   console.log(`    -> /multi-agent prompt written to ${promptsDir}`);
 }
 
+/**
+ * Deliver every skill Claude Code and Copilot CLI get as a **reference file** under
+ * `~/.codex/multi-agent-refs/skills/`, at zero skills-block cost.
+ *
+ * Codex cannot hold the list. Measured on 0.145: one plugin declaring 142 skills
+ * surfaced 75 of them and evicted an unrelated user-scope skill, and every
+ * plugin-provided skill renders with an empty description, so the block buys nothing
+ * even when it fits. Parity on this host therefore means **reachability**, not an
+ * identical listing: the router reads a skill by path the moment it needs one, the
+ * same way it reads a phase spec.
+ *
+ * Two sources, so the set matches the other hosts exactly:
+ *   - the pipeline's own `skills/shared/external` (what `~/.claude/skills` receives)
+ *   - the enabled stack plugin's authored skills (what the marketplace provides)
+ */
+function installSkillRefs(pipelineSrc, dest, home, platformFlag) {
+  const externalSrc = join(pipelineSrc, "skills", "shared", "external");
+
+  ensureRealDir(dest);
+  ensureDir(dest);
+  wipeDir(dest);
+
+  let count = 0;
+  if (existsSync(externalSrc)) count += copyTreeRewritten(externalSrc, dest);
+
+  const res = installAuthoredPluginSkills({
+    home,
+    dest,
+    platformFlag,
+    label: "Codex CLI",
+    skipNames: existingSkillNames(dest),
+  });
+
+  console.log(
+    `    -> ${count + res.copied} skill file(s) copied to ${dest} as refs (0 skills-block cost)`,
+  );
+}
+
 /**
  * Copy `pipeline/scripts` minus the maintainer-only set.
  *

package/install/copilot.mjs

@@ -25,6 +25,7 @@ import { copyExternalSkillsFiltered } from "./_platform-filter.mjs";
 import { DEV_ONLY_SCRIPTS, countDevOnlyFiles } from "./_dev-only-files.mjs";
 import { generateCopilotInstructions } from "./_copilot-instructions.mjs";
 import { legacyTrailingContent, mergeManagedBlock } from "./_managed-block.mjs";
+import { existingSkillNames, installAuthoredPluginSkills } from "./_plugin-skills.mjs";
 
 /**
  * @param {{
@@ -54,7 +55,7 @@ export function installCopilot(ctx) {
   installAgents(pipelineSrc, COPILOT_AGENTS, useSymlinks);
   installSchemas(pipelineSrc, COPILOT_SCHEMAS, useSymlinks);
   installLib(pipelineSrc, COPILOT_LIB, useSymlinks);
-  installSkills({ pipelineSrc, dest: COPILOT_SKILLS, indexOnly, useSymlinks, platformFlag });
+  installSkills({ home, pipelineSrc, dest: COPILOT_SKILLS, indexOnly, useSymlinks, platformFlag });
 }
 
 /** Start of the pipeline-managed span in copilot-instructions.md. */
@@ -160,7 +161,7 @@ function installLib(pipelineSrc, dest, useSymlinks) {
 }
 
 function installSkills(opts) {
-  const { pipelineSrc, dest, indexOnly, useSymlinks, platformFlag } = opts;
+  const { home, pipelineSrc, dest, indexOnly, useSymlinks, platformFlag } = opts;
   console.log("  [Copilot CLI] Installing skills...");
 
   // Same symlink guard as the other owned trees: never prune or copy through
@@ -237,24 +238,44 @@ function installSkills(opts) {
     }
   }
 
-  // Figma component skills moved to the ai-<platform>-engineering-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.
+  // The pre-migration figma-* skill copies are gone; the plugin owns component work
+  // now. Prune leftovers from an old install so the tree stays consistent.
   for (const sub of ["figma-ios", "figma-android", "figma-common", "figma-to-component"]) {
     const stale = join(dest, sub);
     if (!existsSync(stale)) continue;
     if (isDryRun()) {
-      console.log(`    [dry-run] would prune stale ${stale} (moved to plugin)`);
+      console.log(`    [dry-run] would prune stale ${stale} (superseded by the plugin set)`);
       continue;
     }
     try {
       rmSync(stale, { recursive: true, force: true });
-      console.log(`    -> pruned stale ${sub}/ (moved to marketplace plugin)`);
+      console.log(`    -> pruned stale ${sub}/ (superseded by the plugin set)`);
     } catch {
       /* non-fatal */
     }
   }
 
+  // Deliver the stack plugin's authored skills. Copilot CLI has no marketplace
+  // loader, so without this it has none of them: create-screen, figma-validate,
+  // figma-review, component, state and navigation were all absent, which left a
+  // component task on Copilot with nothing to dispatch to. The contract used to call
+  // the pruned figma-* copies a "frozen fallback"; they were pruned, so the fallback
+  // did not exist.
+  //
+  // `knowledge/` is skipped: it is generated from this pipeline's own
+  // skills/shared/external, which the step above already installed. Copying it again
+  // would duplicate ~5 MB the host already has.
+  const pluginResult = installAuthoredPluginSkills({
+    home,
+    dest,
+    platformFlag,
+    label: "Copilot CLI",
+    skipNames: existingSkillNames(dest),
+  });
+  if (pluginResult.copied > 0) {
+    console.log(`    -> ${pluginResult.copied} plugin skill file(s) delivered to ${dest}`);
+  }
+
   console.log(`    -> ${copilotSkillCount} skill files installed to ${dest}`);
 
   const sharedReadmeSrc = join(pipelineSrc, "skills", "shared", "README.md");

package/install/templates/codex-instructions.md

@@ -35,6 +35,29 @@ on real fan-out, so **delegation is authorized whenever a `/multi-agent` or
 3. Outside an active pipeline run, the default applies: do not delegate unless
    asked.
 
+## The skills are on disk, not in the list
+
+`$HOME/.codex/multi-agent-refs/skills/<name>/SKILL.md` holds every skill Claude Code
+and Copilot CLI get: the pipeline's shared knowledge set plus the enabled stack
+plugin's lifecycle skills (`create-screen`, `create-component`, `figma-validate`,
+`figma-review`, `component`, `state`, `navigation`, `ios-coding-standard`, and the
+rest). They are reference files rather than block entries, so they cost nothing until
+read.
+
+That means they will not be suggested to you. Look for one when the work calls for it:
+
+```bash
+ls "$HOME/.codex/multi-agent-refs/skills"                      # what exists
+grep -rl "<topic>" "$HOME/.codex/multi-agent-refs/skills"/*/SKILL.md | head   # by content
+head -4 "$HOME/.codex/multi-agent-refs/skills/<name>/SKILL.md"  # its description
+```
+
+Read the SKILL.md before implementing in its area, exactly as you would read a phase
+spec. A component or screen task should reach `figma-validate` and `create-screen`; a
+Swift review should reach `ios-coding-standard` and cite rule IDs from
+`references/rules.yml`. Guessing a convention that one of these files states is the
+failure this layout exists to prevent.
+
 ## Skills-block budget
 
 Codex assembles every discovered skill's name + description into one prompt block

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mmerterden/multi-agent-pipeline",
-  "version": "13.2.0",
+  "version": "13.3.0",
   "description": "8-phase AI development pipeline with full orchestration on Claude Code, Copilot CLI and Codex CLI. Analysis, planning, TDD, CLI-aware parallel review with consensus surfacing + Fable triage, default-FAIL evidence gates, secret + intent guards, per-phase cost ledger, persistent learnings memory, wiki generation, commit automation. Token-preserving uninstall.",
   "type": "module",
   "main": "index.js",