How My Agent Team Works

01the problem

A single agent works through a job one step at a time. On a big task that's slow, and its conversation fills up with detail until it loses track of what matters. Putting two agents in the same folder doesn't help: they overwrite each other's changes.

02the system

medecide what to build, review the feature

lead agentplans, reviews the code, merges

workerown branch, own files

me: I decide what gets built, approve the plan, and review the finished feature. Every agent runs in its own terminal, so I can watch any of them and step in.
the lead: Reads the code, splits the work, writes each worker's brief, then reviews the code that comes back and merges it.
workers: Each has its own git worktree and branch and owns a set of files. They report back with their test results, and can message each other and the lead.

A rules file in each repo, AGENTS.md, tells every agent how to behave: how to claim a file, when to ask, and what it must never do without me, like pushing or deleting.

03why it works

Each part is borrowed from how a dev team already works.

a branch per developer

Each worker has its own worktree and branch, so nobody overwrites anyone else's work.

code ownership

Work is split by file. If two tasks need the same file, they run one after the other, so merges don't conflict.

tickets

Each worker gets a written brief with the goal, its files and the tests to run. It only needs that, not the lead's whole conversation.

code review

The lead reads every change without having written it, so it spots what the author missed.

one person merges

Only the lead merges, and it runs the full test suite on the combined result before anything reaches me.

04in practice

On Greyfall, my game, I asked for a redesigned map area. The lead started a researcher to study level design and a builder to work from its brief. Partway through I added a shop system, and the lead brought in a third worker for it instead of squeezing it into someone else's files. Two features in one session, with no merge conflicts.

05what I'm improving

It isn't finished. What I'm working on now:

Workers commit to their own branch, so the lead can merge it like a pull request.
A setup script for each new worktree, since a fresh one has no packages, assets or config.
A port per worker, and each worker shuts its servers down before reporting back.
Running the final tests only after every worker has stopped, because a busy machine makes tests fail at random.

I use it for two or more pieces of work that don't share files, or research that can run ahead of the build. For a small fix, one agent is faster.

how my agent team works