Multi-agent orchestration for a refactor

Multi-agent orchestration for a refactor means one coordinating agent splits the change into pieces, hands each piece to a separate agent with its own checkout, and reviews what comes back before anything merges. It works when the pieces touch different files, such as one directory or package each. Shared files go first and anything that depends on them waits, so orchestration shortens a refactor without making every part parallel.
What the orchestrator does
The orchestrator coordinates the agents that edit code. On a refactor it has five jobs:
- Map the shared files. Find what several pieces depend on, such as a bootstrap module, a middleware or a types file. Those files set the order.
- Write a brief for each piece. A worker starts from its brief, not from the orchestrator's conversation. The brief names the files it may edit, the pattern to follow and the command that proves it's done.
- Isolate the writers. Agents that only read can share one checkout. Each agent that edits code gets its own, so no half-finished change lands in someone else's commit.
- Choose parallel or stacked. Pieces that touch different files run at the same time. A piece that needs another piece's change starts from that piece's branch.
- Review what comes back. Read each diff, run the checks, and send specific feedback before a pull request reaches a person.
A worked example: Express to Fastify
The goal. Move a Node API from Express to Fastify without changing its behavior. The service has four route directories: routes/health, routes/auth, routes/billing and routes/webhooks. src/server.ts builds the app, and auth and billing both import src/middleware/session.ts. Someone has already ported routes/health by hand, and an integration suite covers every endpoint.
Step 1: audit. Three read-only agents share one checkout. One lists the Express APIs each directory uses, one lists shared imports, and one confirms the integration suite reaches every route. They find that every directory registers its routes through src/server.ts, and that auth and billing import the session middleware.
Step 2: port the shared core. One agent ports src/server.ts and the session middleware, keeps an adapter so routes still on Express keep working, runs the full suite and opens a pull request. Nothing else starts until that suite passes, because every other piece builds on it.
Step 3: migrate the routes in parallel. Three agents start from step 2's branch, each on its own machine, one per directory: auth, billing and webhooks. Every brief points at routes/health as the pattern, forbids edits outside the agent's directory, and requires that directory's integration tests to pass before the agent reports. Each opens a pull request on top of step 2's.
Step 4: review and fix. The orchestrator reads each diff before it goes to people. The webhooks agent reports failing signature checks: Fastify parses the request body before the handler sees the raw bytes. The fix is an option in src/server.ts, which isn't the webhooks agent's file, so the orchestrator makes it on step 2's branch and the webhooks agent rebases onto it.
Step 5: merge in order. People merge step 2, then the three route pull requests in any order, then one last small pull request that removes the Express adapter.
Three things let this run in parallel: a finished example to copy, directories that don't import each other, and a test suite that tells each agent when it's done. Two shared files kept it from being fully parallel. They had to land first, and they took the one fix that crossed pieces.
Checks before you split a refactor
- Each piece lists the files it may edit, and no two lists overlap.
- Files that several pieces need sit in an earlier piece that lands first.
- Each piece has a command that proves it works, and the command runs in the agent's own checkout.
- There's a finished example of the change for the agents to copy.
- The merge order is written down before the first pull request opens.
A piece that fails one of these stays with one agent, or stacks after the piece it depends on.
Where Capy fits
Capy is a platform that orchestrates agent swarms, and a refactor like this one runs inside a single thread:
- The thread's agent splits the work into subagents. Each starts as a draft holding its full prompt, so the whole plan can be laid out before anything launches.
- Read-only subagents share the parent's machine. Writing subagents boot a fresh machine with a clean checkout, so their edits can't mix.
- Subagents run in parallel or stacked. A stacked subagent starts from the previous one's pull request branch.
- Each subagent sends the parent a final summary, and the parent reviews its diff before opening the pull request or sends it back with feedback.
- The thread that owns each pull request fixes failing CI and resolves conflicts with the base. With automatic review on, the review agent checks every pull request at its exact head.
- Each subagent can run its own model, such as a cheaper one for the audits.
For a migration that outgrows one thread, such as one that runs across services for weeks, a Captain runs each part as its own thread. What is an agent swarm for engineering? covers that setup.
And where it doesn't fit:
- Separate machines keep agents from overwriting each other, but pieces that edit the same lines still conflict when they merge. Stack them instead.
- Subagents start from their prompt alone. A brief that leaves out a constraint gets a change that ignores it.
- Agents install what they need and can write missing tests, but a refactor with no test suite has nothing to prove each piece against until someone writes one.
- Each fresh machine uses machine time in Capy credits.
Follow-up questions
How do I stop two agents from editing the same file?
Give each piece a list of files it may edit, keep the lists apart, and move shared files into an earlier piece. In Capy, writing subagents also get their own machines, so edits can't mix before they reach git.
What happens when one piece fails its tests?
It stays with the agent that owns it. The orchestrator sends specific feedback, the agent fixes it, and the other pieces keep going. When the fix needs a shared file, it goes into the shared piece, as the webhooks fix did.
How big should each piece be?
Small enough for one pull request a person can review in a sitting. A directory or a package is a common size. A piece whose brief is longer than its diff is too small to be worth an agent.
When should I use a Captain instead of subagents?
Use subagents for one change that a single thread can see through, like this refactor. Use a Captain for work that runs for days across many pull requests, where each part is a thread with its own history.




