--- description: "One-shot sync of the entire multi-agent ecosystem: Claude Code, Copilot CLI, pipeline repo, website, and the multi-agent-toolkit MCP server. Use when work is finished and should be propagated across Claude Code, Copilot CLI, the repos, the website and the multi-agent-toolkit server." description-tr: "Tüm multi-agent ekosisteminin tek atımlık senkronu: Claude Code, Copilot CLI, pipeline repo, website ve multi-agent-toolkit MCP sunucusu." argument-hint: "[release] [multi-agent-toolkit]" parameters: [{"name":"release","kind":"flag"},{"name":"multi-agent-toolkit","kind":"flag"}] gui: hidden destructive: false confirm: required allowed-tools: Read, Write, Edit, Bash, Glob, Grep, AskUserQuestion, WebFetch --- # Multi-Agent Sync **One command. Full ecosystem sync. No arguments needed.** When invoked, it synchronizes all targets in order. It detects what changed, updates only the stale ones, and returns a result report. macOS only (ADR-0012); credential access goes through `~/.claude/lib/credential-store.sh` so no call site names the keychain backend. **Input**: $ARGUMENTS (optional) | Arg | Meaning | |---|---| | (none) | Full ecosystem sync: Claude Code, Copilot CLI, pipeline repo, website, multi-agent-toolkit MCP server. | | `release` | Full sync + version bump + tag + npm publish + website deploy (plus the multi-agent-toolkit ship path) | | `multi-agent-toolkit` | Run Step 3d only: gate, commit and publish the companion MCP server | | `"change description"` | Apply the description to every target at once | ## Gotchas - The pre-push gate is timing-sensitive: under heavy load a deadline test fails closed. Re-run it on a quiet machine; never push with `--no-verify`. - `npm publish` answering 202 means the registry is still processing. Verify with the registry's dist-tags before moving `required`, which is asked for every release. - The installed tree is localized (Turkish descriptions, `model: opus` while fable is off). Normalize before copying into the repo, or the public tree ships the local form. - Synced shell runs on BSD userland: BSD grep has no Perl-regex flag, and `sed` has no `\b` or `\|`. A pattern that silently matches nothing reads as "clean". ## Targets | # | Target | Path | Direction | |---|-------|-----|-----| | 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) | | 4 | Website | `{owner}/{website-host}` | <- version + features | | 5 | multi-agent-toolkit MCP server | resolved from `prefs.global.devToolkit` or the `mcpServers` registration | own repo: gate, commit, publish | ## Platform Support (macOS only) Only macOS is supported (ADR-0012). `package.json` declares `os: ["darwin"]`, which npm enforces on the root package, so this tree cannot be installed elsewhere, and a detection table for other hosts would describe a case that cannot occur. **Contract for synced shell scripts.** The runtime is BSD userland and bash 3.2, and that is a stricter constraint than "cross-platform", not a looser one: 1. Path handling: always quote (`"$f"`); use `$HOME`, never `/Users/...`. 2. `grep -P` is banned. BSD grep has no `-P`: it exits 2, and with `2>/dev/null` that reads as "found nothing". Two gates have already shipped green for exactly this reason. Use `-E`. 3. Timestamps: `stat -c %Y` FIRST, then `stat -f %m`. GNU-first ordering is required because `stat -f` is a valid GNU flag (`--file-system`) that succeeds and prints something that is not a timestamp. 4. Hashes: `sha256sum || shasum`, in that order. The gate fails a file that names either alone. 5. `find` traversal: `-prune` for `node_modules`, `Pods`, `.build`, `DerivedData`, `.next`. 6. Sed / awk: POSIX-portable. `-E`, never `-r`; `sed -i ''` on BSD. 7. Keychain I/O: always via `~/.claude/lib/credential-store.sh get|set`, never `security` directly - the wrapper is what keeps a secret off argv. 8. Verification: after Step 3 (REPO), `bash -n` every shell script in `pipeline/lib/` and `pipeline/scripts/`. ## Default Behavior (no arguments) Run every step automatically: ``` Step 0: DOCTOR doctor.mjs - exit 2 or 4 stops the sync Step 1.5: DETECT Compare timestamps, find stale targets Step 2: COPILOT Claude Code -> Copilot CLI (instructions + 64 sub-command skills) Step 2b: CODEX Claude Code -> Codex CLI (1 router skill + sub-command specs as refs + 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) Step 3d: DEV-TOOLKIT companion MCP server -> detect movement, run the ship gates, commit + publish Step 4: WEBSITE Version + phase/model counts -> {website-host} (i18n + projects.ts) Step 5: Commit Commit + push all changed repos Step 6: Report Summary: synced targets, platform, changed files, deploy status, multi-agent-toolkit version ``` If nothing is stale → report "All targets up to date" and stop. Step 0 gate rules and why: `features/doctor.md`. --- ## Sync rules 1. **Read first** - understand every target's current state before making any change 2. **Preserve file structure** - each target has its own format: - `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): - Pipeline entries table (base / :autopilot) - Project detection (URL-based + cwd-based) - Figma pipeline flow - Git conventions (author, branch, commit format) - Keychain management (registry, naming convention, multi-agent pattern) 4. **Do not duplicate** - summary in Copilot, full spec in Claude. Keep this distinction. 5. **Report** - show a short diff summary after sync --- ## Pipeline Repo Sync Rules (CRITICAL) 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 - Personal names/emails -> generic placeholder - Branch names -> `develop` - Project names -> `my-app` - `{JIRA_HOST}`, `{BITBUCKET_HOST}`, `{CONFLUENCE_HOST}`, `{CORP_DOMAIN}` stay as-is - **Verify**: `grep` scan for personal/corporate data inside pipeline/ -> 0 results 4. **File mapping**: ``` ~/.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/ ``` 5. **Files NOT synced** (local-only, may contain personal data): - `~/.claude/multi-agent-preferences.json` - `~/.claude/CLAUDE.md`, `~/.claude/rules/`, `~/.claude/knowledge/` - `~/.claude/scripts/` - EXCEPT `pre-commit-check.sh`, `agent-guard.sh`, `agent-guard.py`, and `build-stack-plugins.mjs` (generic, synced) - `~/.claude/settings.json` - `~/.claude/multi-agent-refs/registries/` - the installer copies gate registries there from `pipeline/skills/shared/external`; the repo already holds the source - **Any `~/.claude/commands/multi-agent/*/SKILL.md` whose frontmatter has `local-only: true`** - these are user/repo-specific alias wrappers that delegate to a private marketplace plugin's skills exposed as `multi-agent:`. Syncing them would leak the private plugin/skill names into the public pipeline. Skip them at copy time; the backstop below proves none reached `pipeline/commands/`. ```bash grep -rl "^local-only: true" ~/multi-agent-pipeline/pipeline/commands/ 2>/dev/null \ && { echo "ABORT: local-only wrapper leaked into pipeline/commands"; exit 1; } || true # backstop: corporate refs only (generic ai-ios-toolkit is fine) grep -rniE "ai-(ios-engineering|mobile)-toolkit:(create-ui-component|evolve-ui-component|fix-bug|branch-and-pr|backlog|code-connect|figma-utility|resource-utility|component-wiki|component-docs|figma-setup)" \ ~/multi-agent-pipeline/pipeline/commands/ 2>/dev/null \ && { echo "ABORT: corporate reference leaked into pipeline/commands"; exit 1; } || true ``` - **Installed-tree artifacts.** Picker descriptions are Turkish with a `description-en:` sidecar when `outputLanguage=tr`, and fable-tier agents carry `model: opus` while `fableEnabled` is off. The repo always gets the English form and `model: fable`, so normalize after copying: ```bash # normalize: restore English descriptions, strip description-en sidecars node ~/multi-agent-pipeline/pipeline/scripts/localize-commands.mjs restore \ --dir ~/multi-agent-pipeline/pipeline/commands/multi-agent grep -rl "^description-en:" ~/multi-agent-pipeline/pipeline/commands/ 2>/dev/null \ && { echo "ABORT: description-en sidecar leaked into pipeline/commands"; exit 1; } || true # backstop: repo description lines must be English (Turkish-diacritics proxy) grep -rn '^description:.*[çğıöşüÇĞİÖŞÜ]' ~/multi-agent-pipeline/pipeline/commands/ 2>/dev/null \ && { echo "ABORT: localized description leaked into pipeline/commands"; exit 1; } || true node ~/multi-agent-pipeline/pipeline/lib/agent-model-sync.mjs --dir ~/multi-agent-pipeline/pipeline/agents --fable-on ``` 6. **Cross-platform smoke gate** (final step of the REPO sync, before push): ```bash # bash -n: parse-level syntax check on every shell script find ~/multi-agent-pipeline/pipeline/lib ~/multi-agent-pipeline/pipeline/scripts \ -name "*.sh" -type f -exec bash -n {} \; # Should print nothing - any output is a portability regression. # Portability grep: flag known non-portable constructs introduced post-sync. grep -rnE "stat -f[^[:space:]]+[^|]|sed -i[^[:space:]'\"]" \ ~/multi-agent-pipeline/pipeline/lib ~/multi-agent-pipeline/pipeline/scripts || true # Each hit needs an explicit GNU/BSD fallback per the Platform Support contract. ``` Gate failure -> abort push, surface the file + line, fix in the `~/.claude/` source first, re-sync. --- ## Codex Sync (Step 2b) Full procedure: `$HOME/.claude/multi-agent-refs/sync/codex.md`. Read it before Step 2b; it runs after Step 3. ## Stack-Plugin Sync (Step 3c) Full procedure: `$HOME/.claude/multi-agent-refs/sync/stack-plugins.md`. Read it before Step 3c. ## Dev-Toolkit Sync (Step 3d) Full procedure: `$HOME/.claude/multi-agent-refs/sync/dev-toolkit.md`. Read it before Step 3d, and for `/multi-agent:sync multi-agent-toolkit`. ## Website Sync (Step 4) Propagate version, phase and model counts and feature descriptions to the website. ```bash gh auth switch --user {owner} WEBSITE_DIR="$HOME/{website-host}" [ ! -d "$WEBSITE_DIR" ] && gh repo clone {owner}/{website-host} "$WEBSITE_DIR" cd "$WEBSITE_DIR" && git pull origin main ``` | File | What to sync | |-------|--------------| | `src/lib/i18n.tsx` | Phase count, model count, feature descriptions (EN + TR) | | `src/data/projects.ts` | Version number, tagline, description, feature list | ```bash # A commit the platform does not recognise is pushed fine and never built, so the site # keeps the old version. {identity} is the one routed to {owner}, not the run's own. # Why, signature, recovery: `$HOME/.claude/multi-agent-refs/website-deploy.md`. bash "$HOME/.claude/scripts/website-deploy-commit.sh" "{identity.name}" "{identity.email}" "{VERSION}" "$WEBSITE_DIR" ``` --- ## Release Flow When invoked with the `release` argument: ``` 1. REPO Claude Code -> pipeline repo (genericized) 2. VERIFY Personal data scan -> 0 results; config-hygiene scan (scan-agent-config.sh) -> 0 HIGH 3. LINT + TEST ESLint + smoke tests (stale .skill-manifest.json fails here; re-sign it with sign-skills.sh whenever a SKILL.md moved) 4. VERSION package.json version bump (patch/minor/major) 5. Commit + TAG git commit + git tag v{VERSION} 6. PUSH git push --tags; publish is local (release.yml off) 7. DEV-TOOLKIT Ship the companion MCP server if it moved (Step 3d gates, then publish) 8. WEBSITE Version + features -> {website-host} (maintainer identity, build verified Ready) 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) This runs on the Claude <-> Copilot axis. Codex is NOT synced here: it receives the same 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` | **64 commands are synced** (canonical inventory - must match `cross-cli-contract.md` section 1; drift = contract violation): ``` analysis, analysis-jira, analysis-resolve, autopilot, autopilot-off, autopilot-on, autopilot-status, bug-bash, build-optimize, channels, complaint-analysis, create-jira, design-check, diff-explain, doctor, estimate, feedback, forget, garbage-collect, graph, help, ios-coding-standard, issue, jira, kill, language, log, manual-test, model, prune-logs, prune-prompts, purge, refactor, research, resume, review, review-analysis, review-issue, review-jira, route-off, route-on, route-status, routines, save, scaffold, scan, scenario-audit, search, security-review, serve, setup, stack, status, steer, store-ready, sync, test, test-accessibility, test-dark-mode, test-dynamic-type, test-screenshots, testflight-validation, uninstall, update ``` **NOT synced**: `$HOME/.claude/multi-agent-refs/*` - lazy-load references, Claude Code specific **Claude -> Copilot**: add SKILL.md frontmatter (`name`, `description`, `user-invocable: true`, `argument-hint`) **Copilot -> Claude**: simplify the frontmatter (`description` + `allowed-tools`), add `$ARGUMENTS` --- ## Keychain Token Access | Operation | Token Source | |-------|---------------| | `gh` CLI (personal) | `{owner}` gh auth (Keychain) | | `gh` CLI (work) | `{user}_` gh auth (Keychain) - see `prefs.global.accounts[]` | | npm publish | `NODE_AUTH_TOKEN` - `GITHUB_TOKEN` in CI, Keychain PAT locally | | multi-agent-toolkit publish (Step 3d) | `npm` logical Keychain key -> throwaway `--userconfig`, registry from that repo's `publishConfig` | ```bash gh auth switch --user {owner} # for personal repos ```