@mmerterden/multi-agent-pipeline 12.11.0 → 13.1.0

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

@@ -20,6 +20,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/` | 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 |
@@ -30,7 +31,8 @@ Run all steps automatically:
 
 ```
 Step 1: 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)
 Step 3d: DEV-TOOLKIT Companion MCP server -> detect movement, ship gates, commit + publish
 Step 4: WEBSITE     Version + phase/model counts -> {website-host} (i18n + projects.ts)
@@ -93,6 +95,41 @@ If nothing is stale -> report "All targets up to date" and stop.
    - `~/.claude/settings.json`
 
 
+## Codex Sync (Step 2b)
+
+This step does **not** hand-copy files. The Codex tree is a *transform* of the Claude
+tree, not a mirror: the 43 sub-command specs become reference files (Codex silently
+truncates its skills block  -  see `cross-cli-contract.md` 2.6), every reference to a
+CLI-owned tree is retargeted (`agents/<persona>.md` becomes `.toml`, the dispatcher
+becomes the router skill), the 8 personas are regenerated as TOML with a model +
+reasoning-effort map, and shared state (`logs/`, prefs, `knowledge/`) is deliberately
+left under `~/.claude`.
+
+That transform lives in `install/codex.mjs` and is gate-locked by
+`smoke-codex-install.sh`. Describing it again in prose would give the pipeline two
+definitions of the same thing, and the prose one would rot. So the step runs the
+installer:
+
+```bash
+cd "$HOME/multi-agent-pipeline" && node install.js --codex
+```
+
+Verify:
+
+```bash
+ls -1 "$HOME/.codex/skills" | grep -c '^multi-agent$'                  # want 1
+find "$HOME/.codex/multi-agent-refs/commands" -name SKILL.md | wc -l  # want the command count
+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 is registered by the installer via `codex mcp add dev-toolkit` (idempotent,
+skipped with a warning when `codex` is absent). Never hand-edit
+`~/.codex/config.toml`  -  Codex owns it. Run this AFTER the REPO step, since the
+installer reads the repo tree.
+
+---
+
 ## Dev-Toolkit Sync (Step 3d)
 
 The companion MCP server (`dev-toolkit-mcp`) is its own repo with its own registry. Pipeline skills call its tools and several declare a minimum version, so when it moves it has to ship.
@@ -114,13 +151,19 @@ When the toolkit ships its own gate script (`npm run gates` / `scripts/gates.sh`
 
 **Version bump**: patch for fixes and docs, minor for a new tool, major for a removed or renamed tool.
 
-**Ship**: commit with that repo's own convention, tag `v<version>`, push with `--tags`, then publish to the registry from `publishConfig` using a throwaway userconfig  -  never edit `~/.npmrc`, never a bare `npm publish`. The token depends on the registry: `npm.pkg.github.com` needs a GitHub PAT with `write:packages` (logical key `github`), `registry.npmjs.org` needs the `npm` key.
+**Ship**: commit with that repo's own convention, tag `v<version>`, push with `--tags`, then publish to the registry from `publishConfig` using a throwaway userconfig  -  never edit `~/.npmrc`, never a bare `npm publish`. The token depends on the registry AND on the package scope: the registry picks the credential type, the scope picks the account. `npm.pkg.github.com` needs a **Classic** GitHub PAT with `write:packages`; `registry.npmjs.org` needs the `npm` key. Resolving on host alone misroutes on any machine with a work and a personal GitHub identity  -  prefer a scope-specific mapping (`github_<scope>`) and fall back to the generic `github` key only when there is one identity.
 
 ```bash
 NPMRC=$(mktemp); trap 'rm -f "$NPMRC"' EXIT
 REG=$(node -p "require('./package.json').publishConfig?.registry || 'https://registry.npmjs.org'")
 HOST=${REG#https://}; HOST=${HOST%/}
-case "$HOST" in npm.pkg.github.com*) KEY=github ;; *) KEY=npm ;; esac
+SCOPE=$(node -p "(require('./package.json').name.match(/^@([^/]+)/)||[])[1] || ''")
+case "$HOST" in
+  npm.pkg.github.com*) KEY=github; [ -n "$SCOPE" ] && KEY="github_$SCOPE" ;;
+  *) KEY=npm ;;
+esac
+# Fall back to the generic key when no scope-specific mapping exists.
+bash "$HOME/.copilot/lib/credential-store.sh" get "$KEY" >/dev/null 2>&1 || KEY=github
 TOKEN=$(bash "$HOME/.claude/lib/credential-store.sh" get "$KEY")
 [ -n "$TOKEN" ] || echo "ABORT: no '$KEY' token - onboard it via /multi-agent:setup before publishing"
 printf '%s\n' "registry=$REG" "//$HOST/:_authToken=$TOKEN" > "$NPMRC"
@@ -167,24 +210,27 @@ 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
 ```
 
 
 ## Sub-Command Sync (Claude Code <-> Copilot CLI Skills)
 
+> Codex takes the Step 2b path instead; see that section.
+
 | Claude Code | Copilot CLI |
 |-------------|-------------|
 | `~/.claude/commands/multi-agent/{cmd}.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**: `refs/*`  -  Lazy-load references, Claude Code specific
@@ -200,8 +246,43 @@ routines, save, scan, search, setup, stack, status, sync, test, uninstall, updat
 | `gh` CLI (personal) | `{owner}` gh auth (Keychain) |
 | `gh` CLI (work) | `${USER}_{work-gh-alias}` gh auth (Keychain) |
 | npm publish | `NODE_AUTH_TOKEN`  -  `GITHUB_TOKEN` in CI, Keychain PAT locally |
-| dev-toolkit publish (Step 3d) | `npm` logical Keychain key -> throwaway `--userconfig`, registry from that repo's `publishConfig` |
+| dev-toolkit publish (Step 3d) | scope-resolved key (`github_<scope>`, else `github`, else `npm`) -> throwaway `--userconfig`, registry from that repo's `publishConfig` |
 
 ```bash
 gh auth switch --user {owner}  # for personal repos
 ```
+
+
+## Pre-flight the token scope
+
+GitHub reports a token's scopes on any authenticated request, so check before
+uploading instead of reading it out of a 403:
+
+```bash
+curl -sI -H "Authorization: token $TOKEN" https://api.github.com/user \
+  | grep -i '^x-oauth-scopes:' | grep -q 'write:packages'
+```
+
+Candidate order for `npm.pkg.github.com`, because storage location and scope are
+not correlated: `github_<scope>` from the mapping, then `gh auth token -u <scope>`
+(gh's own OAuth token often carries `write:packages` when a hand-made PAT does
+not), then the generic `github` key only on a single-identity machine. Take the
+first candidate whose scopes include `write:packages` AND whose login matches the
+package scope. If none qualifies, stop before publishing and report each candidate
+with the login it resolved to and the scope it was missing  -  that is the
+actionable output, not a 403 body.
+
+## Publish 403s: two causes, two fixes
+
+Neither message says "wrong token" plainly, and they need opposite responses:
+
+- `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. No scope grant fixes this; map the personal account's PAT
+  under `github_<scope>`.
+- `The token provided does not match expected scopes`  -  right account, missing
+  permission. Regenerate as a **Classic** PAT with `write:packages`
+  (plus `repo` for a private package) and re-onboard through setup.
+
+Always report which of the two occurred. "Permission denied" alone sends the user
+to regenerate a token that was never the problem.

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

@@ -0,0 +1,120 @@
+---
+name: multi-agent-testflight-validation
+language: en
+description: "Pre-submission validation for a TestFlight / App Store build (iOS, local-only). Three gates: static archive audit, Apple's own `altool --validate-app`, and a Review-Guidelines check. ITMS codes are mapped to the rule each implies. Validates only, never uploads. Use when a build is about to go to TestFlight, or a submission was rejected and you need why."
+user-invocable: true
+argument-hint: "[repo]  -  empty = pick from prefs; repo name or path; --ipa=<path>; --archive=<path>; --resume"
+---
+
+# multi-agent-testflight-validation  -  pre-submission validation
+
+Catch, before you upload, what App Store Connect would send back after you do.
+
+**Local-only**: no commits, no push, no PR, no channels. **It never uploads**  -  only
+`--validate-app` is ever invoked, never `--upload-app`.
+
+## Why three gates
+
+Each sees something the others structurally cannot, so reporting one as "the check"
+is how a build passes locally and gets rejected anyway.
+
+| Gate | Runs | Needs | Sees | Blind to |
+|---|---|---|---|---|
+| **1. Static** | `ios_app_store_audit` (18 rules) | `.xcarchive` | privacy manifest, required-reason API, Info.plist, signing, entitlements, embedded SDK, IPv6, debug leak | anything account-dependent |
+| **2. Authoritative** | `ios_testflight_validate` → `altool --validate-app` | `.ipa` + credentials | unregistered bundle ID, profile/app-record mismatch, **version+build already used**, entitlement not provisioned | the Review Guidelines |
+| **3. Guideline** | `app-store-review` skill + repo evidence | repo checkout | ATT, privacy policy, account deletion, IAP, purpose-string wording | anything not in source |
+
+Most "we passed validation and still got rejected" cases are Gate 3 findings:
+Apple's validator does not read the Review Guidelines.
+
+## Flow
+
+**0. Input.** `(empty)` → ask · `my-ios-app`/path → that repo · `--ipa=<path>` →
+Mode B without Gate 1 · `--archive=<path>` → Mode B with all gates · `--resume`.
+State at `~/.claude/logs/multi-agent/<task_id>/agent-state.json`,
+`taskId = TFV-<repo>-<yyyymmddHHMM>`. Register phases with
+`bash ~/.copilot/scripts/phase-tracker.sh` and render with
+`phase-tracker.sh render` at every boundary.
+
+**1. Pickers.** Repo (iOS entries in `prefs.projects`; a single match auto-resolves,
+and the breadcrumb says so) → branch → mode. Print
+`Step <i>/<n>: <what this decides>` for each. On `git fetch` failure do **not**
+silently use a cached ref, and **classify the failure before naming a cause**:
+`could not read Password` / `Authentication failed` / `403` is a credential
+problem, not a network one, and a VPN cannot fix it; `Could not resolve host` /
+`Operation timed out` is the network. Show the stderr line verbatim next to your
+classification, then offer the remedy that matches it. Only the network case gets
+the continue-on-a-stale-ref option: for a credential failure, staleness is
+unrelated to what broke.
+
+**2. Pre-flight.** `xcrun --find altool` and `xcodebuild -version`; a missing
+prerequisite halts. Resolve credentials and name the active tier in the report:
+tier 1 ASC API key (key id + issuer id from the keychain via
+`prefs.global.keychainMapping`, `.p8` at
+`~/.appstoreconnect/private_keys/AuthKey_<keyId>.p8`), tier 2 Apple ID +
+app-specific password by keychain reference, tier 3 none → **Gate 2 is `SKIPPED`
+and the verdict line says so**. Credentials come from `/multi-agent:setup`; never
+prompt for a secret value in chat. Tier 2 needs no elevated App Store Connect
+role, which matters when API-key creation is not permitted on the account.
+
+**3. Obtain the build.**
+- Mode B `.xcarchive` → Gate 1 runs; export with `ios_export_ipa` to reach Gate 2.
+- Mode B `.ipa` only → **Gate 1 `SKIPPED (needs .xcarchive)`**. The static audit
+  reads archive structure an `.ipa` does not carry. Do not present a two-gate run
+  as a full pass.
+- Mode A → worktree at `{projectRoot}/{worktreeBasePath}/{taskId}` (**never under
+  `$HOME`**) → `ios_xcodebuild({action: "archive", configuration: "Release",
+  destination: "generic/platform=iOS"})`  -  the simulator default would produce a
+  non-distributable archive  -  then `ios_export_ipa({method:
+  "app-store-connect", team_id, ...})`. Leave `allow_provisioning_updates` off
+  unless asked: it lets xcodebuild create or modify profiles in the developer
+  account, which a validation run has no business doing.
+
+**4. Gate 1.** `ios_app_store_audit({archive_path, rules: "all"})`. `error` blocks,
+`warning` advises. Keep each ITMS code  -  Gate 2 may return the same one, and that
+agreement tells the user it is real.
+
+**5. Gate 2.** `ios_testflight_validate({ipa_path, platform: "ios", <creds>})`.
+Render the verdict as returned: `PASS` / `FAIL` (each issue with ITMS code, mapped
+guideline, hint) / `SKIPPED` (with the reason, **never as a pass**). This is the
+only gate that catches an already-used build number  -  the most common wasted
+upload  -  so when it fails on that, name the next free build number.
+
+**6. Gate 3.** Load `app-store-review` and check, with an evidence path each:
+purpose strings (present, specific, matching actual use) · `PrivacyInfo.xcprivacy`
+(exists, declares required-reason APIs, matches linked SDKs) · ATT before any
+tracking · in-app account deletion when accounts are created · privacy policy
+reachable · IAP through StoreKit with no external purchase path · Sign in with
+Apple alongside third-party social login. Mark `pass` / `fail` /
+`not-applicable`, and `not-applicable` needs a reason  -  an unexamined area is not
+a pass.
+
+**7. Report.** `~/TestFlightChecks/<repo>-<branch>-<timestamp>/report.md` plus a
+printed summary:
+
+```
+Verdict: <N> of 3 gates cleared[, <M> skipped]
+Build:   <path>  ·  <bundle id> <version> (<build>)
+Auth:    tier <1|2|none>  ·  <method>
+
+Gate 1  static audit        PASS | FAIL (<n> blocking, <n> advisory) | SKIPPED (<reason>)
+Gate 2  Apple validation    PASS | FAIL (<n> issues) | SKIPPED (<reason>)
+Gate 3  guideline review    PASS | FAIL (<n> findings) | <n> not-applicable
+
+Blocking  -  fix before uploading
+  [ITMS-90683] Info.plist: NSCameraUsageDescription missing
+      guideline 5.1.1 Data Collection and Storage
+      <hint>  ·  <file:line>
+
+Not run
+  Gate 1: needs an .xcarchive; only an .ipa was supplied
+```
+
+A skipped gate is never folded into the pass count. Every blocking finding carries
+a file path or an ITMS code. No AI or assistant attribution anywhere; real
+newlines, no HTML entities.
+
+**8. Offer, do not act.** Print the exact `xcrun altool --upload-app` command for
+when the gates are clear (uploading stays an explicit human act), plus
+`--resume` after fixes and `/multi-agent:fix-bug` for code-level Gate 3 findings.
+Never upload, never bump the build number, never commit.