| name | fleet-migration |
| description | Apply one change across many repos or packages as N independent agent runs that each end in a verified PR. Use when the same migration (dependency bump, API rename, lint fix, codemod) must land across a fleet, when you'd otherwise hand-apply patches one by one, or when designing a background coding-agent that fans a task out at scale. Use after a single-repo recipe is proven. References migration-skill for the per-repo change itself. |
| hints | - Prove the recipe on ONE repo first (it must end green); a fleet is just N parallel runs of a proven recipe.
- Each run is isolated (its own worktree/sandbox), bounded (turns + retries), and ends at a PR — never a hand-apply patch.
- Use a global concurrency cap + durable queue, not per-session slots; the run must survive a host restart.
- A failed verify must block that repo's PR, not the whole fleet — isolate failures per repo.
- Make enqueue idempotent so re-triggering a fleet doesn't double-open PRs.
|
Fleet Migration (one change → many PRs)
Overview
When the same change must land across many repos or packages, the slow path is doing it by hand or producing a pile of patches to apply. The scalable path is a fleet migration: a proven single-repo recipe, fanned out as N isolated, bounded agent runs, each ending in its own verified PR. This skill is the orchestration around a per-repo change (the change itself is migration-skill).
When to Use
- One migration (dep bump, API rename, codemod, config/lint fix) must apply across a fleet of repos/packages
- You're about to hand-apply the same patch repo by repo
- You're building a background coding-agent that needs to operate at scale
- A platform change requires coordinated PRs everywhere it's consumed
When NOT to use: a one-off change in a single repo (just do it); or a change whose per-repo shape varies so much there's no shared recipe (then it's N bespoke tasks, not a fleet).
Workflow
- Prove the recipe on one repo. Run the change end-to-end in a single worktree; it must finish green (build + test). Capture it as a reusable recipe/workflow (the
build-style verify→fix→gate loop).
- Enumerate the fleet and the per-repo inputs. Make the enqueue idempotent (keyed by task+repo) so re-runs don't double-open PRs.
- Fan out under a global cap. Run N isolated jobs — each its own worktree + sandbox, bounded turns/retries, safe-default sandbox for unattended execution — limited by a shared concurrency cap (not per-session slots), backed by a durable queue that survives restarts.
- End each run at a PR. On green + gate, push a branch and open a PR per repo (the PR-emit step). On red, that repo stops at its failure — it does not block the others.
- Observe + reconcile. Track queue depth, per-job state, and PR links in a fleet console; re-queue only the failed repos.
Patterns
- Recipe-first: a fleet is N runs of a proven recipe — never debug the recipe at fleet scale.
- Isolate-per-repo: failures, secrets, and worktrees are per job; one bad repo can't poison the fleet.
- PR-per-task: the run terminates at a PR, not a local patch — that's the whole point of fleet scale.
- Idempotent enqueue: triggering twice is a no-op, so retries and external triggers are safe.
- Global cap + durable queue: concurrency is accounted org-wide and the run is restart-safe.
Common Rationalizations
| Excuse | Reality |
|---|
| "I'll just loop the change over the repos." | A naive loop has no isolation, no concurrency cap, no per-repo failure handling, and ends in patches, not PRs. |
| "Per-session slots are fine." | They cap one parent session, not the fleet — you'll over-run concurrency across jobs. |
| "Skip the single-repo proof, fan out directly." | A broken recipe fails N times; you debug at scale instead of once. Prove on one first. |
| "End at patches, the user can apply them." | N hand-applies defeats the automation. The verified PR is the deliverable. |
Red Flags
- The recipe wasn't proven green on one repo before fan-out.
- A single repo's failed verify halted or polluted the whole fleet.
- Concurrency is per-session; jobs swamp the machine.
- The fleet emits patches, not PRs; or re-triggering double-opens PRs (enqueue not idempotent).
- The queue is in-memory and a restart loses the run.
Verification
- Single-repo recipe finishes green before any fan-out.
- A fleet run over N sample repos opens N PRs, each behind its own green verify gate.
- A deliberately-failing repo produces no PR and does not stop the others.
- Re-triggering the same fleet opens zero new PRs (idempotent).
- The run survives a host restart (durable queue) and respects the global concurrency cap.
