@mmerterden/multi-agent-pipeline 11.2.0 → 11.3.1

package/pipeline/{commands/multi-agent/refs → multi-agent-refs}/wiki-capture.md

@@ -2,7 +2,7 @@
 
 > **TLDR**  -  Component tasks can auto-generate wiki docs + Figma screenshots. The Wiki adapter is invoked from `/multi-agent:channels` (Phase 7 delegates, or user invokes post-hoc). Four layouts supported (`submodule`, `in-repo`, `github-wiki`, `separate-repo`)  -  adapter picked from `figmaConfig.wiki.mode`. Non-blocking: failures log a warning and channels continues to other adapters. The Wiki adapter supports scope multi-select (Case A) and a precondition-failure menu (Case B)  -  see below.
 
-This doc is referenced from `commands/multi-agent/channels.md` (Wiki adapter) and indirectly from `refs/phases/phase-7-report.md` (which delegates all external delivery to channels). Keeping it separate keeps both files under their token budgets and gives the contract a stable location for Claude-side + Copilot-side implementations.
+This doc is referenced from `commands/multi-agent/channels/SKILL.md` (Wiki adapter) and indirectly from `$HOME/.claude/multi-agent-refs/phases/phase-7-report.md` (which delegates all external delivery to channels). Keeping it separate keeps both files under their token budgets and gives the contract a stable location for Claude-side + Copilot-side implementations.
 
 ## Applicability
 
@@ -77,9 +77,9 @@ Save the answer to `prefs.global.wikiDefault` for next run. Migration script (`m
 
 ## Dispatch
 
-1. Resolve wiki mode from `figmaConfig.wiki.mode`  -  one of `submodule`, `in-repo`, `github-wiki`, `separate-repo`. Each has a dedicated adapter inside the `figma-component-wiki` skill; see `pipeline/skills/figma-ios/figma-component-wiki/SKILL.md` for per-mode path layout and push semantics.
+1. Resolve wiki mode from `figmaConfig.wiki.mode`  -  one of `submodule`, `in-repo`, `github-wiki`, `separate-repo`. Each has a dedicated adapter inside the `figma-component-wiki` skill; see the `ai-ios-engineering-toolkit:figma-component-wiki` plugin skill for per-mode path layout and push semantics.
 2. Emit progress line: `→ writing wiki {componentName} (mode: {mode})`.
-3. Dispatch to `pipeline/skills/figma-ios/figma-component-wiki` (iOS) or `pipeline/skills/figma-android/figma-component-wiki` (Android), passing `{componentName, componentPath, figmaConfig, agentState}`.
+3. Dispatch to the plugin skill `ai-ios-engineering-toolkit:figma-component-wiki` (iOS) or `ai-android-engineering-toolkit:figma-component-wiki` (Android), passing `{componentName, componentPath, figmaConfig}`.
 4. Skill returns `{ writtenPaths[], committedSha?, pushedRemote? }`. Write `writtenPaths` to Phase 7 summary's "Files written" section and push metadata (if any) to "External publishes".
 5. On adapter failure  -  log the adapter + mode + error, continue Phase 7. Wiki is a non-blocking augmentation; the Jira comment in Step 3 already carries the component summary, so the developer is never left in the dark if wiki misfires.
 
@@ -107,6 +107,6 @@ Claude Code and Copilot CLI MUST:
 - Render byte-identical Case A / Case B menus (spacing, brackets, numbering).
 - Respect `prefs.global.wikiScope` array. Legacy `wikiDefault` boolean is migrated on first v5.7 load.
 - Treat adapter failures as non-blocking with the same log shape.
-- Pause the Case A / Case B menu in autopilot  -  per Phase 7 autopilot exception (`refs/phases/modes.md`). 30-min timeout ends session cleanly; resume re-opens menu.
+- Pause the Case A / Case B menu in autopilot  -  per Phase 7 autopilot exception (`$HOME/.claude/multi-agent-refs/phases/modes.md`). 30-min timeout ends session cleanly; resume re-opens menu.
 
 `smoke-wiki-integration.sh` asserts every contract item documented above.

package/pipeline/preferences-template.json

@@ -71,7 +71,8 @@
       "warnPct": 80,
       "onExceed": "warn",
       "pricingModel": "opus"
-    }
+    },
+    "derivedSkillSources": []
   },
   "projects": {},
   "_figmaConfigTemplate": {
@@ -153,5 +154,20 @@
       "complex": "opus",
       "overrides": {}
     }
+  },
+  "_derivedSkillSourcesTemplate": {
+    "_comment": "Optional. Populate global.derivedSkillSources[] to let /multi-agent:refactor check whether skills you derived from an upstream marketplace plugin have been updated. Kept in your LOCAL prefs only (never synced), so it may reference private sources. Copy an entry like the one below.",
+    "_example": {
+      "label": "Component toolkit skills",
+      "localPath": "plugins/<my-plugin>/skills/workflow",
+      "upstreamMarketplace": "<installed-marketplace-name>",
+      "upstreamPlugin": "<upstream-plugin-name>",
+      "upstreamSkills": [
+        "<skill-a>",
+        "<skill-b>"
+      ],
+      "derivedFromVersion": "0.0.0",
+      "upstreamRepoUrl": "https://github.com/<org>/<repo>"
+    }
   }
 }

package/pipeline/rules/figma-pipeline.md

@@ -1,6 +1,6 @@
 ## Figma -> Component Generation
 
-Skill set under `pipeline/skills/figma-ios/` (iOS), `pipeline/skills/figma-android/` (Android), and `pipeline/skills/figma-common/` (shared). Activated when the task contains a Figma URL and target files are `.swift` (iOS) or `.kt` (Android).
+Skill set lives in the marketplace plugins  -  `ai-ios-engineering-toolkit` (iOS/SwiftUI) and `ai-android-engineering-toolkit` (Android/Compose). Activated when the task contains a Figma URL and target files are `.swift` (iOS) or `.kt` (Android).
 
 ### MUST: Figma access - 3-tier fallback chain (BLOCKING, pipeline-wide)
 
@@ -190,7 +190,7 @@ Phase 3.3: figma-iteration-commit     → Batch iteration commit (if iterating)
 | Wiki | enabled/disabled | `wiki.enabled` |
 | Figma API | MCP / REST fallback | `figma.mcpEnabled` |
 
-Provider interfaces are defined inline in the platform skill sets  -  see `pipeline/skills/figma-common/`, `pipeline/skills/figma-ios/`, and `pipeline/skills/figma-android/`.
+Provider interfaces are defined inline in the plugin skill sets  -  see the `ai-ios-engineering-toolkit` and `ai-android-engineering-toolkit` marketplace plugins.
 
 ### Optional Features (graceful skip when disabled)
 

package/pipeline/schemas/prefs.schema.json

@@ -613,40 +613,6 @@
           "default": true,
           "description": "When the Wiki channel produces component wiki content AND a Jira issue is linked (`state.jiraId` set), also post a humanizer-passed summary of the wiki content as a Jira comment so QA + PMs see the component docs inline. Independent of `reportChannels.jira` (which controls whether the main Jira comment runs). Set `false` to suppress only the wiki-summary comment."
         },
-        "figmaSource": {
-          "type": [
-            "object",
-            "null"
-          ],
-          "additionalProperties": false,
-          "description": "Upstream figma-to-component source for incremental sync (WS-9). Set manually by users who maintain a separate source project and want `/multi-agent:sync` to keep `pipeline/skills/figma-ios/` in step. Null = no sync, import was one-shot.",
-          "properties": {
-            "path": {
-              "type": "string",
-              "description": "Absolute path to the source project root (expects `.instructions/figma/` and `.claude/skills/` subtrees)."
-            },
-            "branch": {
-              "type": "string",
-              "default": "develop",
-              "description": "Source branch to pull from."
-            },
-            "lastSyncedAt": {
-              "type": [
-                "string",
-                "null"
-              ],
-              "format": "date-time",
-              "description": "ISO timestamp of the most recent successful sync."
-            },
-            "lastCommit": {
-              "type": [
-                "string",
-                "null"
-              ],
-              "description": "Source commit SHA captured at the most recent successful sync. Used as the floor for incremental diff."
-            }
-          }
-        },
         "promptLanguage": {
           "type": "string",
           "enum": [

package/pipeline/scripts/README.md

@@ -15,7 +15,7 @@ Validate contracts. Each emits `══ <name> smoke: N passed, M failed ══`
 - `smoke-figma-cross-cli-inventory.sh`  -  figma skill cross-CLI source-tree parity (39 assertions)
 
 ### Figma pipeline (see `pipeline/scripts/README-figma-smokes.md` for the full index)
-- `smoke-figma-android-parity.sh`, `smoke-figma-config-schema.sh`, `smoke-figma-dispatch.sh`, `smoke-figma-skill-import.sh`, `smoke-figma-sync.sh`
+- `smoke-figma-config-schema.sh`, `smoke-figma-dispatch.sh`
 
 ### Phase contracts
 - `smoke-phase-0-multi-repo.sh`  -  Phase 0 multi-repo mode fetch + worktree atomicity
@@ -78,8 +78,6 @@ Shell scripts invoked during pipeline execution.
 - `search-logs.sh`  -  backs `/multi-agent:search`
 - `scan-skills.sh`  -  backs `/multi-agent:scan`
 - `benchmark-phase-0.sh`  -  Phase 0 perf harness
-- `sync-figma-source.sh`  -  WS-9 source sync (figma)
-- `import-figma-skills.sh`  -  developer-only import harness (not run at runtime)
 - `github-ssh-setup.sh`  -  first-run SSH key setup helper
 - `sync-parity-check.sh`  -  manual parity verification helper
 

package/pipeline/scripts/build-skills-index.mjs

@@ -13,8 +13,7 @@
 //   name           -  frontmatter `name:` (fallback: directory name)
 //   description    -  frontmatter `description:` (first 300 chars)
 //   platform       -  frontmatter `platform:` if set (ios / android / generic)
-//   group          -  derived from path: core / figma-ios / figma-android /
-//                    figma-common / external
+//   group          -  derived from path: core / external
 //   triggerKeywords  -  frontmatter `trigger-keywords:` (comma-separated
 //                    values lowercased)  -  authors can add these to tighten
 //                    match score. Missing → empty list.
@@ -66,9 +65,6 @@ function parseFrontmatter(raw) {
 function groupFromPath(rel) {
   if (rel.startsWith("shared/core/")) return "core";
   if (rel.startsWith("shared/external/")) return "external";
-  if (rel.startsWith("figma-ios/")) return "figma-ios";
-  if (rel.startsWith("figma-android/")) return "figma-android";
-  if (rel.startsWith("figma-common/")) return "figma-common";
   return "other";
 }
 
@@ -107,7 +103,8 @@ entries.sort((a, b) => a.name.localeCompare(b.name));
 
 const json = {
   schemaVersion: "1.0.0",
-  generatedAt: new Date().toISOString(),
+  // No generatedAt timestamp: the index is a committed build artifact and must
+  // be idempotent, so regenerating on an unchanged skill set produces no diff.
   skillCount: entries.length,
   entries,
 };

package/pipeline/scripts/eval-mine-corpus.mjs

@@ -0,0 +1,187 @@
+#!/usr/bin/env node
+// eval-mine-corpus.mjs  -  grow the triage eval set from real production runs.
+//
+// The pipeline already records every Phase 4 triage decision to
+// `~/.claude/logs/multi-agent/triage-corpus.jsonl` (one line per finding:
+// severity/file/line/issue/fix/reviewer + the classification the run gave it,
+// plus an optional human `reason`/`reviewer`). Hand-authoring eval fixtures is
+// the bottleneck; this closes the loop by turning those real decisions into
+// CANDIDATE regression fixtures in the exact shape `eval-triage.mjs` consumes.
+//
+// It is review-gated on purpose: candidates land in
+// `pipeline/eval/triage-candidates/<task_id>/` (which eval-triage does NOT
+// walk), each validated against the triage schema. A maintainer reviews them,
+// fills scope/diffSummary, and moves the good ones into
+// `pipeline/eval/triage/<NN>-<name>/` to adopt them.
+//
+// Highest-signal cases (a human left a `reason` or `reviewer`) are emitted
+// first and marked, since those encode a deliberate triage judgement.
+//
+// Usage:
+//   node pipeline/scripts/eval-mine-corpus.mjs                 # default corpus path
+//   node pipeline/scripts/eval-mine-corpus.mjs --corpus <path>
+//   node pipeline/scripts/eval-mine-corpus.mjs --limit 20      # cap candidates
+//   node pipeline/scripts/eval-mine-corpus.mjs --dry-run       # report, write nothing
+//
+// Exit codes: 0 ok (including "nothing to mine"), 2 usage/setup error.
+
+import { readdirSync, readFileSync, writeFileSync, mkdirSync, existsSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { homedir } from "node:os";
+import { spawnSync } from "node:child_process";
+
+const here = dirname(fileURLToPath(import.meta.url));
+const root = resolve(here, "..", "..");
+const evalTriageDir = join(root, "pipeline", "eval", "triage");
+const candidatesDir = join(root, "pipeline", "eval", "triage-candidates");
+const validator = join(root, "pipeline", "scripts", "validate-triage.mjs");
+
+const args = process.argv.slice(2);
+const opts = { corpus: null, limit: Infinity, dryRun: false };
+for (let i = 0; i < args.length; i++) {
+  if (args[i] === "--corpus") opts.corpus = args[++i];
+  else if (args[i] === "--limit") opts.limit = Number(args[++i]) || Infinity;
+  else if (args[i] === "--dry-run") opts.dryRun = true;
+  else if (args[i] === "-h" || args[i] === "--help") {
+    console.log("Usage: eval-mine-corpus.mjs [--corpus <path>] [--limit N] [--dry-run]");
+    process.exit(0);
+  }
+}
+
+const corpusPath =
+  opts.corpus || join(homedir(), ".claude", "logs", "multi-agent", "triage-corpus.jsonl");
+
+if (!existsSync(corpusPath)) {
+  console.log(`eval-mine-corpus: no corpus at ${corpusPath} - nothing to mine.`);
+  process.exit(0);
+}
+
+// Parse the JSONL corpus, skipping blank/malformed lines (never crash on data).
+const rows = [];
+for (const line of readFileSync(corpusPath, "utf-8").split("\n")) {
+  const s = line.trim();
+  if (!s) continue;
+  try {
+    const r = JSON.parse(s);
+    if (r && r.task_id && r.issue && r.classification) rows.push(r);
+  } catch {
+    /* skip malformed line */
+  }
+}
+
+if (rows.length === 0) {
+  console.log("eval-mine-corpus: corpus has no usable rows - nothing to mine.");
+  process.exit(0);
+}
+
+// task_ids that already have an adopted fixture: skip so we only propose new cases.
+const adopted = new Set();
+if (existsSync(evalTriageDir)) {
+  for (const name of readdirSync(evalTriageDir)) {
+    const inputPath = join(evalTriageDir, name, "input.json");
+    if (existsSync(inputPath)) {
+      try {
+        const meta = JSON.parse(readFileSync(join(evalTriageDir, name, "meta.json"), "utf-8"));
+        if (meta.task_id) adopted.add(meta.task_id);
+      } catch {
+        /* no meta.json -> can't dedup by task_id, that's fine */
+      }
+    }
+  }
+}
+
+// Group corpus rows by task_id.
+const byTask = new Map();
+for (const r of rows) {
+  if (!byTask.has(r.task_id)) byTask.set(r.task_id, []);
+  byTask.get(r.task_id).push(r);
+}
+
+const toFinding = (r) => ({
+  severity: r.severity,
+  file: r.file,
+  // Triage contract requires an integer line >= 0; corpus may carry null for a
+  // file-level finding, so coerce to 0 (the schema's file-level sentinel).
+  line: Number.isInteger(r.line) ? r.line : 0,
+  issue: r.issue,
+  fix: r.fix ?? null,
+  reviewer: r.reviewer ?? null,
+});
+
+// Build a candidate per task. Highest-signal first (has a human reason/reviewer).
+const candidates = [];
+for (const [taskId, findings] of byTask) {
+  if (adopted.has(taskId)) continue;
+  const rawFindings = findings.map(toFinding);
+  const accepted = [];
+  const deferred = [];
+  const rejected = [];
+  for (const r of findings) {
+    if (r.classification === "accepted") accepted.push(toFinding(r));
+    else if (r.classification === "deferred")
+      deferred.push({ finding: toFinding(r), reason: r.reason || "TODO: reason (from corpus)" });
+    else if (r.classification === "rejected")
+      rejected.push({ finding: toFinding(r), reason: r.reason || "TODO: reason (from corpus)" });
+  }
+  const hasHumanSignal = findings.some((r) => r.reason || r.reviewer);
+  const title = findings.find((f) => f.task_title)?.task_title || taskId;
+  candidates.push({
+    taskId,
+    hasHumanSignal,
+    input: {
+      rawFindings,
+      // Corpus does not record scope/diff; a maintainer fills these before adopting.
+      scope: `TODO: scope for ${title}`,
+      diffSummary: "TODO: diff summary",
+    },
+    expected: {
+      accepted,
+      deferred,
+      rejected,
+      // Blockers loop back to dev, so a run with an accepted blocker is not approved.
+      approved: accepted.every((f) => f.severity !== "blocking"),
+    },
+  });
+}
+
+candidates.sort((a, b) => Number(b.hasHumanSignal) - Number(a.hasHumanSignal));
+const selected = candidates.slice(0, opts.limit);
+
+if (selected.length === 0) {
+  console.log("eval-mine-corpus: no new task_ids to propose (all already adopted).");
+  process.exit(0);
+}
+
+let written = 0;
+let invalid = 0;
+for (const c of selected) {
+  const safe = c.taskId.replace(/[^A-Za-z0-9._-]/g, "_");
+  const dir = join(candidatesDir, safe);
+  const tag = c.hasHumanSignal ? " [human-signal]" : "";
+  if (opts.dryRun) {
+    console.log(`  would emit candidate: ${safe} (${c.input.rawFindings.length} findings)${tag}`);
+    continue;
+  }
+  mkdirSync(dir, { recursive: true });
+  writeFileSync(join(dir, "input.json"), JSON.stringify(c.input, null, 2) + "\n");
+  writeFileSync(join(dir, "expected.json"), JSON.stringify(c.expected, null, 2) + "\n");
+  writeFileSync(
+    join(dir, "meta.json"),
+    JSON.stringify({ task_id: c.taskId, source: "eval-mine-corpus", hasHumanSignal: c.hasHumanSignal }, null, 2) + "\n",
+  );
+  // Validate the emitted expected.json against the triage contract; flag if bad.
+  const res = spawnSync("node", [validator, join(dir, "expected.json")], { encoding: "utf-8" });
+  const ok = res.status === 0;
+  if (!ok) invalid++;
+  console.log(`  emitted: triage-candidates/${safe}${tag} ${ok ? "(schema OK)" : "(SCHEMA FAIL - review)"}`);
+  written++;
+}
+
+if (!opts.dryRun) {
+  console.log("");
+  console.log(`eval-mine-corpus: ${written} candidate(s) written to pipeline/eval/triage-candidates/`);
+  if (invalid > 0) console.log(`  ${invalid} failed schema validation - fix before adopting.`);
+  console.log("  Review each, fill scope/diffSummary, then move good ones into");
+  console.log("  pipeline/eval/triage/<NN>-<name>/ to add them to the eval suite.");
+}

package/pipeline/scripts/fixtures/install-layout.tsv

@@ -1,16 +1,17 @@
 .claude/CLAUDE.md	1
 .claude/agents	8
-.claude/commands	92
+.claude/commands	42
 .claude/lib	24
 .claude/multi-agent-preferences.json	1
+.claude/multi-agent-refs	50
 .claude/rules	12
 .claude/schemas	23
-.claude/scripts	180
+.claude/scripts	178
 .claude/settings.json	1
-.claude/skills	572
+.claude/skills	428
 .copilot/agents	8
 .copilot/copilot-instructions.md	1
 .copilot/lib	24
 .copilot/schemas	23
-.copilot/scripts	180
-.copilot/skills	609
+.copilot/scripts	178
+.copilot/skills	465

package/pipeline/scripts/gen-mode-dispatch.mjs

@@ -97,7 +97,7 @@ const skipNote = skippedIds.length > 0
   ? `${modeLabel} mode does NOT TaskCreate phases ${skippedIds.join("/")}  -  those are not part of the ${modeLabel} phase set (\`${spec.phases.join(" ")}\`). Only register tiles for the active set.`
   : `${modeLabel} mode TaskCreates all 8 phases (no phase is skipped).`;
 
-const orderingNote = `**All TaskCreate calls fire in strict phase-number order BEFORE any TaskUpdate is applied.** For ${modeLabel} that means: ${phaseSequence}. The native widget renders by creation order, not by phase number  -  out-of-order calls produce visually scrambled tile stacks. Full ordering contract in \`refs/tracker-contract.md\` section "TaskCreate ordering (strict)".`;
+const orderingNote = `**All TaskCreate calls fire in strict phase-number order BEFORE any TaskUpdate is applied.** For ${modeLabel} that means: ${phaseSequence}. The native widget renders by creation order, not by phase number  -  out-of-order calls produce visually scrambled tile stacks. Full ordering contract in \`$HOME/.claude/multi-agent-refs/tracker-contract.md\` section "TaskCreate ordering (strict)".`;
 
 const localCaveat = spec.local
   ? `\n> **Local mode:** no worktree is created, work happens on the current branch. Phase 0 Init still calls \`init\`  -  the \`--local\` flag is stored in tracker-state.json, and \`:resume\` restores the correct CWD.\n`
@@ -109,7 +109,7 @@ const banner = spec.autopilot
 
 const out = `## Required: Phase Tracker Contract
 
-**The phase tracker is mandatory**  -  the agent cannot skip it. Full spec: [\`refs/tracker-contract.md\`](./refs/tracker-contract.md).
+**The phase tracker is mandatory**  -  the agent cannot skip it. Full spec: [\`$HOME/.claude/multi-agent-refs/tracker-contract.md\`]($HOME/.claude/multi-agent-refs/tracker-contract.md).
 ${banner}${localCaveat}
 Two channels run in parallel at every phase boundary:
 
@@ -135,7 +135,7 @@ bash $HOME/.claude/scripts/phase-tracker.sh tokens <N> <in> <out>
 
 In Claude Code the agent MUST also drive the native TaskList widget so the user sees a sticky phase tile stack  -  this is the only progress signal Claude Code surfaces. Skipping these calls is the #1 source of "I don't see any phases" complaints.
 
-**TaskCreate ordering (strict)**: All TaskCreate calls fire in strict phase-number order BEFORE any TaskUpdate is applied. The native widget renders by creation order, not by phase number  -  out-of-order calls produce visually scrambled tile stacks (e.g. \`1 ✓ · 2 ✓ · 4 ✓ · 0 ▶ · 3 ☐\`) even when the underlying state is correct. Pre-marking phases as completed/skipped before Phase 0 starts is FORBIDDEN  -  register the tile in order, then flip status via TaskUpdate when the phase actually short-circuits. Full contract in \`refs/tracker-contract.md\` section "TaskCreate ordering (strict)".
+**TaskCreate ordering (strict)**: All TaskCreate calls fire in strict phase-number order BEFORE any TaskUpdate is applied. The native widget renders by creation order, not by phase number  -  out-of-order calls produce visually scrambled tile stacks (e.g. \`1 ✓ · 2 ✓ · 4 ✓ · 0 ▶ · 3 ☐\`) even when the underlying state is correct. Pre-marking phases as completed/skipped before Phase 0 starts is FORBIDDEN  -  register the tile in order, then flip status via TaskUpdate when the phase actually short-circuits. Full contract in \`$HOME/.claude/multi-agent-refs/tracker-contract.md\` section "TaskCreate ordering (strict)".
 
 \`\`\`text
 # Phase 0 startup  -  register one tile per phase (0..N), capture the taskId, persist it:

package/pipeline/scripts/lint-skills.mjs

@@ -21,7 +21,11 @@ import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 
 const repoRoot = join(dirname(fileURLToPath(import.meta.url)), "..", "..");
-const files = execSync("find pipeline -name SKILL.md", { cwd: repoRoot, encoding: "utf-8" })
+// Scope to pipeline/skills only. Slash commands under pipeline/commands also use
+// the <name>/SKILL.md layout now, but they are command definitions
+// (description + allowed-tools, name derived from the dir), NOT skills, so the
+// skill frontmatter contract (required `name:`) does not apply to them.
+const files = execSync("find pipeline/skills -name SKILL.md", { cwd: repoRoot, encoding: "utf-8" })
   .trim()
   .split("\n")
   .filter(Boolean)
@@ -29,6 +33,10 @@ const files = execSync("find pipeline -name SKILL.md", { cwd: repoRoot, encoding
 
 const errors = [];
 const fail = (file, msg) => errors.push(`${file}: ${msg}`);
+// Non-fatal quality signals (a terse description routes poorly). Warnings never
+// fail the gate; they surface skills whose frontmatter could trigger better.
+const warnings = [];
+const warn = (file, msg) => warnings.push(`${file}: ${msg}`);
 
 for (const file of files) {
   const raw = readFileSync(join(repoRoot, file), "utf-8");
@@ -61,6 +69,18 @@ for (const file of files) {
     fail(file, "description is empty");
   } else if (fields.description.length > 1024) {
     fail(file, `description exceeds 1024 chars (${fields.description.length})`);
+  } else {
+    // Routing quality: a description of a few words rarely says what the skill
+    // does AND when to use it, so the model cannot decide to trigger it.
+    // Skip YAML block scalars (`description: |` / `>`): this line-based parser
+    // only sees the indicator, not the real multi-line text, so a word count
+    // would be a false positive.
+    const desc = fields.description;
+    const isBlockScalar = /^[|>][+-]?\d*$/.test(desc);
+    const words = desc.split(/\s+/).filter(Boolean).length;
+    if (!isBlockScalar && words < 6) {
+      warn(file, `description is terse (${words} words) - say what it does AND when to use it`);
+    }
   }
 
   if ("user-invocable" in fields && !["true", "false"].includes(fields["user-invocable"])) {
@@ -72,6 +92,11 @@ for (const file of files) {
   }
 }
 
+if (warnings.length > 0) {
+  console.warn(`lint-skills: ${warnings.length} warning(s) (non-fatal):`);
+  for (const w of warnings) console.warn("  " + w);
+}
+
 if (errors.length > 0) {
   console.error(`lint-skills: ${errors.length} error(s) across ${files.length} SKILL.md files`);
   for (const e of errors) console.error("  " + e);

package/pipeline/scripts/phase-banner.sh

@@ -21,7 +21,7 @@
 # Localization:
 #   PHASE_LANG=en (default) | tr  -  when set to tr, canonical labels resolve to
 #   Turkish. The `auto` sentinel in place of [name] triggers a table lookup.
-#   Canonical label set mirrors pipeline/commands/multi-agent/refs/phases.md.
+#   Canonical label set mirrors pipeline/multi-agent-refs/phases.md.
 #
 # Output is colored when stdout is a TTY (TERM != dumb). Plain otherwise so
 # logs and CI artifacts stay readable. Always written to stdout  -  log
@@ -32,7 +32,7 @@ set -uo pipefail
 PHASE_LANG="${PHASE_LANG:-en}"
 
 # Canonical phase label table. Keep synced with
-# pipeline/commands/multi-agent/refs/phases.md and the table in
+# pipeline/multi-agent-refs/phases.md and the table in
 # pipeline/skills/shared/multi-agent/SKILL.md.
 phase_label() {
   local phase="$1" lang="${2:-en}"

package/pipeline/scripts/review-scope.mjs

@@ -0,0 +1,94 @@
+#!/usr/bin/env node
+/**
+ * @file review-scope.mjs  -  v11.3.0
+ *
+ * Diff-complexity gate for Phase 4 Stage 2. On trivial diffs, every reviewer
+ * model agrees and the 2nd/3rd model + triage cost is paid for nothing (a
+ * recurring practitioner complaint about multi-model review). This decides how
+ * many reviewers to dispatch from the deterministic diff-risk report  -  no LLM.
+ *
+ * Pure function of the diff-risk JSON (read on stdin or --file). A diff is
+ * "trivial" (→ single reviewer) only when ALL hold:
+ *   - total churn (loc_added + loc_removed) <= --loc-floor (default 20)
+ *   - totals.max_score < --risk-floor (default 3.0)
+ *   - NO file carries a high-stakes signal: security_path, migration,
+ *     public_api, no_test_change, test_lines_removed
+ * Otherwise → full (the CLI-aware set: 2 on Claude Code, 3 on Copilot CLI).
+ *
+ * Conservative by design: any doubt → full review. Skipping reviewers trades
+ * coverage for cost, so the bar for "trivial" is deliberately high.
+ *
+ * Usage:
+ *   node diff-risk-score.mjs --base B --head H | node review-scope.mjs
+ *   node test-review-scope: node review-scope.mjs --file risk.json --loc-floor 20 --risk-floor 3.0
+ *
+ * Output (stdout, JSON): { scope: "single"|"full", reason, churn, maxScore, blockers }
+ * Exit 0 always. Invalid/empty input → fail SAFE to "full" (never under-review).
+ */
+import { readFileSync } from "node:fs";
+
+const args = process.argv.slice(2);
+const num = (flag, dflt) => {
+  const i = args.indexOf(flag);
+  return i !== -1 && args[i + 1] != null ? Number(args[i + 1]) : dflt;
+};
+const LOC_FLOOR = num("--loc-floor", 20);
+const RISK_FLOOR = num("--risk-floor", 3.0);
+const fileFlag = args.indexOf("--file");
+
+const HIGH_STAKES = new Set([
+  "security_path",
+  "migration",
+  "public_api",
+  "no_test_change",
+  "test_lines_removed",
+]);
+
+function readInput() {
+  try {
+    return fileFlag !== -1 && args[fileFlag + 1]
+      ? readFileSync(args[fileFlag + 1], "utf8")
+      : readFileSync(0, "utf8");
+  } catch {
+    return "";
+  }
+}
+
+function emit(o) {
+  process.stdout.write(JSON.stringify(o));
+}
+
+function main() {
+  let report;
+  try {
+    report = JSON.parse(readInput());
+  } catch {
+    emit({ scope: "full", reason: "no-risk-data-fail-safe", churn: null, maxScore: null, blockers: [] });
+    return;
+  }
+
+  const t = report?.totals || {};
+  const churn = (t.loc_added ?? 0) + (t.loc_removed ?? 0);
+  const maxScore = t.max_score ?? 0;
+  const files = Array.isArray(report?.files) ? report.files : [];
+
+  const blockers = [];
+  for (const f of files) {
+    for (const s of f.signals || []) {
+      if (HIGH_STAKES.has(s.name)) blockers.push({ file: f.file, signal: s.name });
+    }
+  }
+
+  const trivial = churn <= LOC_FLOOR && maxScore < RISK_FLOOR && blockers.length === 0;
+  const reason = trivial
+    ? `trivial: churn ${churn}<=${LOC_FLOOR}, maxScore ${maxScore}<${RISK_FLOOR}, no high-stakes signals`
+    : blockers.length
+      ? `high-stakes signal(s): ${[...new Set(blockers.map((b) => b.signal))].join(", ")}`
+      : churn > LOC_FLOOR
+        ? `churn ${churn} > ${LOC_FLOOR}`
+        : `maxScore ${maxScore} >= ${RISK_FLOOR}`;
+
+  emit({ scope: trivial ? "single" : "full", reason, churn, maxScore, blockers });
+}
+
+main();

package/pipeline/scripts/scan-agent-config.sh

@@ -31,8 +31,8 @@ add "$ROOT/install/templates/claude-hooks.json"
 add "$ROOT/install/templates/copilot-instructions.md"
 add "$ROOT/pipeline/preferences-template.json"
 for f in "$ROOT"/pipeline/agents/*.md; do add "$f"; done
-for f in "$ROOT"/pipeline/skills/figma-common/figma-setup/scripts/*.py \
-         "$ROOT"/pipeline/skills/figma-ios/figma-to-component/scripts/*.py; do add "$f"; done
+# (figma component skills + their scripts now live in the ai-*-engineering-toolkit
+#  marketplace plugin, not in this repo, so there is nothing figma to scan here.)
 add "$ROOT/pipeline/scripts/agent-guard.sh"
 add "$ROOT/pipeline/scripts/pre-commit-check.sh"
 

package/pipeline/scripts/smoke-agent-log-cost.sh

@@ -20,7 +20,7 @@ RENDERER="$ROOT/pipeline/scripts/render-agent-log-cost.sh"
 TRACKER="$ROOT/pipeline/scripts/phase-tracker.sh"
 LOG_METRIC="$ROOT/pipeline/scripts/log-metric.sh"
 TABLE="$ROOT/pipeline/scripts/cost-table.json"
-LOG_FORMAT_DOC="$ROOT/pipeline/commands/multi-agent/refs/phases/log-format.md"
+LOG_FORMAT_DOC="$ROOT/pipeline/multi-agent-refs/phases/log-format.md"
 
 pass=0
 fail=0

package/pipeline/scripts/smoke-agent-model-routing.sh

@@ -15,8 +15,8 @@ set -euo pipefail
 ROOT="$(cd "$(dirname "$0")/../.." && pwd)"
 AGENTS_DIR="$ROOT/pipeline/agents"
 ORCH_SKILL="$ROOT/pipeline/skills/shared/core/multi-agent/SKILL.md"
-ORCH_CMD="$ROOT/pipeline/commands/multi-agent.md"
-PHASE4="$ROOT/pipeline/commands/multi-agent/refs/phases/phase-4-review.md"
+ORCH_CMD="$ROOT/pipeline/commands/multi-agent/SKILL.md"
+PHASE4="$ROOT/pipeline/multi-agent-refs/phases/phase-4-review.md"
 
 pass=0
 fail=0
@@ -66,9 +66,9 @@ fi
 
 # --- 4b: orchestrator command file references ---
 if grep -q 'preferredModel' "$ORCH_CMD"; then
-  record_pass "commands/multi-agent.md references preferredModel"
+  record_pass "commands/multi-agent/SKILL.md references preferredModel"
 else
-  record_fail "commands/multi-agent.md missing preferredModel reference"
+  record_fail "commands/multi-agent/SKILL.md missing preferredModel reference"
 fi
 
 # --- 5: Phase 4 review doc references override ---

package/pipeline/scripts/smoke-autopilot-circuit-breaker.sh

@@ -8,8 +8,8 @@
 set -uo pipefail
 
 ROOT="$(cd "$(dirname "$0")/../.." && pwd)"
-DOC="$ROOT/pipeline/commands/multi-agent/refs/features/autopilot-circuit-breaker.md"
-MODES="$ROOT/pipeline/commands/multi-agent/refs/phases/modes.md"
+DOC="$ROOT/pipeline/multi-agent-refs/features/autopilot-circuit-breaker.md"
+MODES="$ROOT/pipeline/multi-agent-refs/phases/modes.md"
 
 PASS=0; FAIL=0
 pass() { PASS=$((PASS+1)); echo "  ✓ $1"; }

package/pipeline/scripts/smoke-channels-approval-gate.sh

@@ -13,8 +13,8 @@ set -euo pipefail
 
 HERE="$(cd "$(dirname "$0")" && pwd)"
 ROOT="$(cd "$HERE/../.." && pwd)"
-CHANNELS="$ROOT/pipeline/commands/multi-agent/channels.md"
-PHASE7="$ROOT/pipeline/commands/multi-agent/refs/phases/phase-7-report.md"
+CHANNELS="$ROOT/pipeline/commands/multi-agent/channels/SKILL.md"
+PHASE7="$ROOT/pipeline/multi-agent-refs/phases/phase-7-report.md"
 
 PASS=0
 FAIL=0