Cross-repo migration swarm — one coordinator + N parallel subagents (one per target repo) that apply the same transformation, open PRs, wait for CI, and report back to a shared JSON ledger. Coordinator handles topology, conflict auto-rebase, and stop-on-novel-failure. Use when bumping a shared dependency, rolling out a workflow change, or applying a codemod across the org. Do NOT use for single-repo work — that's /ork:implement.
Instrucciones de origen · Vista previa de solo lectura
name
swarm-migrate
license
MIT
compatibility
Claude Code 2.1.220+. Uses isolated git worktrees (one per repo) and the Agent tool for parallel dispatch.
description
Cross-repo migration swarm — one coordinator + N parallel subagents (one per target repo) that apply the same transformation, open PRs, wait for CI, and report back to a shared JSON ledger. Coordinator handles topology, conflict auto-rebase, and stop-on-novel-failure. Use when bumping a shared dependency, rolling out a workflow change, or applying a codemod across the org. Do NOT use for single-repo work — that's /ork:implement.
{"keywords":["swarm","across repos","all repos","every repo","fan out","cross-repo","migration","rollout","codemod","bump everywhere","cascade"],"examples":["swarm-migrate bump @actions/checkout v4 across all 14 repos","swarm-migrate apply this codemod to every TypeScript repo","swarm-migrate roll out the @v1 reusable workflow to all platform repos"],"anti-triggers":["single repo","this repo","current branch"]}
paths
[".swarm-state.json","swarm-specs/**/*.yaml"]
/ork:swarm-migrate — Cross-Repo Migration Swarm
One command, N repos, one coordinator, one ledger.
When to use
Use when the same transformation needs to land in 3 or more repos with the same shape (workflow bump, dependency upgrade, codemod, lint-rule introduction, secret rotation, runbook header). Don't use for one-repo work — that's /ork:implement. Don't use for novel exploration — that's /ork:brainstorm.
This skill exists because the 275-session insights showed 25 sessions burned coordinating PR cascades manually (M164 deploy-migration, M17 yg-mcp-core extraction, @v1 reusable workflow rollout across 14 repos). The pattern was always: pick a repo, branch, apply, push, watch CI, repeat. This automates the repeat.
vs CC /workflows (2.1.154): CC's dynamic workflows orchestrate tens-to-hundreds of agents in the background and report via /workflows. swarm-migrate is different on purpose: it's a coordinator-led, foreground DAG with CI gates, conflict auto-rebase, and stop-on-novel-failure — you watch it and it stops on the first unexpected failure. Reach for CC /workflows when you want large-scale fire-and-forget background fan-out; reach for swarm-migrate when each step needs a CI gate and a human-visible ledger. CC 2.1.202 adds a Dynamic workflow size setting in /config (small / medium / large agent counts) that advises /workflows on how many agents to spawn — it's a hint, not an enforced cap, so check it before hand-capping fan-out.
Inputs
A YAML spec at swarm-specs/<name>.yaml:
name:bump-actions-checkout-v4description:"Pin @actions/checkout to v4 across all repos"# Topology — repos in dependency order. Coordinator only proceeds# to a downstream repo after every upstream parent has merged green.repos:-path:~/coding/yonatan-hq/platformupstream: []
-path:~/coding/yonatan-hq/ventures/jobscraper
[]
[, ]
[, ]
upstream:
platform
# waits for platform to merge first
# Transformation — applied identically per repo. The agent runs this
# inside the isolated worktree, then verifies with the next field.
Each worker is a Agent tool invocation (subagent type git-operations-engineer for plumbing or backend-system-architect for schema-flavored migrations). The coordinator (you, this skill) reads the ledger between waves and decides whether to release downstream waves or pause.
Push, do not poll (CC 2.1.224+)
Workers report state changes (CI green, CI red, novel failure, skipped) by MESSAGING
the coordinator via SendMessage instead of the coordinator re-reading the ledger
between waves:
Workers spawned as Agent-tool subagents use in-session SendMessage (available
since CC 2.1.77).
Workers running as separate sessions or claude -p processes use cross-session
messaging (CC 2.1.224, see chain-patterns Pattern 10). A -p worker must run with
crossSessionInbound: "accept" in --settings to receive replies.
CRITICAL: cross-session delivery is not guaranteed - inbound controls can hold or
refuse a message. .swarm-state.json REMAINS the authoritative durable record, and
every state change is still written there. Messages are the low-latency signal; the
ledger is the truth.
Phase 1 — Spec validation
Load <spec-file.yaml>. Verify:
Every repos[].path exists and is a git repo (use git -C <path> rev-parse checks).
The transform.command returns 0 in a dry-run mode (or transform.type: codemod resolves to a known codemod registered in swarm-specs/codemods/).
Every upstream reference points to a declared repo (no dangling deps).
pr.body_file exists and is non-empty.
If any check fails, abort and print the table of failures. Do NOT proceed.
Phase 2 — Topology sort
Build a DAG from upstream edges. Detect cycles → abort. Group nodes by topological wave (wave 0 = no deps, wave 1 = depends only on wave 0, …). Coordinator releases one wave at a time.
Write .swarm-state.json at the repo root running the skill:
Transform — run transform.command (or apply codemod). Capture stdout to .swarm-logs/<repo>-transform.log.
Verify — run each verify[].command, assert exit matches expect. On mismatch, mark repo skipped in ledger with reason, do not push.
Push + PR — push branch, open PR via gh pr create. Update ledger with PR URL.
Watch CI — poll gh pr checks <n> every 45s up to ci_gate.timeout_minutes. Update ci_state in ledger on every state transition.
Use the Agent tool with subagent_type: ork:git-operations-engineer for steps 1–5 to keep main context lean. The coordinator only reads the ledger.
Phase 4 — Wave gate
After every wave, check the ledger:
All green → release the next wave.
Any pending CI → keep polling.
Any red CI → consult ci_gate.on_failure:
pause → halt the swarm, write a summary to .swarm-state.json, surface the failing logs, ask the user.
skip → mark repo failed-ci, continue with siblings (but block downstream unless they explicitly don't depend on this repo).
abort → terminate the swarm, leave open PRs as-is, never merge.
Phase 5 — Auto-rebase on conflicts
If a downstream repo's worker hits a merge conflict on rebase (because an upstream merged), the worker:
Re-fetches the upstream's merge commit SHA.
Attempts git rebase origin/<base>. If clean → push, ledger update.
If conflicts → mark the conflict files in the ledger, do NOT auto-resolve, surface to the coordinator. Conflicts are the most common place auto-fixers ship broken code.
Phase 6 — Final report
When all waves complete (or the swarm pauses/aborts), emit a single markdown report under .swarm-logs/<spec-name>-report.md:
# Swarm report: bump-actions-checkout-v4
Completed: 12/14 repos · paused: 2 · duration: 47 min
| repo | status | PR | CI | duration |
|-----------------|---------|-------|--------|----------|
| platform | merged | #3456 | green | 8 min |
| jobscraper | merged | #281 | green | 6 min |
| ... |
| dormant-repo-1 | skipped | — | — | (no CI runner configured) |
| trading-ai | paused | #99 | red | (novel failure — see logs) |
## Novel failures (escalated)- trading-ai #99: pyproject lockfile mismatch — see .swarm-logs/trading-ai-ci.log
Hard rules
Never merge a PR. The swarm opens PRs; humans merge them. Auto-merge can be armed by the user with gh pr merge --auto post-swarm if they want.
Never force-push. If a worker can't fast-forward, it pauses.
Never roam outside the spec's declared repos[]. Even if a transformation seems like it'd help elsewhere.
Always quarantine credentials. Workers run with the user's gh auth; the coordinator never logs tokens, just the URLs.
Always respect existing branch protections. If gh pr create fails because of required reviewers or other rules, that's a feature, not a bug to work around.
Failure modes you'll actually hit
Mode
What it looks like
Mitigation
Stale lockfile
CI red on npm ci after dependency bump
Spec includes a post_transform.command: npm install step
Branch protection blocks PR creation
gh pr create exits non-zero
Coordinator marks repo blocked-by-protection, surfaces to user
Topology cycle
Phase 2 abort
Re-spec the upstream edges
Coordinator crash mid-flight
.swarm-state.json half-written
Skill is resumable: re-run with same spec, it reads the ledger and skips merged/green repos
Worker subagent hangs
No ledger update for >5 min
Coordinator times out the agent, marks repo worker-timeout, surfaces logs
Related Skills
Upstream — /ork:brainstorm to design the spec, /ork:visualize-plan to ASCII-preview the DAG before dispatch.
Downstream — /ork:verify per repo after merge, /status for org-wide sweep, /ci-debug if a worker hits a CI red.
Composes with — /ork:create-pr (each worker calls into it), /ork:github-operations (bulk-update labels/milestones post-swarm).
What this skill does NOT do
Does not invent the spec. You write the spec; the skill executes it.
Does not perform schema migrations across DBs (use a single-repo skill plus /ork:database-patterns).
Does not orchestrate production deploys — open PRs only; deploy is a separate gate (the platform's deploy-operator).
Does not bypass /ork:create-pr's playground-gate rule — each PR body must include a playground reference if the repo enforces it.
Example invocation
# Dry-run: build the DAG, verify spec, do NOT push or open PRs
/ork:swarm-migrate swarm-specs/bump-actions-checkout-v4.yaml --dry-run
# Live: dispatch up to 4 workers in parallel
/ork:swarm-migrate swarm-specs/bump-actions-checkout-v4.yaml --max-parallel=4
# Resume after pause: same command, the ledger remembers
/ork:swarm-migrate swarm-specs/bump-actions-checkout-v4.yaml
Why this exists (one paragraph)
You ran 25 sessions in a single month coordinating cross-repo PRs by hand. The 14-repo @v1 workflow rollout, the M17 yg-mcp-core extraction, the M164 deploy-migration. Every one of those sessions had the same shape: a coordinator (you) holding the DAG in your head, dispatching workers (you, sequentially) in different terminal tabs, hand-rolling a status table in your notes. This skill makes the coordinator a YAML file and the workers parallel subagents. The DAG, the ledger, the auto-rebase, the wave gating — all the bookkeeping you were doing manually — get codified once. You write the spec, you walk away, you come back to a report.
