@mmerterden/multi-agent-pipeline 12.11.0 → 13.1.0

package/CHANGELOG.md

@@ -16,6 +16,185 @@ Internal file-layout changes that don't affect the slash-command surface are sti
 
 ## [Unreleased]
 
+## [13.1.0] - 2026-07-27
+
+Six gates, from one branch that spent half its commits on rework.
+
+A Figma-driven screen task was built through the generic development path. The cause
+chain, measured from the run's own artefacts: Phase 0 reported `completed` having
+written only `tracker-state.json`, so `agent-state.json` and its `taskType` never
+existed, so Phase 3's component dispatch could not fire. The stack plugin already
+ships `create-screen`, `figma-validate` (7 criteria including design-token compliance
+and Code Connect strategy) and `figma-review` (14-item checklist)  -  none of them ran.
+Padding came out 16 where the frame said `Spacing/12`. Three of six commits were fixes,
+the last a full sheet rebuild.
+
+Nothing here is a new capability. Every gate enforces a rule that already existed or
+invokes a skill that was already written but never called.
+
+### Added
+
+- **`phase0-exit-gate.mjs`, blocking.** Phase 0 may not be marked completed until
+  `agent-state.json` exists with a `taskType`, and a Figma reference forces
+  `taskType: "component"` plus a recorded `figmaAccess.tier`. A phase that reports
+  success without its output is worse than one that fails: every later phase then
+  reasons from a field that is not there. The evaluator is pure and exported, so the
+  gate is testable without reproducing a run.
+- **Phase 4 Step 2.8, visual conformance gate.** Runs `figma-review` and
+  `/multi-agent:design-check` for component/screen work, with the coverage gate, and
+  asserts Code Connect was **published** rather than merely written  -  a
+  `*.figma.swift` on disk with "Not published" in Figma is a binding that exists for
+  nobody. `design-check` had been a command with no phase invoking it, so the only
+  thing standing between a build and visual drift was the user opening the app.
+- **Phase 1 Step 1.45, reuse discovery, blocking.** Search for an existing wrapper,
+  entity, mapper or screen before proposing a new one. One run wrote a repository over
+  an endpoint a sibling domain already wrapped **with its country parameter**, called
+  the generated method without it, and re-invented an entity the module already had.
+  "Copy X and rename it" is the reuse answer, not a hint.
+- **`smoke-component-dispatch-gates.sh`** (12 assertions) pins all six.
+
+### Changed
+
+- **Component dispatch halts instead of degrading.** The contract used to send an
+  incomplete-state component task down the generic TDD path while the next sentence
+  said "never silently skip the Figma work"  -  taking the generic path *is* skipping
+  it. That wording authorised the exact failure above.
+- **Dispatch routes on scope, not just platform.** A screen and a component are
+  different jobs and the plugin ships a skill for each; routing a screen to the
+  component skill is why one run produced entities and a mapper but left the screen
+  half-wired. `figma-validate` now runs before the create skill.
+- **Phase 1 captures spacing by token name, per atom.** Phase 3 is forbidden from
+  calling Figma, so a pixel number  -  or a missing entry  -  is unrecoverable later. A
+  UI frame with no spacing entries is a capture failure, not an empty frame.
+- **Phase 3 records that generated trees are not editable.** A mock fixture went into
+  the generated tree; the fix moved it to the custom tree and registered the scenario
+  in the generated index. Same content, wrong side of the generator, and the Debug menu
+  never showed it.
+- **Fast modes warn when handed an analysis document.** `--dev` skips Analysis and
+  Planning by design, so there is no phase that turns a document into a plan. The doc
+  becomes context for one pass and work lands in whatever order it was read.
+
+
+## [13.0.0] - 2026-07-27
+
+> **Why major and not minor.** The additions here are additive, but two defaults
+> changed in ways a reasonable workflow would notice: `install --all` now writes a
+> third tree (`~/.codex`) and registers an MCP server via `codex mcp add`, and the
+> cross-CLI contract changed shape (the parity axis is per-host now, so an auditor
+> comparing Codex on skill directories would read a correct install as drift).
+> Per the versioning policy that is a changed default, not a new option.
+
+
+Codex CLI becomes a third supported host, and a new pre-submission validation command.
+
+### Added
+
+- **Codex CLI as a first-class target** (`install --codex`, included in `--all`).
+  The v9.7.0 adapter was deleted in v10.7.0 because Codex was then a degraded
+  consumer with no sub-agent fan-out. Codex 0.145 has skills, parallel sub-agents
+  with per-agent model and reasoning effort, hooks, MCP and a plugin marketplace,
+  so it earns the same treatment as the other two rather than an adapter.
+  `install/codex.mjs` writes `~/.codex/{skills/multi-agent,multi-agent-refs,
+  agents/*.toml,prompts/multi-agent.md,scripts,lib,schemas,rules}` plus a managed
+  span in `~/.codex/AGENTS.md`, and registers the dev-toolkit MCP server through
+  `codex mcp add` rather than hand-merging TOML that Codex owns.
+- **`/multi-agent:testflight-validation`** (command 43). Three gates, each seeing
+  what the others structurally cannot: the static 18-rule archive audit, Apple's
+  own `altool --validate-app`, and a Review-Guidelines check against repo evidence.
+  ITMS codes are mapped to the rule each implies. It validates only  -  never
+  `--upload-app`  -  so a validation run cannot ship a build by accident.
+- **App Store Connect credentials in `/multi-agent:setup`**, inside the Step 1
+  discovery / Step 2 mapping / Step 3b onboarding flow alongside Jira and
+  Bitbucket, not as a late add-on: a user who already has one in their keychain
+  gets it mapped automatically. Tier 1 is an API key, tier 2 an Apple ID plus an
+  app-specific password  -  which matters because creating an API key needs an
+  Admin or App Manager role many developers on a corporate team do not have.
+
+### Changed
+
+- **Codex takes the Claude Code thin-dispatcher shape, and has to.** Measured on
+  Codex 0.145: installing one plugin declaring 142 skills took the assembled
+  skills block from 11 skills / 4,710 bytes to 83 / 22,111, surfacing only **75 of
+  142** and **evicting an unrelated user-scope skill**. Shipping the 43
+  sub-commands as peer skills would silently lose pipeline commands next to any
+  stack toolkit. The pipeline contributes exactly one skill on Codex and keeps the
+  specs as refs; `smoke-install-layout.sh` fails if a second one appears.
+- Phase 4 reviewer matrix gains a Codex column (gpt-5.6 @ xhigh / gpt-5.4 /
+  gpt-5.6 @ medium, triage at max) with two measured constraints written into the
+  contract: a `spawn_agent` that sets `model` without `fork_turns: "none"`
+  **silently inherits the parent model**, collapsing the panel onto one
+  perspective; and 4 concurrency slots *including the orchestrator* make three
+  reviewers the ceiling. Single-vendor caveat recorded  -  consensus among three
+  OpenAI models is weaker evidence than the same consensus on a two-vendor host.
+- `tracker-contract.md` gains the `codex` visual channel: the native `update_plan`
+  tool, with its no-parallel-call and no-plan-mode caveats.
+- Cross-CLI contract retitled for three hosts; parity axis for Codex is the **ref
+  set**, not the skill set, because comparing skill directories would demand the
+  layout that breaks it.
+
+### Fixed
+
+- **The remote reachability gate blamed the network for every failure.** Any
+  non-zero `git ls-remote` exit was reported as `unreachable (VPN/DNS)`, so a
+  missing-credential error that returns in under a second sent the user to enable
+  a VPN that could not help, and offered a stale-base fallback for a cause that
+  had nothing to do with staleness. Failures are now classified from stderr
+  (credential / network / wrong remote / unknown), the observed line is printed
+  next to the classification, and only the network case offers the cached ref.
+- **The Phase 0 branch-collision probe read a failed probe as "no collision".**
+  With `2>/dev/null` and an empty-output test, an auth or network failure was
+  indistinguishable from "the ref does not exist", so the run created a branch
+  that already existed on the remote  -  surfacing as a rejected push at Phase 6,
+  far from its cause. Exit codes are now distinguished (0 exists, 2 free, anything
+  else unknown-and-recorded).
+- **`/multi-agent:update` deleted the Codex prompt on every run**, pruning
+  `~/.codex/prompts/multi-agent.md` as a retired v9.7.0 adapter leftover.
+- **Uninstall could delete trailing user content in `~/.codex/AGENTS.md`.**
+  `stripManagedBlock` matched only the Copilot end marker, so on the Codex marker
+  it fell through to a heading-bounded fallback that returns nothing when the
+  trailing content has no top-level heading. Verified against the pre-fix path.
+- `smoke-own-punctuation.sh` failed on HEAD: `test/tracker-title-entities.test.mjs`
+  (added in v12.11.0) holds the banned characters as its own assertion list and
+  was never allowlisted.
+- **Half-English pickers on Turkish runs: six shipped files contradicted the
+  canonical language matrix.** `rules.md` is unambiguous  -  `AskUserQuestion`
+  `question` and `options[].description` render in `outputLanguage`, only `label`,
+  `header` and host chrome are pinned to English. But `/multi-agent:setup` Step 0
+  claimed `promptLanguage` governs "interactive pickers and prompts ... Picker UI is
+  always English", `/multi-agent:language` claimed "confirmation prompts ... are
+  authored in English. Only the assistant's free-form replies follow
+  `outputLanguage`", and four more files said variations of the same. Those are the
+  two commands a user goes to *configure* this, so the model followed whichever
+  canonical-looking doc it read first and gate questions came out English. All six
+  corrected to describe `promptLanguage`'s real scope: the button and chip chrome,
+  never the question a user reads.
+
+### Gates (continued)
+
+- New `smoke-language-matrix.sh`: asserts `rules.md` still pins the per-field
+  matrix, then greps every shipped command / skill / ref for the seven phrasings
+  that actually shipped and contradicted it. Two authoritative docs giving opposite
+  answers is a spec with two answers, not a wording nit  -  the gate found a sixth
+  violation (`_input-parser.md`) that the manual sweep had missed.
+
+### Gates
+
+- New `smoke-codex-install.sh` (37 assertions): install/uninstall round-trip into a
+  HOME seeded with user content, asserting every artifact lands, every rewritten
+  `$HOME/.codex` path resolves, generated agent TOML parses, and user content is
+  byte-identical afterwards.
+- `smoke-install-layout.sh` extended to three targets, including a check that every
+  concrete `$HOME/.codex` reference **resolves on disk**. The earlier "no `.claude`
+  references remain" check was blind to a wrongly-rewritten path, which is how
+  `commands/multi-agent.md` became `multi-agent-refs/commands.md`  -  well-formed,
+  pointing at nothing. A miss is classified by whether the Claude counterpart
+  exists, so broken-by-rewrite fails and broken-upstream is only reported.
+- New `test/codex-install.test.mjs` (24 assertions) locks the path-rewrite map,
+  the frontmatter transform, the persona tier map, and managed-block trailing
+  content, including regressions for both rewrite defects above.
+- `MULTI_AGENT_SKIP_MCP_REGISTER=1` makes an install hermetic, so the layout
+  fingerprint no longer depends on whether `codex` is on PATH.
+
 ## [12.11.0] - 2026-07-26
 
 ### Tracker tile titles rendered HTML entities

package/README.md

@@ -6,15 +6,15 @@
 [![Zero Dependencies](https://img.shields.io/badge/dependencies-0-brightgreen)](https://github.com/mmerterden/multi-agent-pipeline/blob/main/package.json)
 [![OpenSSF Scorecard](https://api.scorecard.dev/projects/github.com/mmerterden/multi-agent-pipeline/badge)](https://scorecard.dev/viewer/?uri=github.com/mmerterden/multi-agent-pipeline)
 
-An 8-phase AI development pipeline for **Claude Code** and **Copilot CLI**. Drives a Jira issue or GitHub URL to a merged PR in one command - analysis → plan → TDD → review → test → commit → PR - with multi-repo orchestration, a plan-approval gate, CLI-aware parallel review, and store-compliance checks. Component and Figma-to-code work is dispatched to the per-stack marketplace plugins (iOS/SwiftUI, Android/Compose) rather than bundled, so component skills live in one place.
+An 8-phase AI development pipeline for **Claude Code**, **Copilot CLI** and **Codex CLI**. Drives a Jira issue or GitHub URL to a merged PR in one command - analysis → plan → TDD → review → test → commit → PR - with multi-repo orchestration, a plan-approval gate, CLI-aware parallel review, and store-compliance checks. Component and Figma-to-code work is dispatched to the per-stack marketplace plugins (iOS/SwiftUI, Android/Compose) rather than bundled, so component skills live in one place.
 
-Runs natively on Claude Code and Copilot CLI. macOS / Linux / Windows. Zero runtime dependencies.
+Runs natively on Claude Code, Copilot CLI and Codex CLI. macOS / Linux / Windows. Zero runtime dependencies.
 
 ## Quick Start
 
 ```bash
 # from the public registry (no auth)
-npx @mmerterden/multi-agent-pipeline install --all   # Claude Code + Copilot CLI
+npx @mmerterden/multi-agent-pipeline install --all   # Claude Code + Copilot CLI + Codex CLI
 
 # then, once:
 /multi-agent:setup          # keychain token scan + git identity + default stack
@@ -63,8 +63,10 @@ The discipline behind all of this - bounded loops, evidence gates, token-budgete
 | Dev | `/multi-agent:dev "task"` | Init → Dev → Commit → Report |
 | Local | `/multi-agent:local "task"` | Full pipeline, current branch (no worktree) |
 | Finish | `/multi-agent:finish` | Run the review→test→commit→report tail over local work |
+| Audit | `/multi-agent:design-check` | Mock-mode vs Figma conformance, local-only |
+| Audit | `/multi-agent:testflight-validation` | Pre-submission gates for a TestFlight build: static archive audit → Apple's `altool --validate-app` → Review-Guidelines check. Validates only, never uploads |
 
-Helpers: `setup`, `status`, `resume #N`, `review`, `test`, `channels`, `stack`, `update`, `sync`, `refactor`, `jira`, `issue`, `analysis`, `create-jira`, `save`, `routines`, `forget`. Full list: `/multi-agent:help`.
+Helpers: `setup`, `status`, `resume #N`, `review`, `test`, `channels`, `stack`, `update`, `sync`, `refactor`, `jira`, `issue`, `analysis`, `create-jira`, `save`, `routines`, `forget`. 43 commands in all  -  full list: `/multi-agent:help`.
 
 ## Stacks
 
@@ -78,15 +80,29 @@ This enables the matching plugin (+ the shared `ai-common` plugin) in the repo's
 
 ## Tool support
 
-The pipeline runs natively on **Claude Code** and **Copilot CLI** - both install from the same `pipeline/skills/` source and get identical coverage.
+The pipeline runs natively on **Claude Code**, **Copilot CLI** and **Codex CLI** - all three install from the same `pipeline/` source and get the same 43 commands.
 
-| Tool | Flag | Notes |
+| Tool | Flag | What it installs |
 |---|---|---|
 | Claude Code | `--claude` (default) | slash commands + skills + agents + `PreToolUse` secret-scan hook |
-| Copilot CLI | `--copilot` | instructions + skills + scripts |
+| Copilot CLI | `--copilot` | instructions + 43 sub-command skills + scripts |
+| Codex CLI | `--codex` | one router skill + 43 specs as refs + 8 agent TOML + `AGENTS.md` block + `codex mcp add` |
 
 Filter skills by stack with `--platform=ios\|android\|all`.
 
+**Why Codex gets one skill and not 43.** Codex assembles every discovered skill's name
+and description into a single prompt block and drops entries when it overflows, with no
+error. Measured on 0.145: installing one plugin that declares 142 skills surfaced only
+75 of them and evicted an unrelated user skill. So on Codex the pipeline ships a single
+`multi-agent` router and keeps the sub-command specs as reference files that cost
+nothing until read - same commands, same behaviour, a layout the host can actually hold.
+
+Reviewer sets differ because the available models do: Claude Code runs 2 reviewers
+(Fable + Sonnet), Copilot CLI 3 (Opus + GPT-5.4 + Sonnet), Codex CLI 3 (gpt-5.6 at
+xhigh, gpt-5.4, gpt-5.6 at medium). Codex is single-vendor, so consensus among its three
+is weaker evidence than the same consensus on a two-vendor host, and the triage note
+says so.
+
 ## Tokens & integrations
 
 `setup` scans your OS keychain and maps each token by a **logical name** (e.g. `jira`) to its real keychain entry - the pipeline resolves tokens through that mapping (`credential-store.sh`), so literal keychain names never appear in synced files. Tokens stay in the keychain (macOS Keychain / Windows Credential Manager / Linux libsecret), are **never committed or logged**, and are all **optional** - the pipeline asks for any it needs at Phase 0.
@@ -102,6 +118,7 @@ Filter skills by stack with `--platform=ios\|android\|all`.
 | `firebase` | Firebase config (base64 JSON) for Firebase projects | as needed |
 | `jenkins` | CI trigger / status | build / deploy |
 | `npm` | package publish (mostly CI) | release |
+| `appstore_connect_*` | TestFlight / App Store pre-submission validation (optional, iOS) | `testflight-validation` |
 
 The **secret scan** runs as a `PreToolUse` hook on Claude Code (hard-blocks a commit on a hit) and as a pre-push check elsewhere.
 

package/index.js

@@ -50,7 +50,8 @@ if (command === "--version" || command === "-v" || command === "version") {
   Install:
     npx @mmerterden/multi-agent-pipeline install              Install for Claude Code (default)
     npx @mmerterden/multi-agent-pipeline install --copilot    Install for Copilot CLI
-    npx @mmerterden/multi-agent-pipeline install --all        Both Claude + Copilot
+    npx @mmerterden/multi-agent-pipeline install --codex      Install for Codex CLI
+    npx @mmerterden/multi-agent-pipeline install --all        Claude + Copilot + Codex
     npx @mmerterden/multi-agent-pipeline install --link       Use symlinks (saves tokens, dev mode)
 
   Uninstall (token-preserving - Keychain/Credential Manager untouched):
@@ -58,7 +59,8 @@ if (command === "--version" || command === "-v" || command === "version") {
     npx @mmerterden/multi-agent-pipeline uninstall --yes      Skip prompt
     npx @mmerterden/multi-agent-pipeline uninstall --dry-run  Report what would be removed
     npx @mmerterden/multi-agent-pipeline uninstall --claude   Only Claude Code
-    npx @mmerterden/multi-agent-pipeline uninstall --cursor   Legacy pre-v10.7 adapter-file cleanup (also --copilot-chat / --antigravity / --codex; --target=<path> overrides cwd)
+    npx @mmerterden/multi-agent-pipeline uninstall --codex    Only Codex CLI
+    npx @mmerterden/multi-agent-pipeline uninstall --cursor   Legacy pre-v10.7 adapter-file cleanup (also --copilot-chat / --antigravity; --target=<path> overrides cwd)
 
   Help:
     npx @mmerterden/multi-agent-pipeline help
@@ -72,6 +74,7 @@ if (command === "--version" || command === "-v" || command === "version") {
   After installation:
     Claude Code:  /multi-agent "MOBILE-123"
     Copilot CLI:  Describe your task naturally - pipeline instructions are loaded
+    Codex CLI:    /multi-agent "MOBILE-123"  (or $multi-agent)
 
   More info: https://github.com/mmerterden/multi-agent-pipeline
   `);

package/install/_codex-agents.mjs

@@ -0,0 +1,211 @@
+/**
+ * Persona -> Codex subagent transform.
+ *
+ * Claude Code and Copilot CLI read the personas in `pipeline/agents/` directly
+ * as Markdown-with-frontmatter. Codex CLI wants one TOML file per agent under
+ * `$CODEX_HOME/agents/`, with the prompt body in `developer_instructions` and
+ * the model expressed as an OpenAI model id plus a reasoning effort.
+ *
+ * The `.md` files stay the single source of truth: this transform runs at
+ * install time only. Nothing edits a persona at runtime (see the non-goals in
+ * `multi-agent-refs/features/model-fallback.md`).
+ *
+ * @module install/_codex-agents
+ */
+
+import { existsSync, readFileSync, readdirSync, rmSync } from "fs";
+import { join } from "path";
+
+import { ensureDir, ensureRealDir, isDryRun, writeFile } from "./_common.mjs";
+
+/**
+ * Persona tier -> Codex model + reasoning effort.
+ *
+ * The pipeline's ladder is `fable -> opus -> sonnet -> haiku`. Codex offers no
+ * Anthropic models, so each tier maps onto an OpenAI model plus an effort
+ * setting: effort carries the depth distinction that the model id carries on
+ * Claude Code. Keep this table in sync with the Codex column of the Phase 4
+ * reviewer matrix and with `pipeline/scripts/cost-table.json`.
+ */
+export const CODEX_TIER_MAP = Object.freeze({
+  fable: { model: "gpt-5.6", reasoning_effort: "xhigh" },
+  opus: { model: "gpt-5.6", reasoning_effort: "high" },
+  sonnet: { model: "gpt-5.4", reasoning_effort: "medium" },
+  haiku: { model: "gpt-5.6-terra", reasoning_effort: "low" },
+});
+
+/** Fallback when a persona declares no recognizable tier. */
+const DEFAULT_TIER = "sonnet";
+
+/**
+ * Split a persona file into its frontmatter map and body.
+ *
+ * Deliberately a minimal parser, not a YAML engine: persona frontmatter is a
+ * flat `key: value` map with optionally double-quoted values, and adding a YAML
+ * dependency to the installer for eight files is not worth it.
+ *
+ * @param {string} raw - full file content
+ * @returns {{front: Record<string,string>, body: string}}
+ */
+export function parsePersona(raw) {
+  const front = {};
+  const lines = raw.split("\n");
+  if (lines[0]?.trim() !== "---") return { front, body: raw.trim() };
+
+  let i = 1;
+  for (; i < lines.length; i++) {
+    if (lines[i].trim() === "---") {
+      i++;
+      break;
+    }
+    const m = /^([A-Za-z][A-Za-z0-9_-]*):\s*(.*)$/.exec(lines[i]);
+    if (!m) continue;
+    let value = m[2].trim();
+    if (value.startsWith('"') && value.endsWith('"') && value.length >= 2) {
+      value = value.slice(1, -1);
+    }
+    front[m[1]] = value;
+  }
+  return { front, body: lines.slice(i).join("\n").trim() };
+}
+
+/**
+ * Encode a string as a TOML value.
+ *
+ * Multi-line bodies use a literal string (`'''`), which needs no escaping at
+ * all. If a body ever contains `'''` the literal form is unusable, so fall back
+ * to a basic multi-line string with the three sequences TOML requires escaping.
+ * Without that guard a future persona could silently emit invalid TOML.
+ *
+ * @param {string} s
+ * @returns {string} TOML-quoted scalar
+ */
+export function tomlString(s) {
+  if (!s.includes("\n")) {
+    return JSON.stringify(s);
+  }
+  if (!s.includes("'''")) {
+    return `'''\n${s}\n'''`;
+  }
+  const escaped = s.replace(/\\/g, "\\\\").replace(/"""/g, '\\"\\"\\"');
+  return `"""\n${escaped}\n"""`;
+}
+
+/**
+ * Render one persona as a Codex agent TOML document.
+ *
+ * @param {string} name - agent name (persona filename stem)
+ * @param {string} raw - persona file content
+ * @returns {string} TOML
+ */
+export function renderCodexAgent(name, raw) {
+  const { front, body } = parsePersona(raw);
+  const tier = front.preferredModel || front.model || DEFAULT_TIER;
+  const mapped = CODEX_TIER_MAP[tier] || CODEX_TIER_MAP[DEFAULT_TIER];
+
+  const lines = [
+    GENERATED_MARKER,
+    `# Source of truth: pipeline/agents/${name}.md - edit that, then re-install.`,
+    "",
+    `name = ${tomlString(name)}`,
+    `description = ${tomlString(front.description || name)}`,
+    `model = ${tomlString(mapped.model)}`,
+    `model_reasoning_effort = ${tomlString(mapped.reasoning_effort)}`,
+    `developer_instructions = ${tomlString(body)}`,
+    "",
+  ];
+  return lines.join("\n");
+}
+
+/**
+ * Generate `$CODEX_HOME/agents/<persona>.toml` for every persona.
+ *
+ * Only pipeline-owned files are removed before writing - `~/.codex/agents/`
+ * also holds user-authored agents, so the directory is never wiped. The owned
+ * name set is derived from the source tree so it cannot go stale.
+ *
+ * @param {string} agentsSrc - `pipeline/agents`
+ * @param {string} dest - `$CODEX_HOME/agents`
+ * @returns {number} how many agent files were written
+ */
+export function installCodexAgents(agentsSrc, dest) {
+  if (!existsSync(agentsSrc)) return 0;
+  const personas = readdirSync(agentsSrc).filter((f) => f.endsWith(".md"));
+  if (personas.length === 0) return 0;
+
+  // ensureRealDir only swaps a --link-era symlink for a real dir; it does not
+  // create a missing one. Both calls are needed.
+  ensureRealDir(dest);
+  ensureDir(dest);
+
+  // `~/.codex/agents/` also holds user-authored agents, so never wipe the dir.
+  // Remove only pipeline-owned files whose persona no longer exists upstream,
+  // otherwise a renamed persona lingers as a ghost agent Codex can still spawn.
+  removeStalePipelineAgents(dest, personas);
+
+  let written = 0;
+  for (const file of personas) {
+    const name = file.replace(/\.md$/, "");
+    const toml = renderCodexAgent(name, readFileSync(join(agentsSrc, file), "utf-8"));
+    const target = join(dest, `${name}.toml`);
+    if (isDryRun()) {
+      console.log(`    [dry-run] would write ${target}`);
+      written++;
+      continue;
+    }
+    writeFile(target, toml);
+    written++;
+  }
+  return written;
+}
+
+/** Header line stamped on every generated agent file, used to identify ownership. */
+const GENERATED_MARKER = "# Generated by multi-agent-pipeline install --codex.";
+
+/**
+ * Remove generated agent files whose source persona is gone.
+ *
+ * Identified by the generated-marker header, so a user-authored `.toml` that
+ * happens to share a name is never deleted.
+ *
+ * @param {string} dest - `$CODEX_HOME/agents`
+ * @param {string[]} personas - current `pipeline/agents/*.md` filenames
+ * @returns {number} files removed
+ */
+function removeStalePipelineAgents(dest, personas) {
+  if (!existsSync(dest)) return 0;
+  const current = new Set(personas.map((f) => f.replace(/\.md$/, ".toml")));
+  let removed = 0;
+  for (const name of readdirSync(dest)) {
+    if (!name.endsWith(".toml") || current.has(name)) continue;
+    const path = join(dest, name);
+    let owned;
+    try {
+      owned = readFileSync(path, "utf-8").startsWith(GENERATED_MARKER);
+    } catch {
+      continue;
+    }
+    if (!owned) continue;
+    if (isDryRun()) {
+      console.log(`    [dry-run] would remove stale generated agent ${path}`);
+      removed++;
+      continue;
+    }
+    try {
+      rmSync(path, { force: true });
+      removed++;
+    } catch {
+      /* non-fatal */
+    }
+  }
+  if (removed > 0) console.log(`    -> removed ${removed} stale generated agent file(s)`);
+  return removed;
+}
+
+/**
+ * Header the installer stamps on generated agent files. Uninstall matches on
+ * this rather than on a name list derived from the source tree: ownership has
+ * to be decidable from the installed file alone, since uninstall can run from a
+ * different pipeline version than the one that installed.
+ */
+export { GENERATED_MARKER as CODEX_AGENT_GENERATED_MARKER };

package/install/_codex-instructions.mjs

@@ -0,0 +1,33 @@
+/**
+ * Codex CLI instructions block - read from a Markdown source file.
+ *
+ * Mirrors `_copilot-instructions.mjs`: the canonical text lives in
+ * `install/templates/codex-instructions.md` so it is editable as Markdown
+ * (renders on GitHub, lints with prettier, diffs cleanly) rather than as an
+ * escaped JavaScript template literal.
+ *
+ * This is a separate template from the Copilot one on purpose. The two hosts
+ * differ in the places that matter: tree paths (`~/.codex` vs `~/.copilot`),
+ * persona file format (TOML vs Markdown), progress channel (`update_plan` vs
+ * `phase-tracker.sh render`), and Codex's two silent-failure constraints
+ * (sub-agent delegation gating, skills-block overflow). Substituting paths into
+ * the Copilot text would produce a document that is wrong in all four places.
+ *
+ * @module install/_codex-instructions
+ */
+
+import { readFileSync } from "fs";
+import { dirname, join } from "path";
+import { fileURLToPath } from "url";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const TEMPLATE_PATH = join(__dirname, "templates", "codex-instructions.md");
+
+/**
+ * Build the pipeline instructions block for `~/.codex/AGENTS.md`.
+ *
+ * @returns {string} Markdown content
+ */
+export function generateCodexInstructions() {
+  return readFileSync(TEMPLATE_PATH, "utf-8");
+}

package/install/_managed-block.mjs

@@ -0,0 +1,99 @@
+/**
+ * Managed-block merge for host instruction files.
+ *
+ * A host instruction file (`~/.copilot/copilot-instructions.md`,
+ * `~/.codex/AGENTS.md`) is co-owned: the pipeline owns one span, the user owns
+ * everything around it. Every install replaces only that span, so user content
+ * before and after survives.
+ *
+ * Extracted from `install/copilot.mjs` in v13.0.0 when Codex CLI became a third
+ * install target. The bounding logic carries two rounds of drift-cleanup fixes
+ * (v5.6.2 pre-marker sections, v11.4.1 explicit end marker) and must not be
+ * re-derived per target.
+ *
+ * @module install/_managed-block
+ */
+
+import { existsSync, readFileSync } from "fs";
+
+import { writeFile } from "./_common.mjs";
+
+/**
+ * Legacy files (written before the end marker existed) have no explicit
+ * terminator. Bound the pipeline span at the next top-level "# " heading after
+ * the start marker when one exists OUTSIDE fenced code blocks (the pipeline
+ * body carries bash comments like "# Bootstrap once ..." inside fences that
+ * must not be mistaken for headings); otherwise the span runs to EOF, which
+ * matches the pre-marker behavior.
+ *
+ * @param {string} section - file content from the start marker onward
+ * @returns {string} user content trailing the pipeline span ("" if none)
+ */
+export function legacyTrailingContent(section) {
+  const lines = section.split("\n");
+  let inFence = false;
+  for (let i = 1; i < lines.length; i++) {
+    if (/^\s*(```|~~~)/.test(lines[i])) {
+      inFence = !inFence;
+      continue;
+    }
+    if (!inFence && /^# /.test(lines[i])) return lines.slice(i).join("\n");
+  }
+  return "";
+}
+
+/**
+ * Write `body` into `path` as the pipeline-managed span, preserving user
+ * content on both sides.
+ *
+ * @param {object} opts
+ * @param {string} opts.path - instruction file to merge into
+ * @param {string} opts.body - pipeline section content (without the end marker)
+ * @param {string} opts.startMarker - first line of the managed span
+ * @param {string} opts.endMarker - HTML comment terminating the managed span
+ * @param {RegExp[]} [opts.driftPatterns] - pre-marker sections to scrub
+ * @returns {"created"|"updated"|"appended"} what the merge did
+ */
+export function mergeManagedBlock(opts) {
+  const { path, body, startMarker, endMarker, driftPatterns = [] } = opts;
+  const managedBlock = body.trimEnd() + "\n\n" + endMarker + "\n";
+
+  if (!existsSync(path)) {
+    writeFile(path, managedBlock);
+    return "created";
+  }
+
+  let existing = readFileSync(path, "utf-8");
+
+  // Drift cleanup: strip pipeline sections written by installers that predate
+  // the stable marker. Without this they linger and contradict current output.
+  let cleaned = false;
+  for (const re of driftPatterns) {
+    if (re.test(existing)) {
+      existing = existing.replace(re, "");
+      cleaned = true;
+    }
+  }
+
+  if (!existing.includes(startMarker)) {
+    writeFile(path, existing.trimEnd() + "\n\n" + managedBlock);
+    return "appended";
+  }
+
+  const startIdx = existing.indexOf(startMarker);
+  const before = existing.slice(0, startIdx).trimEnd();
+  const fromStart = existing.slice(startIdx);
+  // Replace only the start..end span. User content appended AFTER the pipeline
+  // section (below the end marker, or below the next top-level heading in
+  // legacy files) is preserved.
+  const endIdx = fromStart.indexOf(endMarker);
+  const trailing =
+    endIdx >= 0 ? fromStart.slice(endIdx + endMarker.length) : legacyTrailingContent(fromStart);
+
+  let out = before.length > 0 ? before + "\n\n" : "";
+  out += managedBlock;
+  const trailingClean = trailing.replace(/^[\r\n]+/, "").trimEnd();
+  if (trailingClean.length > 0) out += "\n" + trailingClean + "\n";
+  writeFile(path, out);
+  return cleaned ? "updated+scrubbed" : "updated";
+}