Migration sweep

Split a large upgrade — a framework major version, a language bump, a deprecated API — by module: one worktree and one agent per module, then a reviewer that checks every diff before anything merges.

Split by module, not by step

Pick boundaries that can change independently, such as packages, services or top-level folders. One agent upgrading web/ while another upgrades api/ works; one agent "updating imports" while another "fixing types" in the same code doesn't.

Cut one worktree per module

beswarm worktree add --name upgrade-web --workspace app
beswarm worktree add --name upgrade-api --workspace app
beswarm worktree add --name upgrade-worker --workspace app

Find each worktree's terminal id with beswarm terminal list.

Start one agent per worktree

Give every agent the same target version and the same definition of done:

beswarm agent start --name web --agent claude <terminal-id> --group migrate \
  --prompt "Upgrade web/ to React 19. Only touch web/. Follow the official migration guide. Done means: npm run build, npm test and npm run lint all pass. Run them before you finish and list anything you couldn't migrate in ../../reports/migrate/web.md."
beswarm agent start --name api --agent codex <terminal-id> --group migrate \
  --prompt "Upgrade api/ to the same versions. Only touch api/. Done means the api test suite passes. List anything you couldn't migrate in ../../reports/migrate/api.md."

Repeat for each module.

Agents started in a worktree's terminal work inside .worktrees/<name>/, so prompts point them at ../../reports/ — the repo root's reports/, where the Artifacts panel looks.

Track progress

beswarm worktree list --workspace app
beswarm agent list
beswarm agent wait web --until done,blocked --timeout 3600

Review before merging

beswarm agent start --name reviewer --agent claude --group migrate \
  --prompt "Review the diffs in .worktrees/upgrade-*. Check each against the migration guide, flag behavior changes and anything left half-migrated. Write findings to reports/migrate/review.md." \
  --wait --timeout 1800

Read reports/migrate/ in the Artifacts panel, merge the modules you're happy with, then clean up:

beswarm agent close --group migrate
beswarm worktree remove --name upgrade-web --workspace app

note

Merge one module at a time and rerun the full test suite after each. Modules that pass alone can still break together.