@mmerterden/multi-agent-pipeline 8.6.1 → 10.0.6

package/pipeline/adapters/codex.mjs

@@ -0,0 +1,159 @@
+/**
+ * @file OpenAI Codex CLI adapter.
+ *
+ * Codex CLI is a GLOBAL-config tool, not a per-project rule consumer like
+ * Cursor / Antigravity / Copilot Chat. Its custom prompts (slash commands) and
+ * MCP servers live under `~/.codex/`, and there is no project-level prompt
+ * directory. The only project-scoped hook Codex reads is `AGENTS.md` (the shared
+ * open standard), which the Antigravity adapter already writes when installed.
+ *
+ * Therefore this adapter writes Codex's REAL surfaces, all global, and ignores
+ * the per-project `target`:
+ *   ~/.codex/prompts/multi-agent.md   the 8-phase orchestration as a /multi-agent
+ *                                     slash command (sequential - Codex has no
+ *                                     subagent fan-out, so parallel review
+ *                                     degrades to a sequential two-pass)
+ *   ~/.codex/AGENTS.md                marker-wrapped global context block (rules
+ *                                     pointer + skill index)
+ *   ~/.codex/config.toml             marker-wrapped [mcp_servers.dev-toolkit]
+ *                                     registration (TOML managed block)
+ *
+ * Shared gate scripts install to the common `~/.multi-agent/` runtime, same as
+ * the other adapters.
+ *
+ * @module pipeline/adapters/codex
+ */
+
+import { writeFileSync } from "fs";
+import { join } from "path";
+import {
+  collectSkills,
+  ensureDir,
+  installSharedRuntime,
+  removeFileAndPrune,
+  removeManagedBlock,
+  renderSkillIndex,
+  replaceManagedBlock,
+  rewriteScriptRefs,
+  uninstallSharedRuntime,
+  withoutOrchestrationSkills,
+} from "./_base.mjs";
+
+const NAME = "codex";
+
+// TOML cannot host HTML-comment markers, so config.toml uses its own
+// `#`-comment managed block (kept independent of _base's MARKER_BEGIN/END).
+const TOML_MARKERS = Object.freeze({
+  begin: "# multi-agent-pipeline:begin",
+  end: "# multi-agent-pipeline:end",
+});
+
+function codexHome() {
+  const home = process.env.HOME || process.env.USERPROFILE;
+  if (!home) throw new Error("$HOME (or $USERPROFILE) is not set");
+  return join(home, ".codex");
+}
+
+/**
+ * @param {{ pipelineSrc: string, target?: string, platformFilter?: "all"|"ios"|"android" }} opts
+ */
+export function install({ pipelineSrc, platformFilter = "all" }) {
+  const base = codexHome();
+
+  // 1. Slash command -> ~/.codex/prompts/multi-agent.md
+  const promptsDir = join(base, "prompts");
+  ensureDir(promptsDir);
+  writeFileSync(join(promptsDir, "multi-agent.md"), rewriteScriptRefs(ORCHESTRATION_PROMPT));
+
+  // 2. Global context block -> ~/.codex/AGENTS.md
+  const skills = withoutOrchestrationSkills(collectSkills(pipelineSrc, platformFilter));
+  const ctxAction = replaceManagedBlock(join(base, "AGENTS.md"), renderContext(skills));
+
+  // 3. MCP registration -> ~/.codex/config.toml
+  const mcp = mergeTomlMcp(join(base, "config.toml"));
+
+  // 4. Shared runtime so the prompt's gate-script references resolve + run.
+  installSharedRuntime(pipelineSrc);
+
+  console.log(
+    `    -> [codex] prompts/multi-agent.md + AGENTS.md (${ctxAction}) + config.toml mcp (${mcp})`,
+  );
+  console.log(
+    "    -> [codex] global install under ~/.codex (prompts + MCP are global; Codex has no per-project prompt dir).",
+  );
+}
+
+/**
+ * Codex writes only to ~/.codex, so uninstall ignores `target`.
+ */
+export function uninstall() {
+  const base = codexHome();
+  let removed = removeFileAndPrune(join(base, "prompts", "multi-agent.md"));
+
+  if (removeManagedBlock(join(base, "AGENTS.md")).startsWith("removed")) removed++;
+  if (removeManagedBlock(join(base, "config.toml"), { markers: TOML_MARKERS }).startsWith("removed")) removed++;
+  if (uninstallSharedRuntime()) removed++;
+
+  return { removed };
+}
+
+function renderContext(skills) {
+  return renderSkillIndex({
+    title: "# multi-agent-pipeline (Codex CLI)",
+    intro: [
+      "> Installed by @mmerterden/multi-agent-pipeline. Run the pipeline with the",
+      "> `/multi-agent` slash command (defined in `~/.codex/prompts/multi-agent.md`).",
+      "> The dev-toolkit MCP server is registered in `~/.codex/config.toml`.",
+      "> Below is the reference skill index. Remove with",
+      "> `npx @mmerterden/multi-agent-pipeline uninstall --codex`.",
+    ],
+    skills,
+  });
+}
+
+const MCP_BLOCK_BODY = [
+  "[mcp_servers.dev-toolkit]",
+  'command = "npx"',
+  'args = ["-y", "@mmerterden/dev-toolkit-mcp"]',
+].join("\n");
+
+function mergeTomlMcp(tomlPath) {
+  ensureDir(join(tomlPath, ".."));
+  const action = replaceManagedBlock(tomlPath, MCP_BLOCK_BODY, { markers: TOML_MARKERS });
+  // A managed block landing in a pre-existing user TOML is a "merged" config.
+  return action === "appended" ? "merged" : action;
+}
+
+const ORCHESTRATION_PROMPT = `# /multi-agent  -  run the pipeline in Codex CLI
+
+> Installed by @mmerterden/multi-agent-pipeline. Codex runs a single agent loop
+> (no file-declared subagents and no parallel subagent fan-out), so this prompt
+> encodes the 8-phase orchestration sequentially. The standing conventions (TDD,
+> security, code-review, git) live in the skill index in \`~/.codex/AGENTS.md\`.
+> Pickers/approvals follow refs/picker-contract.md - use a numbered prompt and
+> wait for the user's choice. The dev-toolkit MCP server is registered in
+> \`~/.codex/config.toml\`.
+>
+> GATE SCRIPTS: the deterministic-gate scripts are installed to a shared
+> \`$HOME/.multi-agent/scripts/\` runtime (evidence-gate.mjs, classify-intent.sh,
+> learnings-ledger.mjs, validate-triage.mjs, pre-commit-check.sh, ...). Invoke
+> them by that absolute path as explicit steps - there is no PreToolUse hook
+> forcing them, so they are workflow-enforced, not OS-blocked.
+
+Input: a Jira id, GitHub issue, repo#N, or free-text task.
+
+Run these phases in order, obeying every convention in \`~/.codex/AGENTS.md\`:
+
+0. **Init** - detect stack, resolve branch (\`bugfix/…\` / \`feature/…\`), confirm scope.
+1. **Analysis** - explore the codebase; produce a structured analysis: stack, touchedAreas[], risks[], summary.
+2. **Planning** - draft the task breakdown; present it and ask the user to Approve / Cancel / edit (picker-contract). Loop on edits until approved.
+3. **Dev** - implement TDD-first (test -> code -> build), following the conventions.
+4. **Review** - Codex has no parallel subagents, so run review as a sequential two-pass: first a correctness/security pass, then a separate fresh-context pass that tries to REFUTE the first pass's findings (adversarial verify). Add a stack-architect lens (iOS / Android / backend) and a security pass when auth/secrets are touched. Merge findings, triage (accept / defer / reject), fix accepted blocking/important items, re-review.
+5. **Test** - offer an interactive test pass (picker); use the dev-toolkit MCP server for simulator / emulator / web checks.
+6. **Commit** - \`{type}(scope): description\`; never auto-close issues; PR uses \`Ref: #N\`.
+7. **Report** - summarize changes, the review passes, and cost.
+
+No "AI / generated by" in code or commits. Attribute each finding to the review pass that raised it.
+`;
+
+export default { name: NAME, install, uninstall };

package/pipeline/adapters/copilot-chat-orchestration.mjs

@@ -0,0 +1,148 @@
+/**
+ * @file VS Code Copilot Chat orchestration layer  -  emits the FULL-pipeline
+ * artifacts so the pipeline runs in VS Code Copilot Chat agent mode, not just
+ * the knowledge layer.
+ *
+ * VS Code Copilot Chat (2026) supports file-based custom agents
+ * (`.github/agents/*.agent.md`, with `description` / `tools` / `model` /
+ * `agents` / `handoffs`) and prompt-file commands (`.github/prompts/*.prompt.md`),
+ * plus native tool-approval / confirmation dialogs (the picker-contract render
+ * target for this platform). Parallelism is handoff-driven rather than a
+ * concurrent fan-out, so the review phase runs the reviewers as orchestrated
+ * sub-agents.
+ *
+ * Emits:
+ *   .github/agents/ma-*.agent.md   one custom agent per pipeline persona
+ *   .github/prompts/multi-agent.prompt.md   the /multi-agent orchestration driver
+ *   .vscode/mcp.json   dev-toolkit MCP registration (merged)
+ *
+ * @module pipeline/adapters/copilot-chat-orchestration
+ */
+
+import { writeFileSync } from "fs";
+import { join } from "path";
+import {
+  ensureDir,
+  installPersonaAgents,
+  installSharedRuntime,
+  mergeMcpJson,
+  removeFileAndPrune,
+  removePrefixedFiles,
+  REVIEWER_MODELS,
+  rewriteScriptRefs,
+  uninstallSharedRuntime,
+  unmergeMcpJson,
+} from "./_base.mjs";
+
+const AGENT_PREFIX = "ma-";
+
+/**
+ * @param {{ pipelineSrc: string, target: string }} opts
+ */
+export function installOrchestration({ pipelineSrc, target }) {
+  // The code-reviewer pins a Claude model; every other persona inherits the
+  // picker model (omit `model`). The cross-vendor second reviewer is pinned to
+  // a different vendor so Phase 4 is a 2-model review (Claude + GPT) instead
+  // of single-model.
+  const cm = REVIEWER_MODELS.copilotChat.crossModel;
+  const { agents, names: personaNames } = installPersonaAgents({
+    pipelineSrc,
+    outDir: join(target, ".github", "agents"),
+    prefix: AGENT_PREFIX,
+    fileFor: (name) => `${AGENT_PREFIX}${name}.agent.md`,
+    render: renderAgent,
+    primaryOpts: (persona) => ({
+      model: persona === "code-reviewer" ? REVIEWER_MODELS.copilotChat.primary : null,
+    }),
+    crossReviewer: {
+      model: cm,
+      note: `Cross-vendor reviewer pinned to \`${cm}\` so Phase 4 runs two different models (vs the primary \`ma-code-reviewer\` on \`${REVIEWER_MODELS.copilotChat.primary}\`). Adjust the model labels to ones available in your Copilot plan.`,
+    },
+  });
+
+  const promptsOut = join(target, ".github", "prompts");
+  ensureDir(promptsOut);
+  writeFileSync(join(promptsOut, "multi-agent.prompt.md"), rewriteScriptRefs(renderDriver(personaNames)));
+
+  const mcp = mergeMcpJson(join(target, ".vscode", "mcp.json"), { rootKey: "servers" });
+
+  // Shared runtime so the agents' gate-script references resolve + run.
+  installSharedRuntime(pipelineSrc);
+
+  return { agents, mcp };
+}
+
+/**
+ * @param {{ target: string }} opts
+ */
+export function uninstallOrchestration({ target }) {
+  let removed = removePrefixedFiles(join(target, ".github", "agents"), AGENT_PREFIX, ".agent.md");
+  const promptsDir = join(target, ".github", "prompts");
+  removed += removeFileAndPrune(join(promptsDir, "multi-agent.prompt.md"), promptsDir);
+  unmergeMcpJson(join(target, ".vscode", "mcp.json"), { rootKey: "servers" });
+  if (uninstallSharedRuntime()) removed++;
+  return { removed };
+}
+
+function renderAgent(persona, frontmatter, body, opts = {}) {
+  const description = (frontmatter.description || `multi-agent pipeline ${persona}`).replace(/\n/g, " ").trim();
+  const tier = frontmatter.model || "inherit";
+  // VS Code Copilot Chat has no `inherit` keyword: OMIT `model` to inherit the
+  // picker's model, or pin a specific picker LABEL. (Writing `model: inherit`
+  // would name a non-existent model.) The agent name is derived from the filename.
+  const modelLine = opts.model ? [`model: ${opts.model}`] : [];
+  const fm = [
+    "---",
+    `description: ${JSON.stringify(description)}`,
+    "tools: ['codebase', 'search', 'usages']",
+    ...modelLine,
+    "---",
+    "",
+    `> Pipeline persona \`${persona}\` (intended tier: ${tier}). Transformed for VS Code`,
+    "> Copilot Chat by @mmerterden/multi-agent-pipeline. Read-only analysis/review",
+    "> role; the main agent performs edits. Confirmations use the native approval UI",
+    "> (see refs/picker-contract.md).",
+    ...(opts.note ? ["> ", `> ${opts.note}`] : []),
+    "",
+  ].join("\n");
+  return `${fm}${rewriteScriptRefs(body.trim())}\n`;
+}
+
+function renderDriver(personaNames) {
+  const agentList = personaNames.map((n) => `\`${n}\``).join(", ");
+  return `---
+mode: agent
+description: "Run the multi-agent pipeline in VS Code Copilot Chat."
+---
+
+# /multi-agent  -  run the pipeline in VS Code Copilot Chat
+
+> Installed by @mmerterden/multi-agent-pipeline. Drives the 8-phase pipeline
+> using the custom agents in \`.github/agents/ma-*.agent.md\` and the dev-toolkit
+> MCP server (\`.vscode/mcp.json\`). Confirmations/approvals use VS Code's native
+> tool-approval dialogs (refs/picker-contract.md). Sub-agents available: ${agentList}.
+>
+> GATE SCRIPTS: installed at \`$HOME/.multi-agent/scripts/\` (evidence-gate.mjs,
+> classify-intent.sh, learnings-ledger.mjs, validate-triage.mjs,
+> pre-commit-check.sh); the agents invoke them there. Unlike Claude Code there is
+> no PreToolUse hook forcing them, so they are workflow-enforced (run as steps)
+> rather than OS-blocked.
+
+Input: \${input:task:a Jira id, GitHub issue, repo#N, or free-text task}
+
+Run the phases in order, following every \`.github/instructions/multi-agent-*\` file:
+
+0. **Init** - detect stack, resolve branch (\`bugfix/…\` / \`feature/…\`), confirm scope.
+1. **Analysis** - hand off to \`ma-explorer\`; produce stack / touchedAreas[] / risks[] / summary.
+2. **Planning** - draft the task breakdown; present it and ask the user to Approve / Cancel / edit (native approval dialog). Loop on edits.
+3. **Dev** - implement TDD-first (test -> code -> build), following the instructions; optionally \`ma-dev-critic\` before review.
+4. **Review** - for cross-model coverage hand off to BOTH \`ma-code-reviewer\` (Claude) and \`ma-code-reviewer-x\` (GPT) as separate sessions so the code review runs on two vendors, plus the stack architect (\`ma-ios-architect\` / \`ma-android-architect\` / \`ma-backend-architect\`) and \`ma-security-auditor\` for auth/secret diffs. Merge findings, triage, record the \`consensus\` block (same-model agreement on judgment calls = \`unverified\`), fix accepted blocking/important, re-review.
+5. **Test** - offer an interactive test pass; use the dev-toolkit MCP server for simulator / emulator / web checks.
+6. **Commit** - \`{type}(scope): description\`; never auto-close issues; PR uses \`Ref: #N\`.
+7. **Report** - summarize changes, per-reviewer consensus, and cost.
+
+No "AI / generated by" in code or commits. Attribute each finding to the agent that raised it.
+`;
+}
+
+export default { installOrchestration, uninstallOrchestration };

package/pipeline/adapters/copilot-chat.mjs

@@ -1,11 +1,11 @@
 /**
- * @file GitHub Copilot Chat adapter — emits `.github/copilot-instructions.md`
+ * @file GitHub Copilot Chat adapter  -  emits `.github/copilot-instructions.md`
  * (marker-wrapped) at the project root. Optionally also writes per-skill
  * `.github/instructions/multi-agent-*.instructions.md` files which Copilot
  * Chat picks up as scoped instructions.
  *
  * Note: this is **not** the same as `--copilot` (which targets the Copilot
- * CLI's `~/.copilot/` configuration). Copilot Chat is a different product —
+ * CLI's `~/.copilot/` configuration). Copilot Chat is a different product  -
  * the IDE-side chat that lives in VS Code / GitHub.com / JetBrains, reads
  * repo-scoped instruction files, and has no subagent dispatch. So this
  * adapter ports the knowledge layer only, like cursor/windsurf/cline.
@@ -13,18 +13,21 @@
  * @module pipeline/adapters/copilot-chat
  */
 
-import { existsSync, readdirSync, rmSync, writeFileSync } from "fs";
 import { join } from "path";
 import {
+  collectSkills,
   concatSkills,
   ensureDir,
   inferGlobs,
+  installAdapterFiles,
+  jsonString,
   rel,
   removeManagedBlock,
+  removePrefixedFiles,
   replaceManagedBlock,
-  walkSkills,
   withoutOrchestrationSkills,
 } from "./_base.mjs";
+import { installOrchestration, uninstallOrchestration } from "./copilot-chat-orchestration.mjs";
 
 const NAME = "copilot-chat";
 const MAIN_FILE = ".github/copilot-instructions.md";
@@ -52,74 +55,41 @@ export function install({ pipelineSrc, target, platformFilter = "all" }) {
   // Chat applies it only when the user touches matching globs. Filename
   // convention `<name>.instructions.md` is the GitHub Copilot Chat 2025+ format.
   const perSkillOut = join(target, PER_SKILL_DIR);
-  ensureDir(perSkillOut);
-  let written = 0;
-  for (const skill of skills) {
-    const fileName = `${FILE_PREFIX}${skill.name}.instructions.md`;
-    const outPath = join(perSkillOut, fileName);
-    writeFileSync(outPath, renderInstructionFile(skill));
-    written++;
-  }
+  const written = installAdapterFiles({
+    outDir: perSkillOut,
+    items: skills,
+    fileFor: (skill) => `${FILE_PREFIX}${skill.name}.instructions.md`,
+    render: renderInstructionFile,
+  });
   console.log(
     `    -> [copilot-chat] ${written} per-skill instruction files in ${rel(target, perSkillOut)}`,
   );
+
+  // Orchestration layer  -  custom agents + /multi-agent prompt + MCP, so the
+  // full pipeline runs in VS Code Copilot Chat agent mode.
+  const orch = installOrchestration({ pipelineSrc, target });
+  console.log(
+    `    -> [copilot-chat] orchestration: ${orch.agents} custom agents (.github/agents/ma-*) + /multi-agent prompt + .vscode/mcp.json (${orch.mcp})`,
+  );
 }
 
 /**
  * @param {{ target: string }} opts
  */
 export function uninstall({ target }) {
-  const mainPath = join(target, MAIN_FILE);
-  const status = removeManagedBlock(mainPath);
+  const status = removeManagedBlock(join(target, MAIN_FILE));
+  const removed = removePrefixedFiles(join(target, PER_SKILL_DIR), FILE_PREFIX, ".instructions.md");
+  const orch = uninstallOrchestration({ target });
 
-  const perSkillOut = join(target, PER_SKILL_DIR);
-  let removed = 0;
-  if (existsSync(perSkillOut)) {
-    for (const entry of readdirSync(perSkillOut, { withFileTypes: true })) {
-      if (!entry.isFile()) continue;
-      if (entry.name.startsWith(FILE_PREFIX) && entry.name.endsWith(".instructions.md")) {
-        rmSync(join(perSkillOut, entry.name), { force: true });
-        removed++;
-      }
-    }
-    try {
-      if (readdirSync(perSkillOut).length === 0) {
-        rmSync(perSkillOut, { recursive: true, force: true });
-      }
-    } catch {
-      /* non-fatal */
-    }
-  }
-
-  // Don't touch .github itself — user may have other CI configs there
-  return { mainStatus: status, perSkillRemoved: removed };
+  // Don't touch .github itself  -  user may have other CI configs there
+  return { mainStatus: status, perSkillRemoved: removed + orch.removed };
 }
 
 function collectKnowledgeSkills(pipelineSrc, platformFilter) {
-  const skillsRoot = join(pipelineSrc, "skills");
-  const sources = [
-    join(skillsRoot, "shared", "core"),
-    join(skillsRoot, "shared", "external"),
-    join(skillsRoot, "figma-common"),
-  ];
-  if (platformFilter === "ios" || platformFilter === "all") {
-    sources.push(join(skillsRoot, "figma-ios"));
-  }
-  if (platformFilter === "android" || platformFilter === "all") {
-    sources.push(join(skillsRoot, "figma-android"));
-  }
-  const all = [];
-  for (const src of sources) all.push(...walkSkills(src));
-
-  const knowledge = withoutOrchestrationSkills(all);
-  if (platformFilter === "all") return knowledge;
-  return knowledge.filter((s) => {
-    const globs = inferGlobs(s.name);
-    if (!globs) return true;
-    if (platformFilter === "ios") return globs.includes("swift");
-    if (platformFilter === "android") return globs.includes("kt");
-    return true;
-  });
+  const sources = ["shared/core", "shared/external", "figma-common"];
+  if (platformFilter === "ios" || platformFilter === "all") sources.push("figma-ios");
+  if (platformFilter === "android" || platformFilter === "all") sources.push("figma-android");
+  return withoutOrchestrationSkills(collectSkills(pipelineSrc, platformFilter, { sources }));
 }
 
 /**
@@ -129,11 +99,11 @@ function renderMainBlock(skills) {
   const header = `# multi-agent-pipeline (GitHub Copilot Chat)
 
 > Installed by @mmerterden/multi-agent-pipeline. Repo-scoped instructions for
-> GitHub Copilot Chat. The 8-phase pipeline orchestration (parallel review,
-> autopilot, subagent dispatch) is **not portable** to Copilot Chat — for
-> the full pipeline, use Claude Code or Copilot CLI. What you get here:
-> the knowledge layer (rules + skills catalog) loaded automatically into
-> every Copilot Chat conversation in this repo.
+> GitHub Copilot Chat. This block is the knowledge layer (rules + skills) loaded
+> into every conversation; the 8-phase orchestration runs via the custom agents
+> in \`.github/agents/ma-*.agent.md\` and the \`/multi-agent\` prompt
+> (\`.github/prompts/multi-agent.prompt.md\`) in VS Code Copilot Chat agent mode.
+> Confirmations use VS Code's native approval dialogs (refs/picker-contract.md).
 
 `;
   return header + concatSkills(skills);
@@ -151,8 +121,4 @@ function renderInstructionFile(skill) {
   return `${fmLines.join("\n")}\n# ${skill.name}\n\n${skill.body.trim()}\n`;
 }
 
-function jsonString(s) {
-  return JSON.stringify(s);
-}
-
 export default { name: NAME, install, uninstall };

package/pipeline/adapters/cursor-orchestration.mjs

@@ -0,0 +1,152 @@
+/**
+ * @file Cursor orchestration layer  -  emits the FULL-pipeline artifacts (not
+ * just the knowledge layer) that let Cursor run the multi-agent pipeline:
+ *
+ *   .cursor/agents/ma-*.md     one Cursor subagent per pipeline persona
+ *                              (explorer, code-reviewer, the architects,
+ *                              security-auditor, dev-critic, task-clarifier),
+ *                              transformed from pipeline/agents/*.md.
+ *   .cursor/commands/multi-agent.md   the orchestration driver: the 8-phase
+ *                              flow adapted to Cursor's runtime (parallel
+ *                              subagent dispatch for review, ask-choice picker
+ *                              fallback for the approval gate).
+ *   .cursor/mcp.json           registers the dev-toolkit MCP server (merged,
+ *                              never clobbering the user's other servers).
+ *
+ * Cursor 2.4+ supports `.cursor/agents/*.md` (MD + YAML frontmatter, parallel
+ * dispatch up to 8) and `.cursor/commands/*.md`, so the orchestration is
+ * portable - the gaps vs Claude Code are the picker (degraded to ask-choice /
+ * MCP) and hard blocking gates (advisory rules + CI). See refs/picker-contract.md.
+ *
+ * @module pipeline/adapters/cursor-orchestration
+ */
+
+import { writeFileSync } from "fs";
+import { join } from "path";
+import {
+  ensureDir,
+  installPersonaAgents,
+  installSharedRuntime,
+  mergeMcpJson,
+  removeFileAndPrune,
+  removePrefixedFiles,
+  REVIEWER_MODELS,
+  rewriteScriptRefs,
+  uninstallSharedRuntime,
+  unmergeMcpJson,
+} from "./_base.mjs";
+
+const AGENT_PREFIX = "ma-";
+
+/**
+ * @param {{ pipelineSrc: string, target: string }} opts
+ * @returns {{ agents: number, command: boolean, mcp: "created"|"merged"|"skipped" }}
+ */
+export function installOrchestration({ pipelineSrc, target }) {
+  // 1. Transform each pipeline persona into a Cursor subagent. The cross-vendor
+  //    second reviewer is a code-reviewer pinned to a different model so Phase 4
+  //    is a 2-model review (the primary inherits the user's model, usually
+  //    Claude; the -x variant pins gpt-5.5) instead of single-model.
+  const cm = REVIEWER_MODELS.cursor.crossModel;
+  const { agents } = installPersonaAgents({
+    pipelineSrc,
+    outDir: join(target, ".cursor", "agents"),
+    prefix: AGENT_PREFIX,
+    fileFor: (name) => `${AGENT_PREFIX}${name}.md`,
+    render: renderCursorAgent,
+    crossReviewer: {
+      name: `${AGENT_PREFIX}code-reviewer-x`,
+      model: cm,
+      note: `Cross-vendor reviewer pinned to \`${cm}\` so Phase 4 runs two different models (vs the primary \`ma-code-reviewer\`, which inherits your selected model). Verify the model id matches your Cursor build.`,
+    },
+  });
+
+  // 2. Orchestration command (script refs rewritten to the shared runtime).
+  const cmdOut = join(target, ".cursor", "commands");
+  ensureDir(cmdOut);
+  writeFileSync(join(cmdOut, "multi-agent.md"), rewriteScriptRefs(ORCHESTRATION_COMMAND));
+
+  // 3. MCP server registration (merge into existing .cursor/mcp.json).
+  const mcp = mergeMcpJson(join(target, ".cursor", "mcp.json"));
+
+  // 4. Shared runtime: install the gate scripts/lib/schemas so the agents'
+  //    `$HOME/.multi-agent/scripts/...` references resolve and the gates run.
+  const shared = installSharedRuntime(pipelineSrc);
+
+  return { agents, command: true, mcp, sharedRuntime: shared.trees.length > 0 };
+}
+
+/**
+ * @param {{ target: string }} opts
+ */
+export function uninstallOrchestration({ target }) {
+  let removed = removePrefixedFiles(join(target, ".cursor", "agents"), AGENT_PREFIX, ".md");
+  const cmdDir = join(target, ".cursor", "commands");
+  removed += removeFileAndPrune(join(cmdDir, "multi-agent.md"), cmdDir);
+  // Remove only OUR MCP server entry; leave the user's other servers + file.
+  unmergeMcpJson(join(target, ".cursor", "mcp.json"));
+  // Remove the shared runtime (100% pipeline-owned).
+  if (uninstallSharedRuntime()) removed++;
+  return { removed };
+}
+
+/**
+ * Map a pipeline persona's Opus/Sonnet/Haiku tier to a Cursor `model` value.
+ * Cursor runs the user's selected model, so we default to `inherit` and record
+ * the intended tier in the body - the orchestrator picks per-phase if the user
+ * has multiple models configured.
+ */
+function renderCursorAgent(persona, frontmatter, body, opts = {}) {
+  const name = opts.name || `${AGENT_PREFIX}${persona}`;
+  const model = opts.model || "inherit";
+  const description = (frontmatter.description || `multi-agent pipeline ${persona}`).replace(/\n/g, " ").trim();
+  const tier = frontmatter.model || "inherit";
+  const fm = [
+    "---",
+    `name: ${name}`,
+    `description: ${JSON.stringify(description)}`,
+    `model: ${model}`,
+    "readonly: true",
+    "---",
+    "",
+    `> Pipeline persona \`${persona}\` (intended tier: ${tier}). Transformed for Cursor by`,
+    "> @mmerterden/multi-agent-pipeline. Read-only analysis/review role; the main",
+    "> agent performs edits. Picker/approval steps degrade per refs/picker-contract.md.",
+    ...(opts.note ? ["> ", `> ${opts.note}`] : []),
+    "",
+  ].join("\n");
+  // Rewrite logical pipeline/scripts refs in the persona body to the absolute
+  // shared-runtime path so the gate scripts resolve from any cwd.
+  return `${fm}${rewriteScriptRefs(body.trim())}\n`;
+}
+
+const ORCHESTRATION_COMMAND = `# /multi-agent  -  run the pipeline in Cursor
+
+> Installed by @mmerterden/multi-agent-pipeline. Drives the 8-phase pipeline
+> using Cursor subagents (\`.cursor/agents/ma-*.md\`) and the dev-toolkit MCP
+> server. Picker/approval steps follow refs/picker-contract.md (Cursor Plan-mode
+> question UI where available, else a numbered choice the agent presents inline
+> numbered prompt). Gate scripts are installed at \`$HOME/.multi-agent/scripts/\`
+> (evidence-gate.mjs, classify-intent.sh, learnings-ledger.mjs, validate-triage.mjs,
+> pre-commit-check.sh) and the subagents invoke them there. Unlike Claude Code
+> there is no PreToolUse hook forcing them, so they are workflow-enforced (run as
+> steps) rather than OS-blocked.
+
+Input: \`$ARGUMENTS\` (a Jira id, GitHub issue, repo#N, or a free-text task).
+
+## Phases
+
+0. **Init** - detect stack, resolve branch (\`bugfix/…\` or \`feature/…\`), confirm scope with the user.
+1. **Analysis** - dispatch the \`ma-explorer\` subagent (read-only) to map touched areas, risks, and the stack; produce the analysis object (see analysis-output schema in the rules).
+2. **Planning** - draft a task breakdown. Present it and ask the user to **Approve / Cancel / edit** via the picker contract (Plan-mode UI or a numbered prompt). Edits loop until approved.
+3. **Dev** - the MAIN agent implements TDD-first (test, then code, then build), following \`.cursor/rules/*\`. Optionally run \`ma-dev-critic\` before review.
+4. **Review** - dispatch the reviewer subagents IN PARALLEL for cross-model coverage: \`ma-code-reviewer\` (your selected model) AND \`ma-code-reviewer-x\` (pinned to a different vendor) so the code review runs on two models, plus the stack architect (\`ma-ios-architect\` / \`ma-android-architect\` / \`ma-backend-architect\`) and \`ma-security-auditor\` when the diff touches auth/secrets. Merge their findings, then triage (accept / defer / reject); record the \`consensus\` block (treat same-model agreement on judgment calls as \`unverified\`). Fix accepted blocking/important findings and re-review.
+5. **Test** - offer an interactive test pass via the picker. Use the dev-toolkit MCP server (simulator / emulator / web) for UI checks.
+6. **Commit** - \`{type}(scope): description\`; never auto-close issues; PR uses \`Ref: #N\`.
+7. **Report** - summarize what changed, the review consensus (per reviewer), and cost.
+
+## Rules
+Follow every \`.cursor/rules/multi-agent-*\` file (code style, TDD, security, review priorities). Attribute each finding to the subagent that produced it. Do not invent design values; cite the analysis. No "AI/generated by" in code or commits.
+`;
+
+export default { installOrchestration, uninstallOrchestration };