@mmerterden/multi-agent-pipeline 12.11.0 → 13.0.0

package/install/index.mjs

@@ -2,8 +2,8 @@
  * multi-agent-pipeline installer entry point.
  *
  * Parses flags, dispatches to the per-target installers (Claude Code / Copilot
- * CLI), prints a summary, and fires opt-in telemetry. The pipeline runs natively
- * on these two CLIs only.
+ * CLI / Codex CLI), prints a summary, and fires opt-in telemetry. The pipeline
+ * runs natively on these three CLIs only.
  *
  * @module install/index
  */
@@ -16,6 +16,7 @@ import { join } from "path";
 
 import { installClaude } from "./claude.mjs";
 import { installCopilot } from "./copilot.mjs";
+import { installCodex } from "./codex.mjs";
 import { setDryRun, writeFile } from "./_common.mjs";
 import { sendInstallTelemetry } from "./_telemetry.mjs";
 
@@ -25,7 +26,7 @@ const PIPELINE_ROOT = dirname(__dirname);
 const PIPELINE_SRC = `${PIPELINE_ROOT}/pipeline`;
 
 /** Tool flags surfaced in CLI help. */
-const TOOL_FLAGS = ["--claude", "--copilot"];
+const TOOL_FLAGS = ["--claude", "--copilot", "--codex"];
 
 /**
  * @param {string[]} argv
@@ -69,6 +70,8 @@ export async function runInstall(argv) {
 
   const forCopilot = flags.includes("--copilot") || flags.includes("--all");
 
+  const forCodex = flags.includes("--codex") || flags.includes("--all");
+
   const useSymlinks = flags.includes("--link");
   const indexOnly = flags.includes("--index-only");
   const platformFlag = parsePlatformFlag(flags);
@@ -89,10 +92,11 @@ export async function runInstall(argv) {
 
   if (forClaude) installClaude(installerCtx);
   if (forCopilot) installCopilot(installerCtx);
+  if (forCodex) installCodex(installerCtx);
 
   // Version marker: update-check.sh falls back to this for npx-only installs
   // that have no pipeline repo clone to read a version from.
-  writeVersionMarkers({ home: HOME, forClaude, forCopilot });
+  writeVersionMarkers({ home: HOME, forClaude, forCopilot, forCodex });
 
   if (dryRun) {
     console.log("");
@@ -101,7 +105,7 @@ export async function runInstall(argv) {
     return;
   }
 
-  printSummary({ forClaude, forCopilot });
+  printSummary({ forClaude, forCopilot, forCodex });
 
   // Fire-and-forget; install is already done.
   sendInstallTelemetry({ packageRoot: PIPELINE_ROOT, flags });
@@ -111,9 +115,9 @@ export async function runInstall(argv) {
  * Stamp the installed package version into each target so the advisory
  * update check works without a repo clone. Failure is non-fatal.
  *
- * @param {{home: string, forClaude: boolean, forCopilot: boolean}} opts
+ * @param {{home: string, forClaude: boolean, forCopilot: boolean, forCodex?: boolean}} opts
  */
-export function writeVersionMarkers({ home, forClaude, forCopilot }) {
+export function writeVersionMarkers({ home, forClaude, forCopilot, forCodex }) {
   let version;
   try {
     version = JSON.parse(readFileSync(join(PIPELINE_ROOT, "package.json"), "utf-8")).version;
@@ -124,6 +128,7 @@ export function writeVersionMarkers({ home, forClaude, forCopilot }) {
   const targets = [];
   if (forClaude) targets.push(join(home, ".claude", ".pipeline-version"));
   if (forCopilot) targets.push(join(home, ".copilot", ".pipeline-version"));
+  if (forCodex) targets.push(join(home, ".codex", ".pipeline-version"));
   for (const target of targets) {
     try {
       writeFile(target, `${version}\n`);
@@ -150,7 +155,7 @@ function parsePlatformFlag(flags) {
 }
 
 function printSummary(opts) {
-  const { forClaude, forCopilot } = opts;
+  const { forClaude, forCopilot, forCodex } = opts;
 
   console.log("  Installation complete!");
   console.log("");
@@ -168,9 +173,20 @@ function printSummary(opts) {
     console.log("    Just describe your task - Copilot will follow the pipeline");
     console.log("");
   }
+  if (forCodex) {
+    console.log("  Codex CLI:");
+    console.log('    /multi-agent "MOBILE-123"   Start a task (prompt form)');
+    console.log('    $multi-agent "MOBILE-123"   Start a task (skill form)');
+    console.log("    Sub-commands are refs, not skills - the orchestrator loads them on demand");
+    console.log("    Run `codex login` first if you have not already");
+    console.log("");
+  }
 
   console.log("  For UI testing, also install the mobile MCP server:");
-  console.log("    Add to your MCP config: npx @mmerterden/dev-toolkit-mcp");
+  if (forCodex) {
+    console.log("    Codex: registered automatically (codex mcp add dev-toolkit)");
+  }
+  console.log("    Otherwise add to your MCP config: npx @mmerterden/dev-toolkit-mcp");
   console.log("");
   console.log("  Uninstall everything: npx @mmerterden/multi-agent-pipeline uninstall");
   console.log("  (Personal access tokens in keychain are preserved.)");

package/install/templates/codex-instructions.md

@@ -0,0 +1,45 @@
+# Multi-Agent Development Pipeline
+
+This block is managed by `multi-agent-pipeline`. Edit anything outside it freely;
+the installer replaces only the span up to the end marker.
+
+The pipeline is an 8-phase development workflow (analysis, planning, TDD dev,
+parallel review + triage, test, commit, report). It is invoked as `/multi-agent`
+or `$multi-agent`, and the orchestrator spec lives at
+`$HOME/.codex/skills/multi-agent/SKILL.md`.
+
+## Host adaptation (Codex CLI)
+
+| Concern          | On Codex                                                                                                                     |
+| ---------------- | ---------------------------------------------------------------------------------------------------------------------------- |
+| Orchestrator     | one skill, `multi-agent` - it reads per-command specs on demand from `$HOME/.codex/multi-agent-refs/commands/<cmd>/SKILL.md` |
+| Phase specs      | `$HOME/.codex/multi-agent-refs/phases/phase-N-*.md`, read only when that phase runs                                          |
+| Personas         | `$HOME/.codex/agents/*.toml` (generated from the pipeline's persona set)                                                     |
+| Progress display | the native `update_plan` tool, one plan step per phase, plus `phase-tracker.sh` state on disk                                |
+| Shared state     | task logs and preferences stay under `$HOME/.claude/` - that path is the cross-host state root, not a Claude Code dependency |
+
+## Sub-agent delegation is authorized for this pipeline
+
+Codex does not spawn sub-agents unless instructions explicitly ask for it. The
+pipeline's Phase 1 (parallel codebase scan) and Phase 4 (parallel review) depend
+on real fan-out, so **delegation is authorized whenever a `/multi-agent` or
+`$multi-agent` run is active**, under these rules:
+
+1. **Always pass `fork_turns: "none"`** (or a positive integer) on a
+   `spawn_agent` that sets `model` or `reasoning_effort`. A full-history fork
+   inherits the parent model and **silently discards the override**, which would
+   collapse the whole review panel onto one model with no error.
+2. **At most 3 concurrent children.** There are 4 concurrency slots including the
+   orchestrator, so a 3-reviewer panel is the ceiling; a 4th child queues rather
+   than running in parallel.
+3. Outside an active pipeline run, the default applies: do not delegate unless
+   asked.
+
+## Skills-block budget
+
+Codex assembles every discovered skill's name + description into one prompt block
+and **silently drops entries when that block overflows**. The pipeline therefore
+contributes exactly **one** skill (`multi-agent`) and keeps its 42 sub-command
+specs as reference files that cost nothing until read. Do not convert those specs
+into peer skills: doing so evicts other skills, including ones from installed
+plugins, with no error surfaced.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@mmerterden/multi-agent-pipeline",
-  "version": "12.11.0",
-  "description": "8-phase AI development pipeline with full orchestration on Claude Code and Copilot CLI. Analysis, planning, TDD, CLI-aware parallel review with consensus surfacing + Fable triage, default-FAIL evidence gates, secret + intent guards, per-phase cost ledger, persistent learnings memory, wiki generation, commit automation. Token-preserving uninstall.",
+  "version": "13.0.0",
+  "description": "8-phase AI development pipeline with full orchestration on Claude Code, Copilot CLI and Codex CLI. Analysis, planning, TDD, CLI-aware parallel review with consensus surfacing + Fable triage, default-FAIL evidence gates, secret + intent guards, per-phase cost ledger, persistent learnings memory, wiki generation, commit automation. Token-preserving uninstall.",
   "type": "module",
   "main": "index.js",
   "exports": {
@@ -42,7 +42,9 @@
     "frontend",
     "jira",
     "github-issues",
-    "automation"
+    "automation",
+    "codex",
+    "codex-cli"
   ],
   "author": "Mert Erden",
   "license": "MIT",

package/pipeline/claude-md-template.md

@@ -19,6 +19,7 @@
 4. Review -> deterministic gates + parallel review + Fable triage
    - Claude Code: Opus + Sonnet (2 paralel)
    - Copilot CLI: GPT-5.4 + Opus + Sonnet (3 paralel)
+   - Codex CLI: gpt-5.6 (xhigh) + gpt-5.4 + gpt-5.6 (medium) (3 paralel)
 
 ### Strict Rules
 

package/pipeline/commands/multi-agent/SKILL.md

@@ -48,7 +48,7 @@ Classification schema lives in `$HOME/.claude/multi-agent-refs/_input-parser.md`
 | 7 | `issue` | full picker | account → repo (multi) → issue → maturity → dev-context |
 | 8 | Free-text | `freetext` | account → repo (single) → dev-context (maturity skip) |
 
-**Rule**: Whatever the type, **account is always asked** (autopilot picks a default). After issue fetch, **maturity check is mandatory**  -  blockers halt the pipeline. All picker UI strings render in English (`promptLanguage` is locked to `en`).
+**Rule**: Whatever the type, **account is always asked** (autopilot picks a default). After issue fetch, **maturity check is mandatory**  -  blockers halt the pipeline. Picker `label` + `header` render in English (`promptLanguage` is locked to `en`); the `question` and each option's `description` render in `outputLanguage`, per the canonical matrix in `multi-agent-refs/rules.md`.
 
 Lib scripts (`~/.claude/lib/`):
 - `account-resolver.sh`  -  keychain account inventory

package/pipeline/commands/multi-agent/dev/SKILL.md

@@ -57,19 +57,44 @@ The agent CANNOT make these Phase 0 decisions automatically; it suggests, then w
    - Show the chosen provider in the picker label (e.g. "Bitbucket account?" not "GitHub account?")
 3. Project root (state inheritance is FORBIDDEN  -  picker runs every run)
 4. dev-context picker (extra repos / submodules  -  read `.gitmodules` and suggest)
-5. **Network reachability gate (run before branch picker)**: Test remote with `git ls-remote --heads origin <baseBranch>` (5s timeout). One of three outcomes:
-   - **Reachable** → proceed to base branch picker, fetch latest, create worktree from `origin/<baseBranch>`
-   - **Unreachable** (DNS resolve fail / timeout) → STOP and ask the user:
+5. **Remote reachability gate (run before branch picker)**: Test remote with
+   `git ls-remote --heads origin <baseBranch>` (5s timeout), capturing **stderr**.
+
+   **Classify the failure before naming a cause.** A non-zero exit is not evidence
+   of a network problem, and telling the user to enable a VPN for an auth failure
+   sends them to fix something that was never broken. Match stderr, in this order:
+
+   | stderr contains | Cause | What to offer |
+   |---|---|---|
+   | `could not read Password`, `Authentication failed`, `terminal prompts disabled`, `Invalid username or password`, `403` | **credential**, not network | the remote URL usually embeds a username with no credential-helper entry. Offer: store the PAT in the credential helper (`git credential approve`, or re-run `/multi-agent:setup`), or switch the remote to SSH. A VPN cannot fix this. |
+   | `Could not resolve host`, `Operation timed out`, `Connection refused`, `Network is unreachable`, or the 5s timeout fired with no output | **network** | the VPN/DNS prompt below |
+   | `Repository not found`, `does not appear to be a git repository`, `404` | **wrong remote** | show `git remote -v` and ask which remote is correct |
+   | anything else | **unknown** | print the stderr line verbatim and ask; never assert a cause you did not observe |
+
+   Outcomes:
+   - **Reachable** → proceed to base branch picker, fetch latest, create worktree
+     from `origin/<baseBranch>`
+   - **Credential / wrong remote** → STOP with the matching remedy above. Do **not**
+     offer "continue from the local ref": the base being stale is unrelated to the
+     actual failure, so accepting staleness here trades correctness for nothing.
+   - **Network** → STOP and ask:
      ```
-     [N/Total] Network gate
-       Detected: <host> unreachable (VPN/DNS).
+     [N/Total] Remote gate
+       Observed: <the stderr line, verbatim>
+       Classified: <host> unreachable (network).
        Options:
          1. Enable VPN and retry (recommended  -  branch will be fresh)
          2. Continue from local origin/<baseBranch> ref (may be stale)
          3. Cancel
        Confirm? [1/2/3]
      ```
-   - User picks `2` → log warning + record `"baseRefFreshness": "stale"` in `agent-state.json`, proceed from local ref. Phase 6 push needs network anyway, so re-prompt VPN there if still unreachable.
+   - User picks `2` → log warning + record `"baseRefFreshness": "stale"` in
+     `agent-state.json`, proceed from local ref. Phase 6 push needs network anyway,
+     so re-prompt there if still unreachable.
+
+   Always show what was **observed** next to what was **classified**. The previous
+   wording asserted `Detected: <host> unreachable (VPN/DNS)` for every failure mode,
+   including a plain missing-credential error that returns in under a second.
 6. Base branch picker (show recents, take an explicit pick)
 7. Branch name (suggest, allow edit)
 8. Maturity flags acknowledge (read from the issue body's Progress table)

package/pipeline/commands/multi-agent/finish/SKILL.md

@@ -56,7 +56,7 @@ Phases 1-3 (Analysis / Planning / Dev) are skipped by design  -  `finish` treats
   - interactive: present them and ask (`AskUserQuestion`) whether to fix now (loop back through a minimal Phase-3-style TDD fix) or proceed;
   - `autopilot` (or `prefs.global.finish.autoFix == true`): auto-fix accepted blocking/important findings, then re-review the fix, before advancing.
 - **Phase 5 Build+Test** - the **automated success gate** (this is what "build+test success" means here; the interactive device user-test is `/multi-agent:manual-test`). Stack-aware: build via `figma-config.build` (iOS scheme / Android gradle / detected backend/frontend build) and run the existing test suite if present (`swift test` / `xcodebuild test` / `./gradlew test` / `pytest` / `npm test` / `vitest`). Require success to advance; on failure, surface logs and (interactive) stop or (autopilot) attempt a bounded fix loop. **If the repo has no tests, report "no tests present" - never fabricate test results.**
-- **Phase 6 Commit/PR** - per `$HOME/.claude/multi-agent-refs/phases/phase-6-commit.md`: stage + commit any remaining local changes with a conventional message (`{type}(scope): desc [{JIRA_KEY}-{id}]`), push, and open a PR **only if one does not already exist** for the branch. PR body per `$HOME/.claude/multi-agent-refs/pipeline-output-formatting` and `rules/git-conventions` - `Ref: #N` / `Related: #N`, never `Closes/Fixes/Resolves`; NO AI/bot attribution anywhere.
+- **Phase 6 Commit/PR** - per `$HOME/.claude/multi-agent-refs/phases/phase-6-commit.md`: stage + commit any remaining local changes with a conventional message (`{type}(scope): desc [{JIRA_KEY}-{id}]`), push, and open a PR **only if one does not already exist** for the branch. PR body per `$HOME/.claude/rules/pipeline-output-formatting.md` and `$HOME/.claude/rules/git-conventions.md` - `Ref: #N` / `Related: #N`, never `Closes/Fixes/Resolves`; NO AI/bot attribution anywhere.
 - **Phase 7 Report** - per `$HOME/.claude/multi-agent-refs/phases/phase-7-report.md` + `channels.md`: produce the **technical analysis** and **test scenarios**, then post to the configured channels. Default content for `finish`: a Jira **comment** carrying the technical analysis + the test scenarios (and, when the PR was opened, the PR description). Every body runs through the humanizer; bot/tool/AI signatures are FORBIDDEN in comments.
 
 ## Modes

package/pipeline/commands/multi-agent/language/SKILL.md

@@ -15,7 +15,7 @@ Two-axis language preference for the pipeline:
 | `promptLanguage` | Interactive prompts during a pipeline run (account picker, project picker, dev-context picker, base-branch picker, branch-name picker, maturity ack, channels picker, Phase 5 test prompt, Phase 6 local-checkout prompt) | `prefs.global.promptLanguage` | **Fixed to `en`**  -  never toggled by this skill |
 | `outputLanguage` | Assistant's explanations, status updates, error messages, and pipeline-generated reports rendered to the user (NOT external payloads) | `prefs.global.outputLanguage` | Toggled by this skill |
 
-**Why promptLanguage is fixed:** Pipeline picker UI, confirmation prompts, and error messages are authored in English to keep tooling consistent across CLIs. Mixing Turkish prompts into otherwise-English skill output looks inconsistent. Only the assistant's free-form replies follow `outputLanguage`.
+**Why promptLanguage is fixed:** it governs the picker's structural chrome only  -  `AskUserQuestion` `label` (button text) and `header` (chip), host error UI, and internal contract identifiers. Those stay English so tooling reads the same across CLIs. Everything a user actually reads follows `outputLanguage`, including the picker `question` and each option's `description`, per the canonical per-field matrix in `multi-agent-refs/rules.md`. A picker whose question is English on a Turkish run is a bug, not the contract.
 
 **Always English regardless of either field**: commit messages, PR titles/bodies, Jira comments, wiki pages, reviewer/triage system prompts, agent-log.md payloads, confirmation / error UI exposed by the CLI host.
 
@@ -109,5 +109,5 @@ Render in the **new** outputLanguage:
 
 - `setup.md` Step 0  -  first-run language picker (asks only outputLanguage; promptLanguage seeded as `en`)
 - `prefs.schema.json`  -  `global.promptLanguage` (fixed `"en"`) and `global.outputLanguage` definitions
-- `phase-5-test.md`, `phase-6-commit.md`  -  read promptLanguage for their interactive prompts (always English)
+- `phase-5-test.md`, `phase-6-commit.md`  -  interactive prompts follow the per-field matrix: `question` + `description` in `outputLanguage`, `label` + `header` English
 - `help.md`  -  reads outputLanguage to render its own help text

package/pipeline/commands/multi-agent/setup/SKILL.md

@@ -24,7 +24,7 @@ Ask BEFORE anything else, so every subsequent setup prompt and the rest of the p
 
 | Axis | What it controls | Configurable? |
 |---|---|---|
-| `promptLanguage` | Interactive pickers and prompts during a pipeline run (account, project, dev-context, branch, channels, Phase 5 test, Phase 6 confirmations) | **No  -  fixed to `en`.** Picker UI is always English to keep tooling consistent across CLIs. |
+| `promptLanguage` | The picker's structural UI chrome only: `AskUserQuestion` `label` (button text) and `header` (chip), plus host error UI and internal contract identifiers | **No  -  fixed to `en`.** Button and chip text stays English so tooling reads the same across CLIs. |
 | `outputLanguage` | The assistant's non-interactive explanations, status updates, error messages, and pipeline-generated reports rendered to the user | Yes  -  set here and changeable later via `/multi-agent:language <en\|tr>` |
 
 `promptLanguage` is seeded as `"en"` and never offered to the user. **External payloads always stay English** (commits, PR titles/bodies, Jira comments, wiki content, reviewer/triage prompts, agent-log.md).
@@ -51,7 +51,16 @@ Select (1-2):
   - `tr`: `outputLanguage=<Y>. promptLanguage "en" sabit. Dış çıktılar (PR açıklamaları, Jira yorumları, review istemleri) her durumda İngilizce kalır.`
 - **Unknown input** → re-ask once, then abort setup with a hint pointing to `/multi-agent:language`.
 
-From this point forward, every prompt in Steps 1-6 below (discovery summaries, Token Save Flow Steps A-D, identity binding, repo picker) renders in English (per the fixed `promptLanguage`). The setup wizard's own status text and the post-setup summary render in `outputLanguage`. External payloads remain English.
+From this point forward, every prompt in Steps 1-6 below follows the canonical
+per-field matrix in `$HOME/.claude/multi-agent-refs/rules.md` ("Language Application"):
+the `question` text and each option's `description` render in `outputLanguage`, while
+`label` and `header` stay English. The wizard's status text and post-setup summary
+render in `outputLanguage`. External payloads remain English.
+
+> This paragraph used to say every prompt renders in English "per the fixed
+> `promptLanguage`", which contradicted the canonical matrix and produced
+> half-English pickers on Turkish runs: `promptLanguage` governs only the button and
+> chip chrome, never the question a user reads.
 
 ### Step 0.5  -  Credential Backend Check
 
@@ -102,6 +111,12 @@ These are the RECOMMENDED key names. When creating NEW keys, use these. But exis
 | `graylog` | `${USER}_Graylog_Access_Token` | `graylog` |
 | `firebase` | `${USER}_Firebase_Access_Json` | `firebase` (any variant: `sa`, `service`, `account`, `access`, `json`) |
 | `jenkins` | `${USER}_Jenkins_Access_Token` | `jenkins` |
+| `appstore_connect_key_id` | `${USER}_AppStoreConnect_Key_Id` | (`appstore` or `asc` or `app_store`) + (`key` or `keyid`) |
+| `appstore_connect_issuer_id` | `${USER}_AppStoreConnect_Issuer_Id` | (`appstore` or `asc` or `app_store`) + `issuer` |
+| `appstore_connect_apple_id` | `${USER}_AppStoreConnect_Apple_Id` | (`appstore` or `asc`) + (`apple` or `account` or `user`) |
+| `appstore_connect_password_item` | `${USER}_AppStoreConnect_Password_Item` | (`appstore` or `asc` or `altool`) + (`password` or `app_specific`) |
+
+> The four App Store Connect entries are **iOS-only and optional**: skip them all and the pipeline still works, it just reports Gate 2 of `/multi-agent:testflight-validation` as `SKIPPED` (never as a pass). They mirror the Figma 3-tier shape  -  Tier 1 = API key (`appstore_connect_key_id` + `appstore_connect_issuer_id`), Tier 2 = Apple ID + app-specific password (`appstore_connect_apple_id` + `appstore_connect_password_item`), Tier 3 = nothing configured. **Offer Tier 2 first when the user says they cannot create an API key**: creating one needs an Admin or App Manager role in App Store Connect, while an app-specific password is generated by the account holder at `appleid.apple.com` with no team permission at all. Two of these hold identifiers rather than secrets (key id, issuer id) and one holds a keychain ITEM NAME, not a password  -  they still go through the mapping layer so every credential is read the same way. Onboarding mechanics in Step 3b.
 
 **1c. Resolution logic (per service):**
 
@@ -352,6 +367,58 @@ This builds `platformIdentityRouting` incrementally  -  no separate Step 7 neede
 
 ---
 
+### Step 3b  -  App Store Connect onboarding (iOS only, optional)
+
+Runs inside Step 3 alongside the other missing credentials, not as a late add-on:
+a user who already has an App Store Connect credential in their keychain gets it
+mapped by Step 1 discovery like any other token, and only the genuinely missing
+pieces reach this flow.
+
+Three of the four entries do not go through the normal Token Save Flow, because
+what they hold is not a pasteable secret:
+
+| Entry | Holds | Flow |
+|---|---|---|
+| `appstore_connect_key_id` | an identifier | plain value, not a secret; still mapped so it is read through the mapping layer |
+| `appstore_connect_issuer_id` | an identifier | same |
+| `appstore_connect_apple_id` | an email address | same |
+| `appstore_connect_password_item` | a keychain ITEM NAME | the password lives in Apple's own keychain item, referenced as `-p @keychain:<item>` and never read by the pipeline |
+
+Ask which tier to configure (picker): **API key** / **Apple ID + app-specific
+password** / **Skip**. Lead with the second when the user says they cannot create
+an API key.
+
+**API key.** The private key is a FILE and is never copied into the credential
+store. It must sit in a directory `altool` already searches:
+
+```bash
+ls ~/.appstoreconnect/private_keys/AuthKey_*.p8 2>/dev/null \
+  || echo "MISSING: put AuthKey_<keyId>.p8 in ~/.appstoreconnect/private_keys/"
+```
+
+**Apple ID + app-specific password.** Use Apple's own keychain helper. The secret
+never enters chat and never becomes a shell argument, per the Token Save Flow rule:
+
+```bash
+# the user exports AC_PASSWORD_ONCE in their own shell, for this one command
+xcrun altool --store-password-in-keychain-item "<item-name>" \
+  -u "<apple-id>" -p @env:AC_PASSWORD_ONCE
+```
+
+Then map only `<item-name>` as `appstore_connect_password_item`.
+
+**Multi-provider accounts.** A corporate Apple ID often belongs to several
+providers, and `altool` fails opaquely without one. Resolve it once with
+`ios_testflight_validate({list_providers: true, <credentials just configured>})`
+and store the answer under
+`prefs.projects[<key>].appStoreConnect.providerPublicId`  -  per-project, since a
+user can ship for more than one team.
+
+**Verify + expiry.** Re-run the `list_providers` probe and report the resolved
+tier. A credential that resolves but is rejected (401/403) follows the
+Expired-token decision in `refs/keychain.md` Rule 1  -  Regenerate / Use a
+different token / Skip and continue  -  never a silent drop.
+
 ### Step 3.5  -  Host Prompt (embedded in Token Save Flow)
 
 **Not a standalone step**  -  runs inline at the end of the Token Save Flow whenever the saved token belongs to a **hosted service** (Jira, Confluence, Bitbucket, Fortify, Graylog) AND the host is not yet in `prefs.global.hosts`. Firebase tokens skip this step  -  Crashlytics is always on Google's fixed domains and `project_id` is embedded in the SA JSON.

package/pipeline/commands/multi-agent/sync/SKILL.md

@@ -27,6 +27,7 @@ When invoked, it synchronizes all targets in order. It detects what changed, upd
 |---|-------|-----|-----|
 | 1 | Claude Code (source of truth) | `~/.claude/commands/multi-agent.md` + `~/.claude/commands/multi-agent/` + `~/.claude/agents/` + `~/.claude/scripts/` + `~/.claude/lib/` | source |
 | 2 | Copilot CLI | `~/.copilot/copilot-instructions.md` + `~/.copilot/skills/` | <- from Claude |
+| 2b | Codex CLI | `~/.codex/AGENTS.md` + `~/.codex/skills/multi-agent/` + `~/.codex/multi-agent-refs/` + `~/.codex/agents/*.toml` | <- from Claude (path-rewritten) |
 | 3 | multi-agent-pipeline repo | `~/multi-agent-pipeline/pipeline/` | <- from Claude (genericized) |
 | 4 | Website | `{owner}/{website-host}` | <- version + features |
 | 5 | dev-toolkit MCP server | resolved from `prefs.global.devToolkit` or the `mcpServers` registration | own repo: gate, commit, publish |
@@ -58,7 +59,8 @@ Run every step automatically:
 ```
 Step 1: PLATFORM    Detect macOS / Linux / Windows (Git Bash / WSL); export PLATFORM env
 Step 1.5: DETECT    Compare timestamps, find stale targets
-Step 2: COPILOT     Claude Code -> Copilot CLI (instructions + 42 sub-command skills)
+Step 2: COPILOT     Claude Code -> Copilot CLI (instructions + 43 sub-command skills)
+Step 2b: CODEX      Claude Code -> Codex CLI (1 router skill + 43 specs as refs + 8 agent TOML)
 Step 3: REPO        Claude Code -> pipeline repo (genericized, personal data scrub, bash -n on all sh)
 Step 3c: PLUGINS    pipeline shared/external -> multi-agent-plugins marketplace (rebuild knowledge/,
                      bump changed plugins' patch version, commit + push the plugins repo)
@@ -169,6 +171,50 @@ If nothing is stale → report "All targets up to date" and stop.
 
 ---
 
+## Codex Sync (Step 2b)
+
+Unlike the Copilot step, this one does **not** hand-copy files. The Codex tree is a
+*transform* of the Claude tree, not a mirror of it, and the transform is real work:
+
+- the 43 sub-command specs become reference files, because Codex silently truncates
+  its skills block (see `cross-cli-contract.md` 2.6 for the measurement)
+- every `$HOME/.claude/...` reference to a CLI-owned tree is retargeted, with
+  `agents/<persona>.md` becoming `.toml` and the dispatcher becoming the router skill
+- the 8 personas are regenerated as TOML with a model + reasoning-effort mapping
+- shared state (`logs/`, prefs, `knowledge/`) is deliberately NOT retargeted
+
+That logic lives in `install/codex.mjs` and is gate-locked by
+`smoke-codex-install.sh`. Re-describing it here in prose would give the pipeline two
+definitions of the same transform, and the prose copy would be the one that rots. So
+the step runs the installer's Codex target:
+
+```bash
+cd "$HOME/multi-agent-pipeline"
+node install.js --codex
+```
+
+**Verify** (the installer is quiet about correctness, only about counts):
+
+```bash
+# exactly one pipeline skill: more than one means the skills block will truncate
+ls -1 "$HOME/.codex/skills" | grep -c '^multi-agent$'          # want 1
+# every sub-command reachable as a ref
+find "$HOME/.codex/multi-agent-refs/commands" -name SKILL.md | wc -l   # want the command count
+# no reference left pointing at a tree a Codex-only install does not have
+grep -rhoE '(\$HOME|~)/\.claude/(agents|scripts|lib|schemas|commands|multi-agent-refs|rules)' \
+  "$HOME/.codex/skills" "$HOME/.codex/multi-agent-refs" | sort -u   # want empty
+```
+
+**MCP**: the installer runs `codex mcp add dev-toolkit` itself. It is idempotent, and
+it is skipped with a warning when `codex` is not on `PATH` -  never hand-edit
+`~/.codex/config.toml`, which Codex owns (marketplace and plugin state live there
+too).
+
+**Order matters**: run this AFTER Step 3 (REPO), because the installer reads the repo
+tree. Running it before means Codex gets the previous revision.
+
+---
+
 ## Stack-Plugin Sync (Step 3c)
 
 Stack skills are distributed as versioned plugins in the `mmerterden/multi-agent-plugins` marketplace. The pipeline's `pipeline/skills/shared/external/` is the **single authoring source**; the marketplace is a derived, versioned publish artifact. This step rebuilds it and publishes only when something changed.
@@ -283,7 +329,79 @@ git tag "v$NEW" && git push origin main --tags
 
 Publish to the registry declared in `publishConfig` through a throwaway userconfig. Never edit `~/.npmrc`, and never a bare `npm publish`  -  it lands on whichever registry the ambient config happens to name.
 
-**The token depends on the registry**: `npm.pkg.github.com` authenticates with a GitHub PAT carrying `write:packages` (logical key `github`), `registry.npmjs.org` with an npm token (logical key `npm`). Picking the wrong one fails with a 401 that reads like a missing package.
+**The token depends on the registry AND on the package scope.** The registry picks
+the credential *type*; the scope picks the *account*. Resolving on host alone
+misroutes on any machine with more than one GitHub identity, which is the common
+case for anyone with a work and a personal account.
+
+| Registry | Credential type | Account chosen by |
+|---|---|---|
+| `npm.pkg.github.com` | GitHub PAT with `write:packages` (Classic; fine-grained PATs are not fully supported for Packages) | the package scope, e.g. `@{owner}` → the `{owner}` account's PAT |
+| `registry.npmjs.org` | npm token (logical key `npm`) | the npm account that owns the scope |
+
+Resolve the scope first, then the key:
+
+```bash
+SCOPE=$(node -p "(require('./package.json').name.match(/^@([^/]+)/)||[])[1] || ''")
+# Prefer a scope-specific mapping; fall back to the generic key only when the
+# machine has exactly one GitHub identity.
+KEY=$(node -e '
+  const fs=require("fs"),os=require("os"),p=os.homedir()+"/.claude/multi-agent-preferences.json";
+  const km=(JSON.parse(fs.readFileSync(p,"utf8")).global||{}).keychainMapping||{};
+  const scope=process.argv[1];
+  process.stdout.write(km[`github_${scope}`] ? `github_${scope}` : "github");
+' "$SCOPE")
+```
+
+**Pre-flight the scope, do not learn it from a 403.** GitHub tells you a token's
+scopes on any authenticated request, so check before uploading rather than after:
+
+```bash
+scope_ok() {  # $1 = token; prints the login, non-zero when write:packages is absent
+  local hdrs; hdrs=$(curl -sI -H "Authorization: token $1" https://api.github.com/user)
+  printf '%s' "$hdrs" | grep -i '^x-oauth-scopes:' | grep -q 'write:packages'
+}
+```
+
+**Candidate order for a `npm.pkg.github.com` publish.** The scope matters more than
+where the token is stored, and the two are not correlated: on a machine with a work
+and a personal identity, the hand-made PAT in the credential store may be the wrong
+account or the right account without `write:packages`, while the `gh` CLI's own
+OAuth token for that account often has it.
+
+1. `github_<scope>` from `keychainMapping` (a PAT deliberately onboarded for this scope)
+2. `gh auth token -u <scope>`  -  gh's stored OAuth token for that account
+3. the generic `github` key  -  only when the machine has one GitHub identity
+
+Take the first candidate that passes `scope_ok` AND whose `login` matches the
+package scope. If none qualifies, stop before `npm publish` and report which
+candidates were tried, what login each resolved to, and which scope was missing.
+That report is the actionable output; a 403 body is not.
+
+Measured on this machine, which is why the order is what it is:
+
+| Candidate | login | scopes |
+|---|---|---|
+| `keychainMapping.github` | corporate EMU account | cannot publish to a personal scope under any grant |
+| `mmerterden_Github_Auth_Token` | personal | `admin:public_key, gist, read:org, repo`  -  no `write:packages` |
+| `gh auth token -u mmerterden` | personal | `gist, read:org, repo, workflow, write:packages` ✓ |
+
+**Two 403s mean two different things, and neither says "wrong token" plainly:**
+
+- `Unauthorized: As an Enterprise Managed User, you cannot access this content`  -
+  the resolved token belongs to a corporate EMU account, which cannot publish to a
+  personal scope at all. The mapping points at the wrong identity. Map the personal
+  account's PAT under `github_<scope>` and re-run; do not "fix" this by granting
+  the EMU token more scopes, because no scope makes an EMU account able to write
+  to a personal namespace.
+- `The token provided does not match expected scopes`  -  right account, missing
+  permission. The PAT needs **Classic** with `write:packages` (plus `repo` for a
+  private package). Regenerate it at
+  `https://github.com/settings/tokens/new?scopes=write:packages,read:packages,repo`
+  and re-onboard via `/multi-agent:setup`.
+
+Report which of the two it was. "Permission denied" alone sends the user to
+regenerate a token that was never the problem.
 
 ```bash
 NPMRC=$(mktemp); trap 'rm -f "$NPMRC"' EXIT
@@ -350,6 +468,7 @@ When invoked with the `release` argument:
 7. DEV-TOOLKIT   Ship the companion MCP server if it moved (Step 3d gates, then publish)
 8. WEBSITE       Version + features -> {website-host}
 9. COPILOT       Copilot CLI instructions + skills sync
+9b. CODEX        Codex CLI router skill + refs + agent TOML (node install.js --codex)
 10. Report       Summary: version, touched repos, deploy status
 ```
 
@@ -357,20 +476,24 @@ When invoked with the `release` argument:
 
 ## Sub-Command Sync (Claude Code <-> Copilot CLI Skills)
 
-This runs on the Claude <-> Copilot axis - the two CLIs the pipeline supports natively.
+> Codex takes the Step 2b path instead; see that section.
+
+This runs on the Claude <-> Copilot axis. Codex is NOT synced here: it receives the
+same 43 specs as reference files rather than as peer skills, via Step 2b -  see
+`cross-cli-contract.md` 2.6 for why the parity axis differs per host.
 
 | Claude Code | Copilot CLI |
 |-------------|-------------|
 | `~/.claude/commands/multi-agent/{cmd}/SKILL.md` | `~/.copilot/skills/multi-agent-{cmd}/SKILL.md` |
 
-**42 commands are synced** (canonical inventory  -  must match `cross-cli-contract.md` section 1; drift = contract violation):
+**43 commands are synced** (canonical inventory  -  must match `cross-cli-contract.md` section 1; drift = contract violation):
 
 ```
 analysis, analysis-resolve, autopilot, build-optimize, channels, create-jira, design-check, dev,
 dev-autopilot, dev-local, dev-local-autopilot, diff-explain, finish, forget, garbage-collect,
 help, issue, jira, kill, language, local,
 local-autopilot, log, manual-test, prune-logs, purge, refactor, resume, review, review-issue, review-jira,
-routines, save, scan, search, setup, stack, status, sync, test, uninstall, update
+routines, save, scan, search, setup, stack, status, sync, test, testflight-validation, uninstall, update
 ```
 
 **NOT synced**: `$HOME/.claude/multi-agent-refs/*`  -  lazy-load references, Claude Code specific