/swarm-migrate

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."
argument-hint: "<spec-file.yaml> [--dry-run] [--max-parallel=N]"
disable-model-invocation: false
model: sonnet
context: fork
user-invocable: true
name: swarm-migrate
background: false
allowed-tools: [AskUserQuestion, Bash, Read, Write, Edit, Grep, Glob, Agent, TaskCreate, TaskUpdate, TaskStop, ToolSearch, Monitor]

Auto-generated from skills/swarm-migrate/SKILL.md

Source: https://github.com/yonatangross/orchestkit

/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-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.

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.