Agent orchestrator

---
name: agent-orchestrator
description: Plan work for several coding agents (or sub-agents) so they never step on each other. Use before running more than one agent, sub-agent, or parallel task on the same repository. Splits the job into pieces that touch different files, gives each agent its own branch and file fence, sets the merge order, and merges one at a time to avoid merge conflicts.
---

# Agent orchestrator

When several agents change the same files at the same time, their branches
collide and you get merge conflicts. Untangling a conflict is much harder than
avoiding one. Your job as the orchestrator is to plan first, so each agent
works in its own lane and the pieces merge cleanly. A slower start is the
price of a clean finish.

You plan, assign and merge. You do not need to write the code yourself.

## Step 1: Understand the whole job

- Restate the goal in two or three sentences and confirm it with the user if
  anything is unclear.
- Read the parts of the codebase the job touches. List the files and folders
  that will likely change.

## Step 2: Split it into pieces

- Break the job into pieces that can each be built, tested and reviewed on
  their own.
- For every piece, write down the files it will create or change.
- Keep pieces small: one agent, one clear outcome.

## Step 3: Check for overlap

Make a simple table: piece, files, agent.

- If two pieces change the same file, do one of these:
  1. Merge them into one piece for one agent, or
  2. Run them one after the other instead of at the same time, or
  3. Do the shared part first (for example a shared type, config or
     interface) as its own piece, merge it, then start the others.
- Watch for hidden shared files: lockfiles (`package-lock.json`), route lists,
  shared config, database migrations, generated files, and central `index`
  files. Give each of these to exactly one piece.
- Do not start any agent until no two parallel pieces share a file.

## Step 4: Give each agent its own lane

For each agent, prepare:

- **Its own branch**, created from the latest main:
  `git switch -c agent/<piece-name> origin/main`.
- **Its own working folder** when agents run at the same time, so they do not
  share one checkout: `git worktree add ../<repo>-<piece> -b agent/<piece> origin/main`.
- **A brief** that includes:
  - The goal of this piece and how to know it is done.
  - The file fence: the exact files and folders it may change.
  - A rule: "If you need to change a file outside your fence, stop and report
    back instead of changing it."
  - How to test it.
  - "Commit in small steps. Do not push to main. Do not merge."

## Step 5: Set the merge order

- Decide the order before work starts. Foundations first (shared types,
  database changes, config), then features that depend on them, then polish.
- Write the order down and share it with the user.

## Step 6: Merge one at a time

For each piece, in order:

1. Check the agent stayed inside its fence: `git diff --name-only origin/main...agent/<piece>`.
   Any file outside the fence needs your review before merging.
2. Run the tests on that branch.
3. Merge it (or open a pull request and let the user merge, if that is how
   this project works).
4. Bring every remaining branch up to date with the new main
   (`git rebase origin/main` or `git merge origin/main` on each), and re-run
   their tests.
5. Only then move to the next piece.

## Step 7: If a conflict still appears

- Stop. Do not force a merge or pick a side at random.
- Find out why the lanes overlapped. Usually a fence was too loose or a shared
  file was missed.
- Re-plan: hand the conflicting part to one agent, or finish one branch before
  the other continues. Explain the fix to the user.

## Hard rules

- No two agents change the same file at the same time.
- Every agent gets its own branch; parallel agents also get their own folder.
- Nobody pushes to main directly. Merges happen in the agreed order.
- Never force-push, reset or delete another agent's branch or work.
- When in doubt, run fewer agents. Two clean lanes beat five tangled ones.

## Report to the user

At the start: the piece table (piece, files, agent, branch) and the merge order.
At the end: what was merged, in what order, test results, and anything left
open.

---

Free skill from CTO Breakdowns (lesson: Many agents, one app).
More from Henry: odd.community