/swarm-migrate

name: swarm-migrate
license: MIT
compatibility: "Claude Code 2.1.277+. Uses isolated git worktrees (one per repo) and the Agent tool for parallel dispatch."
description: "Cross-repo migration swarm: one coordinator and a subagent per repo apply the same change, open PRs, wait for CI, and log to a shared ledger. Use for org-wide dependency bumps or codemods. Not for one repo (use implement)."
argument-hint: "<spec-file.yaml> [--dry-run] [--max-parallel=N]"
context: fork
# user-typed commands stay interactive; CC >= 2.1.218 backgrounds forks by default (#3093)
background: false
disable-model-invocation: false
user-invocable: true
allowed-tools: "AskUserQuestion Bash Read Write Edit Grep Glob Agent TaskCreate TaskUpdate TaskStop ToolSearch Monitor"
skills: [github-operations, verify, memory, explore]
model: sonnet
metadata:
  category: workflow-automation
  version: "0.1.0"
  author: "OrchestKit"
  complexity: "high"
  tags: "migration, cross-repo, swarm, parallel-agents, worktree, ledger"
triggers:
  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"

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 `implement`. Don't use for novel exploration — that's `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-v4
description: "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/platform
    upstream: []
  - 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.
transform:
  type: codemod              # codemod | regex | command
  command: |
    grep -rl 'actions/checkout@v3' .github/workflows | \
      xargs sed -i '' 's|actions/checkout@v3|actions/checkout@v4|g'

# Verification — must pass before PR opens. Coordinator skips the repo
# if it fails locally (records skip-reason in ledger).
verify:
  - command: "git diff --quiet"
    expect: nonzero            # must have changes
  - command: "grep -r 'actions/checkout@v3' .github/workflows"
    expect: nonzero            # zero matches = clean

# PR shape — title, body, base branch
pr:
  branch_prefix: chore/bump-checkout-v4
  title: "chore(ci): pin @actions/checkout to v4"
  body_file: swarm-specs/bump-actions-checkout-v4.pr.md
  base: main
  labels: [chore, ci]

# CI gate — coordinator waits for required checks to pass before
# moving downstream. Set to false for dry-run, or in repos without CI.
ci_gate:
  required_checks: ["build", "test"]
  timeout_minutes: 20
  on_failure: pause            # pause | skip | abort

# Limits
max_parallel: 4
abort_on_novel_failure: true

How it works

┌────────────────────────────────┐
│ COORDINATOR (you)              │
│ reads spec → builds DAG →       │
│ writes .swarm-state.json       │
└─────────────────┬──────────────┘
     ┌────────────┼────────────┐
┌──────────┐ ┌──────────┐ ┌──────────┐
│ WORKER A │ │ WORKER B │ │ WORKER C │
│ (repo 1) │ │ (repo 2) │ │ (repo 3) │
└────┬─────┘ └────┬─────┘ └────┬─────┘
     └─────────── isolated worktrees ─────┘
                  │ each: clone branch, transform,
                  │ verify, push, open PR, wait for CI, report
                  ▼
┌────────────────────────────────┐
│ .swarm-state.json              │
│ rolling ledger of {repo,       │
│ status, pr_url, ci_state,      │
│ last_action_at}                │
└────────────────────────────────┘

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:

> **Cross-session replies lan