@mmerterden/multi-agent-pipeline 15.3.1 → 15.3.2

package/CHANGELOG.md

@@ -16,6 +16,20 @@ Internal file-layout changes that don't affect the slash-command surface are sti
 
 ## [Unreleased]
 
+## [15.3.2] - 2026-08-17
+
+### Fixed
+
+- `local` and `local-autopilot` mode docs pointed at the retired `commands/multi-agent.md` dispatcher spelling; they now reference `commands/multi-agent/SKILL.md`, and the Codex installer rewrites the directory-layout spelling to the router skill (dedicated rewrite rule, smoke guard for the new corruption shape, unit tests).
+- The sync spec copies (command tree + Copilot shared-core mirror) disagreed on the Claude source list and file mapping; both now carry `multi-agent-refs/` and `lib/` and the same mapping rows.
+- The dispatcher entry doc now declares the TaskCreate ordering rule and is scanned by `smoke-tasklist-ordering.sh`, closing the one mode (full interactive) the inventory missed.
+- `check-md-links.mjs` resolves `$HOME/.claude/commands/` links against the repo source, so a future layout move cannot leave dangling dispatcher references silently.
+- Install-layout fingerprint fixture regenerated for `usage-report.mjs` and the relocated reference files.
+
+### Changed
+
+- refactor Step 0c (dev-toolkit research) and setup Step 3b (App Store Connect onboarding) moved to on-demand references under `multi-agent-refs/`, keeping both skills inside their token budgets.
+
 ## [15.3.1] - 2026-08-15
 
 ### Changed

package/install/codex.mjs

@@ -82,6 +82,18 @@ export const CODEX_PATH_REWRITES = Object.freeze([
     to: "$HOME/.codex/skills/multi-agent/SKILL.md",
   },
   { from: /~\/\.claude\/commands\/multi-agent\.md/g, to: "~/.codex/skills/multi-agent/SKILL.md" },
+  // Current dispatcher spelling (directory layout). MUST also precede the
+  // sub-command rule: `commands/multi-agent/SKILL.md` would otherwise become
+  // `multi-agent-refs/commands/SKILL.md`, which installRefs deliberately never
+  // writes (the top-level SKILL.md ships as the router skill instead).
+  {
+    from: /\$HOME\/\.claude\/commands\/multi-agent\/SKILL\.md/g,
+    to: "$HOME/.codex/skills/multi-agent/SKILL.md",
+  },
+  {
+    from: /~\/\.claude\/commands\/multi-agent\/SKILL\.md/g,
+    to: "~/.codex/skills/multi-agent/SKILL.md",
+  },
   // Sub-command specs become reference files under the Codex refs tree.
   {
     from: /\$HOME\/\.claude\/commands\/multi-agent\b/g,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mmerterden/multi-agent-pipeline",
-  "version": "15.3.1",
+  "version": "15.3.2",
   "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",

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

@@ -285,6 +285,10 @@ Quick pointers:
 
 Load `$HOME/.claude/multi-agent-refs/rules.md` for the full contract (Swift-specific rules, reviewer policy, secret scan, subagent contract).
 
+### TaskCreate ordering (strict)
+
+**All TaskCreate calls fire in strict phase-number order BEFORE any TaskUpdate is applied**  -  this binds the full interactive `/multi-agent` run (all 8 phases) exactly like every mode alias. The native widget renders tiles by creation order, not by phase number; out-of-order calls produce visually scrambled tile stacks. Register every tile in order, then flip status via TaskUpdate when a phase actually starts or short-circuits. Full contract: `$HOME/.claude/multi-agent-refs/tracker-contract.md` section "TaskCreate ordering (strict)".
+
 ---
 
 ## Status Display

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

@@ -40,7 +40,7 @@ Phase 7: Report     → Jira / Wiki / Confluence + log + knowledge/memory
 
 This command routes to the orchestrator with the `--local` flag set. The Phase 0-7 contract from `$HOME/.claude/multi-agent-refs/phases/phase-0-init.md` and the later phase docs applies as-is  -  only the worktree step is skipped, and `state.projects[*].worktreePath` stays `null`.
 
-Read the routing table in `$HOME/.claude/commands/multi-agent.md` and apply Phase 0 Step 8 in local mode (no worktree: continue on the current branch, state file under `.claude/logs/multi-agent/{project}/{taskId}/`).
+Read the routing table in `$HOME/.claude/commands/multi-agent/SKILL.md` and apply Phase 0 Step 8 in local mode (no worktree: continue on the current branch, state file under `.claude/logs/multi-agent/{project}/{taskId}/`).
 
 ## Examples
 

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

@@ -69,7 +69,7 @@ Run the full pipeline **without a worktree** and **with every confirmation skipp
 
 ## Delegation
 
-Orchestrator routing: the routing table in `$HOME/.claude/commands/multi-agent.md` resolves `local-autopilot` as the union of the `dev-local` + `autopilot` mode mixins. Contract details: `$HOME/.claude/multi-agent-refs/phases/phase-0-init.md` Step 8 (local branch) + `$HOME/.claude/multi-agent-refs/phases/phase-2-planning.md` Step 5 (autopilot gate skip + safety classifier).
+Orchestrator routing: the routing table in `$HOME/.claude/commands/multi-agent/SKILL.md` resolves `local-autopilot` as the union of the `dev-local` + `autopilot` mode mixins. Contract details: `$HOME/.claude/multi-agent-refs/phases/phase-0-init.md` Step 8 (local branch) + `$HOME/.claude/multi-agent-refs/phases/phase-2-planning.md` Step 5 (autopilot gate skip + safety classifier).
 ## Required: outward-facing payload contracts
 
 Before writing anything outward-facing  -  PR body, Jira comment, Confluence page, closing report  -  load `$HOME/.claude/multi-agent-refs/payload-contracts.md`. It names the canonical section set for each payload, the markup dialect per surface (PR body is Markdown, Jira is wiki markup  -  mixing them is a defect), and the token/duration numbers the closing report must carry. Improvising a payload shape from memory is the most common failure of the short modes.

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

@@ -112,73 +112,7 @@ Procedure:
 
 The pipeline's hands on devices and browsers are MCP tools served by a companion repo (`dev-toolkit-mcp`): Phase 5 test, `manual-test`, `design-check` and `apple-archive-compliance` all call them, and several pipeline skills declare a minimum toolkit version (see `cross-cli-contract.md`). That repo therefore has to track the MCP field, not just its own README. This step researches what current practice is and audits the toolkit against it.
 
-**Resolution**  -  configuration first, never a hardcoded path:
-
-1. `prefs.global.devToolkit` in `~/.claude/multi-agent-preferences.json`:
-
-```jsonc
-{
-  "enabled": true,
-  "label": "<human name>",
-  "localPath": "$HOME/<repo-dir>",              // the companion repo working copy
-  "mcpServerName": "<registered MCP server name>",
-  "packageName": "@<scope>/<package>",
-  "registry": "github-packages",                 // github-packages | npmjs | none
-  "repoUrl": "https://github.com/<owner>/<repo>"
-}
-```
-
-2. If unset, auto-detect from the MCP registration: read `mcpServers` in `~/.claude.json` (including each `projects[*].mcpServers`) and in `~/.claude/settings.json`; for a stdio entry whose command is `node`, take `dirname(args[0])`. Accept it only when that directory is a git repo whose `package.json` depends on `@modelcontextprotocol/sdk`.
-3. If neither resolves, skip this step and report "no dev-toolkit configured". Never guess a path, never clone.
-4. `enabled: false` skips the step.
-
-**Research axes**  -  a finding without a source link is not a finding:
-
-| # | Axis | Where to look | What to extract |
-|---|------|---------------|-----------------|
-| 1 | MCP protocol | spec revisions + `@modelcontextprotocol/sdk` releases | protocol features released since the pinned SDK range that the server does not use yet: tool annotations (`readOnlyHint` / `destructiveHint` / `idempotentHint` / `openWorldHint`), `outputSchema` + structured content, resource links in results, progress + cancellation, `tools/list_changed`, pagination, elicitation |
-| 2 | Host clients | Claude Code / Copilot CLI / Cursor / Antigravity docs + release notes | per-tool description budget, tool-count ceilings, naming conventions, image and output size limits, permission / allowlist ergonomics |
-| 3 | Peer servers | GitHub search on the same domain terms + `stars:>50` | tool surfaces we lack, conventions peers converged on, and what to discard as out of scope |
-| 4 | Wrapped tooling | `xcrun simctl help`, `idb`, `adb`, `xcodebuild`, Playwright release notes, Apple ITMS + App Store Review Guidelines | deprecated flags still in use, new capabilities worth a tool, audit rules that changed |
-| 5 | Field practice | X / Twitter, Reddit, MCP community threads | what server authors actually changed recently (transport choice, output-token diets, sandboxing, error shape) |
-
-**Audit the toolkit against the findings**  -  run the checks, do not assume:
-
-```bash
-DT="<resolved localPath>"
-node --check "$DT/index.js"
-find "$DT/tools" -name "*.js" -type f -exec node --check {} \;
-
-# stdout carries the JSON-RPC frames: a stray stdout write corrupts the stream
-grep -rn "console\.log(" "$DT/index.js" "$DT/tools" || echo "stdout clean"
-
-# advertised tool counts vs reality (README header + package.json description)
-grep -nE "[0-9]+ tools" "$DT/README.md" "$DT/package.json"
-
-# packaging: every runtime directory must be inside files[]
-node -p "require('$DT/package.json').files.join('\n')"
-ls -d "$DT"/tools/*/
-
-cd "$DT" && npm outdated; npm audit --omit=dev 2>/dev/null | tail -20
-```
-
-Also check: every tool carries a description and an `inputSchema`; token-heavy results (screenshots, UI trees, logs) are truncated or written to a file path instead of inlined; failures return an error result with an actionable message instead of throwing; `engines.node` matches what the SDK needs; `CHANGELOG.md`, a CI workflow and a test harness exist.
-
-Output (plan band E):
-
-```
-| # | Axis | Finding | Source | Adaptation in the toolkit (file) | Effort | Impact | In plan? |
-|---|------|---------|--------|----------------------------------|--------|--------|----------|
-| 1 | Protocol | read-only tools carry no annotations | <spec link> | add `annotations` to the read-only tools in index.js | Low | Medium | Yes (P1) |
-| 2 | Wrapped tooling | uses a simctl flag removed in Xcode <v> | <release notes> | switch tools/<family>/<file>.js to <new flag> | Low | High | Yes (P0) |
-| 3 | Peer servers | peer exposes <surface> | <repo link> | does not fit: outside the pipeline's phases | - | - | No |
-```
-
-Rules for this band:
-
-- Band-E work lands in the toolkit repo, never mirrored into this one. Shipping it is `/multi-agent:sync` Step 3d.
-- A finding that changes the tool surface (new / renamed / removed tool) pairs with a pipeline-side item: bump the minimum toolkit version wherever a pipeline skill declares one.
-- If the current working directory IS the toolkit repo, skip band E and let bands A/B/C cover it  -  never report the same finding twice.
+Full procedure  -  resolution (configuration first, never a hardcoded path; skip when nothing resolves or `enabled` is false), the 5 research axes, the audit command block, and the band-E output table + rules  -  lives in `$HOME/.claude/multi-agent-refs/refactor/dev-toolkit-research.md`. Read it before running this step.
 
 ## Step 0d: RUN-ERRORS  -  what the pipeline actually failed on
 

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

@@ -402,55 +402,7 @@ 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.
+Runs inside Step 3 alongside the other missing credentials. The four `appstore_connect_*` entries, their non-secret handling (three hold identifiers / a keychain item name, not pasteable secrets), the API-key vs Apple-ID tier picker, and the verification probes live in `$HOME/.claude/multi-agent-refs/setup/app-store-connect.md`. Read that file when the user opts into App Store Connect onboarding; on Skip, nothing is written.
 
 ### Step 3.5  -  Host Prompt (embedded in Token Save Flow)
 

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

@@ -25,7 +25,7 @@ When invoked, it synchronizes all targets in order. It detects what changed, upd
 
 | # | Target | Path | Direction |
 |---|-------|-----|-----|
-| 1 | Claude Code (source of truth) | `~/.claude/commands/multi-agent.md` + `~/.claude/commands/multi-agent/` + `~/.claude/agents/` + `~/.claude/scripts/` + `~/.claude/lib/` | source |
+| 1 | Claude Code (source of truth) | `~/.claude/commands/multi-agent/` + `~/.claude/multi-agent-refs/` + `~/.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) |
@@ -87,7 +87,7 @@ If nothing is stale → report "All targets up to date" and stop.
 
 1. **Read first**  -  understand every target's current state before making any change
 2. **Preserve file structure**  -  each target has its own format:
-   - `multi-agent.md` + phases/: detailed pipeline spec (frontmatter, phases, routing)
+   - `commands/multi-agent/` SKILL tree + `multi-agent-refs/phases/`: detailed pipeline spec (frontmatter, phases, routing)
    - `copilot-instructions.md`: general development instructions + pipeline summary section
    - `multi-agent-pipeline/pipeline/`: generic open-source version (NO personal data)
 3. **Sync the shared sections** (Claude ↔ Copilot):
@@ -105,7 +105,7 @@ If nothing is stale → report "All targets up to date" and stop.
 
 ## Pipeline Repo Sync Rules (CRITICAL)
 
-1. **Source**: `~/.claude/commands/multi-agent.md` + `~/.claude/commands/multi-agent/` + `~/.claude/agents/`
+1. **Source**: `~/.claude/commands/multi-agent/` + `~/.claude/multi-agent-refs/` + `~/.claude/agents/` + `~/.claude/lib/`
 2. **Target**: `~/multi-agent-pipeline/pipeline/`
 3. **Genericization** (must be applied BEFORE writing to the target):
    - Jira project key (`prefs.global.defaultJiraKey`) -> `{JIRA_KEY}`, `PROJ` in examples
@@ -116,7 +116,6 @@ If nothing is stale → report "All targets up to date" and stop.
    - **Verify**: `grep` scan for personal/corporate data inside pipeline/ -> 0 results
 4. **File mapping**:
    ```
-   ~/.claude/commands/multi-agent.md      -> pipeline/commands/multi-agent.md
    ~/.claude/commands/multi-agent/        -> pipeline/commands/multi-agent/
    ~/.claude/multi-agent-refs/            -> pipeline/multi-agent-refs/   (refs + pickers, non-command)
    ~/.claude/commands/sim-test.md         -> pipeline/commands/sim-test.md

package/pipeline/multi-agent-refs/refactor/dev-toolkit-research.md

@@ -0,0 +1,72 @@
+# Dev-Toolkit Research (refactor Step 0c)
+
+Loaded on demand by `/multi-agent:refactor` Step 0c. The SKILL.md carries the step intro; this file is the full procedure.
+
+**Resolution**  -  configuration first, never a hardcoded path:
+
+1. `prefs.global.devToolkit` in `~/.claude/multi-agent-preferences.json`:
+
+```jsonc
+{
+  "enabled": true,
+  "label": "<human name>",
+  "localPath": "$HOME/<repo-dir>",              // the companion repo working copy
+  "mcpServerName": "<registered MCP server name>",
+  "packageName": "@<scope>/<package>",
+  "registry": "github-packages",                 // github-packages | npmjs | none
+  "repoUrl": "https://github.com/<owner>/<repo>"
+}
+```
+
+2. If unset, auto-detect from the MCP registration: read `mcpServers` in `~/.claude.json` (including each `projects[*].mcpServers`) and in `~/.claude/settings.json`; for a stdio entry whose command is `node`, take `dirname(args[0])`. Accept it only when that directory is a git repo whose `package.json` depends on `@modelcontextprotocol/sdk`.
+3. If neither resolves, skip this step and report "no dev-toolkit configured". Never guess a path, never clone.
+4. `enabled: false` skips the step.
+
+**Research axes**  -  a finding without a source link is not a finding:
+
+| # | Axis | Where to look | What to extract |
+|---|------|---------------|-----------------|
+| 1 | MCP protocol | spec revisions + `@modelcontextprotocol/sdk` releases | protocol features released since the pinned SDK range that the server does not use yet: tool annotations (`readOnlyHint` / `destructiveHint` / `idempotentHint` / `openWorldHint`), `outputSchema` + structured content, resource links in results, progress + cancellation, `tools/list_changed`, pagination, elicitation |
+| 2 | Host clients | Claude Code / Copilot CLI / Cursor / Antigravity docs + release notes | per-tool description budget, tool-count ceilings, naming conventions, image and output size limits, permission / allowlist ergonomics |
+| 3 | Peer servers | GitHub search on the same domain terms + `stars:>50` | tool surfaces we lack, conventions peers converged on, and what to discard as out of scope |
+| 4 | Wrapped tooling | `xcrun simctl help`, `idb`, `adb`, `xcodebuild`, Playwright release notes, Apple ITMS + App Store Review Guidelines | deprecated flags still in use, new capabilities worth a tool, audit rules that changed |
+| 5 | Field practice | X / Twitter, Reddit, MCP community threads | what server authors actually changed recently (transport choice, output-token diets, sandboxing, error shape) |
+
+**Audit the toolkit against the findings**  -  run the checks, do not assume:
+
+```bash
+DT="<resolved localPath>"
+node --check "$DT/index.js"
+find "$DT/tools" -name "*.js" -type f -exec node --check {} \;
+
+# stdout carries the JSON-RPC frames: a stray stdout write corrupts the stream
+grep -rn "console\.log(" "$DT/index.js" "$DT/tools" || echo "stdout clean"
+
+# advertised tool counts vs reality (README header + package.json description)
+grep -nE "[0-9]+ tools" "$DT/README.md" "$DT/package.json"
+
+# packaging: every runtime directory must be inside files[]
+node -p "require('$DT/package.json').files.join('\n')"
+ls -d "$DT"/tools/*/
+
+cd "$DT" && npm outdated; npm audit --omit=dev 2>/dev/null | tail -20
+```
+
+Also check: every tool carries a description and an `inputSchema`; token-heavy results (screenshots, UI trees, logs) are truncated or written to a file path instead of inlined; failures return an error result with an actionable message instead of throwing; `engines.node` matches what the SDK needs; `CHANGELOG.md`, a CI workflow and a test harness exist.
+
+Output (plan band E):
+
+```
+| # | Axis | Finding | Source | Adaptation in the toolkit (file) | Effort | Impact | In plan? |
+|---|------|---------|--------|----------------------------------|--------|--------|----------|
+| 1 | Protocol | read-only tools carry no annotations | <spec link> | add `annotations` to the read-only tools in index.js | Low | Medium | Yes (P1) |
+| 2 | Wrapped tooling | uses a simctl flag removed in Xcode <v> | <release notes> | switch tools/<family>/<file>.js to <new flag> | Low | High | Yes (P0) |
+| 3 | Peer servers | peer exposes <surface> | <repo link> | does not fit: outside the pipeline's phases | - | - | No |
+```
+
+Rules for this band:
+
+- Band-E work lands in the toolkit repo, never mirrored into this one. Shipping it is `/multi-agent:sync` Step 3d.
+- A finding that changes the tool surface (new / renamed / removed tool) pairs with a pipeline-side item: bump the minimum toolkit version wherever a pipeline skill declares one.
+- If the current working directory IS the toolkit repo, skip band E and let bands A/B/C cover it  -  never report the same finding twice.
+

package/pipeline/multi-agent-refs/setup/app-store-connect.md

@@ -0,0 +1,54 @@
+# App Store Connect Onboarding (setup Step 3b)
+
+Loaded on demand by `/multi-agent:setup` Step 3b (iOS only, optional). The SKILL.md carries the step intro; this file is the full flow.
+
+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.
+

package/pipeline/multi-agent-refs/tracker-contract.md

@@ -142,7 +142,7 @@ Mode-specific phase sets:
 
 Note: in `--dev` modes the omitted phases (1, 2  -  plus 5 in the autopilot/local variants) **do not get TaskCreate calls at all**  -  they're not part of the mode's phase set. Phase 4 is in every mode's set as of v14.0.0, so it is always registered. The "[SKIPPED]" pattern above only applies if a phase that IS in the set is conditionally skipped at runtime. The authoritative per-mode set is the `for p in ...` init block in each mode's own entry doc, generated by `gen-mode-dispatch.mjs`; this table mirrors those blocks.
 
-**Enforcement**: `smoke-tasklist-ordering.sh` scans every mode entry point doc (`commands/multi-agent.md`, `commands/multi-agent/{autopilot,local,local-autopilot,dev,dev-autopilot,dev-local,dev-local-autopilot}.md` + Copilot mirrors) for the explicit "in phase-number order" rule. Inventory drift fails the smoke.
+**Enforcement**: `smoke-tasklist-ordering.sh` scans the dispatcher (`commands/multi-agent/SKILL.md`) and every mode entry point doc (`commands/multi-agent/{dev,autopilot,local,local-autopilot,dev-autopilot,dev-local,dev-local-autopilot,resume-local}/SKILL.md` + the Copilot full-inline orchestrator mirror) for the explicit "in phase-number order" rule. Inventory drift fails the smoke.
 
 ### Other CLIs  -  call render after every state change
 

package/pipeline/skills/shared/core/multi-agent/SKILL.md

@@ -28,7 +28,7 @@ If user gives wrong format for the project, warn:
 
 ## Input Parsing
 
-Classify user input into one of 5 types (matches the colon-form `multi-agent.md` contract; cross-CLI parity is enforced by `smoke-cross-cli-behavior.sh`):
+Classify user input into one of 5 types (matches the `commands/multi-agent/SKILL.md` dispatcher contract; cross-CLI parity is enforced by `smoke-cross-cli-behavior.sh`):
 
 | # | Pattern | Type | Action |
 |---|---------|------|--------|

package/pipeline/skills/shared/core/multi-agent-refactor/SKILL.md

@@ -114,73 +114,7 @@ Procedure:
 
 The pipeline's hands on devices and browsers are MCP tools served by a companion repo (`dev-toolkit-mcp`): Phase 5 test, `manual-test`, `design-check` and `apple-archive-compliance` all call them, and several pipeline skills declare a minimum toolkit version (see `cross-cli-contract.md`). That repo therefore has to track the MCP field, not just its own README. This step researches what current practice is and audits the toolkit against it.
 
-**Resolution**  -  configuration first, never a hardcoded path:
-
-1. `prefs.global.devToolkit` in `~/.claude/multi-agent-preferences.json`:
-
-```jsonc
-{
-  "enabled": true,
-  "label": "<human name>",
-  "localPath": "$HOME/<repo-dir>",              // the companion repo working copy
-  "mcpServerName": "<registered MCP server name>",
-  "packageName": "@<scope>/<package>",
-  "registry": "github-packages",                 // github-packages | npmjs | none
-  "repoUrl": "https://github.com/<owner>/<repo>"
-}
-```
-
-2. If unset, auto-detect from the MCP registration: read `mcpServers` in `~/.claude.json` (including each `projects[*].mcpServers`) and in `~/.claude/settings.json`; for a stdio entry whose command is `node`, take `dirname(args[0])`. Accept it only when that directory is a git repo whose `package.json` depends on `@modelcontextprotocol/sdk`.
-3. If neither resolves, skip this step and report "no dev-toolkit configured". Never guess a path, never clone.
-4. `enabled: false` skips the step.
-
-**Research axes**  -  a finding without a source link is not a finding:
-
-| # | Axis | Where to look | What to extract |
-|---|------|---------------|-----------------|
-| 1 | MCP protocol | spec revisions + `@modelcontextprotocol/sdk` releases | protocol features released since the pinned SDK range that the server does not use yet: tool annotations (`readOnlyHint` / `destructiveHint` / `idempotentHint` / `openWorldHint`), `outputSchema` + structured content, resource links in results, progress + cancellation, `tools/list_changed`, pagination, elicitation |
-| 2 | Host clients | Claude Code / Copilot CLI / Cursor / Antigravity docs + release notes | per-tool description budget, tool-count ceilings, naming conventions, image and output size limits, permission / allowlist ergonomics |
-| 3 | Peer servers | GitHub search on the same domain terms + `stars:>50` | tool surfaces we lack, conventions peers converged on, and what to discard as out of scope |
-| 4 | Wrapped tooling | `xcrun simctl help`, `idb`, `adb`, `xcodebuild`, Playwright release notes, Apple ITMS + App Store Review Guidelines | deprecated flags still in use, new capabilities worth a tool, audit rules that changed |
-| 5 | Field practice | X / Twitter, Reddit, MCP community threads | what server authors actually changed recently (transport choice, output-token diets, sandboxing, error shape) |
-
-**Audit the toolkit against the findings**  -  run the checks, do not assume:
-
-```bash
-DT="<resolved localPath>"
-node --check "$DT/index.js"
-find "$DT/tools" -name "*.js" -type f -exec node --check {} \;
-
-# stdout carries the JSON-RPC frames: a stray stdout write corrupts the stream
-grep -rn "console\.log(" "$DT/index.js" "$DT/tools" || echo "stdout clean"
-
-# advertised tool counts vs reality (README header + package.json description)
-grep -nE "[0-9]+ tools" "$DT/README.md" "$DT/package.json"
-
-# packaging: every runtime directory must be inside files[]
-node -p "require('$DT/package.json').files.join('\n')"
-ls -d "$DT"/tools/*/
-
-cd "$DT" && npm outdated; npm audit --omit=dev 2>/dev/null | tail -20
-```
-
-Also check: every tool carries a description and an `inputSchema`; token-heavy results (screenshots, UI trees, logs) are truncated or written to a file path instead of inlined; failures return an error result with an actionable message instead of throwing; `engines.node` matches what the SDK needs; `CHANGELOG.md`, a CI workflow and a test harness exist.
-
-Output (plan band E):
-
-```
-| # | Axis | Finding | Source | Adaptation in the toolkit (file) | Effort | Impact | In plan? |
-|---|------|---------|--------|----------------------------------|--------|--------|----------|
-| 1 | Protocol | read-only tools carry no annotations | <spec link> | add `annotations` to the read-only tools in index.js | Low | Medium | Yes (P1) |
-| 2 | Wrapped tooling | uses a simctl flag removed in Xcode <v> | <release notes> | switch tools/<family>/<file>.js to <new flag> | Low | High | Yes (P0) |
-| 3 | Peer servers | peer exposes <surface> | <repo link> | does not fit: outside the pipeline's phases | - | - | No |
-```
-
-Rules for this band:
-
-- Band-E work lands in the toolkit repo, never mirrored into this one. Shipping it is `/multi-agent:sync` Step 3d.
-- A finding that changes the tool surface (new / renamed / removed tool) pairs with a pipeline-side item: bump the minimum toolkit version wherever a pipeline skill declares one.
-- If the current working directory IS the toolkit repo, skip band E and let bands A/B/C cover it  -  never report the same finding twice.
+Full procedure  -  resolution (configuration first, never a hardcoded path; skip when nothing resolves or `enabled` is false), the 5 research axes, the audit command block, and the band-E output table + rules  -  lives in `$HOME/.claude/multi-agent-refs/refactor/dev-toolkit-research.md`. Read it before running this step.
 
 ## Step 0d: RUN-ERRORS  -  what the pipeline actually failed on
 

package/pipeline/skills/shared/core/multi-agent-sync/SKILL.md

@@ -18,7 +18,7 @@ When invoked, it synchronizes all targets in order. It detects what changed, upd
 
 | # | Target | Path | Direction |
 |---|-------|-----|-----|
-| 1 | Claude Code (source of truth) | `~/.claude/commands/multi-agent.md` + `~/.claude/commands/multi-agent/` + `~/.claude/agents/` + `~/.claude/scripts/` | source |
+| 1 | Claude Code (source of truth) | `~/.claude/commands/multi-agent/` + `~/.claude/multi-agent-refs/` + `~/.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) |
@@ -56,7 +56,7 @@ If nothing is stale -> report "All targets up to date" and stop.
 
 1. **Read first**  -  Understand the current state of all targets before making changes
 2. **Preserve file structure**  -  Each target has its own format:
-   - `multi-agent.md` + phases/: detailed pipeline spec (frontmatter, phases, routing)
+   - `commands/multi-agent/` SKILL tree + `multi-agent-refs/phases/`: detailed pipeline spec (frontmatter, phases, routing)
    - `copilot-instructions.md`: general development instructions + pipeline summary section
    - `multi-agent-pipeline/pipeline/`: generic open-source version (NO personal data)
 3. **Sync shared sections** (Claude <-> Copilot):
@@ -71,7 +71,7 @@ If nothing is stale -> report "All targets up to date" and stop.
 
 ## Pipeline Repo Sync Rules (CRITICAL)
 
-1. **Source**: `~/.claude/commands/multi-agent.md` + `~/.claude/commands/multi-agent/` + `~/.claude/agents/`
+1. **Source**: `~/.claude/commands/multi-agent/` + `~/.claude/multi-agent-refs/` + `~/.claude/agents/` + `~/.claude/lib/`
 2. **Target**: `~/multi-agent-pipeline/pipeline/`
 3. **Genericization** (must be applied BEFORE writing to the target):
    - Jira project key (`prefs.global.defaultJiraKey`) -> `{JIRA_KEY}`, `PROJ` in examples
@@ -82,8 +82,8 @@ If nothing is stale -> report "All targets up to date" and stop.
    - **Verify**: scan for personal/corporate data inside pipeline/ with `grep` -> 0 results
 4. **File mapping**:
    ```
-   ~/.claude/commands/multi-agent.md      -> pipeline/commands/multi-agent.md
    ~/.claude/commands/multi-agent/        -> pipeline/commands/multi-agent/
+   ~/.claude/multi-agent-refs/            -> pipeline/multi-agent-refs/   (refs + pickers, non-command)
    ~/.claude/commands/sim-test.md         -> pipeline/commands/sim-test.md
    ~/.claude/agents/*.md                  -> pipeline/agents/
    ```