From One AI Session to a Team: Coordinator and Subagents

The single-session era #

For most of its first three and a half days, Dekiro was built the way the earlier posts describe: one Claude Code session at a time, working through tasks in order. The human set direction and playtested, and the AI implemented, tested, screenshotted and committed. It worked well: well over a hundred commits, from an arc attack against training dummies to a 2.6 x 3 km map with music, multiplayer and fishing.

It had one obvious limit: everything was serial. While the session was composing music, it wasn't fixing the grass. While it was building item icons, the map waited. Some tasks, like rebuilding every monster model or designing a full UI theme, are long and mostly independent of everything else. Doing them one after another meant long stretches where the human had nothing new to look at.

The new setup #

On day four the human asked for a different way of working: the main session should spawn subagents freely and act as coordinator and quality control. The working notes from that day put it this way: review, test, screenshot and fix before work reaches the human, give agents self-contained briefs with file boundaries, and commit only after checking.

In practice there are two kinds of Claude sessions:

• The coordinator holds the conversation with the human and the overall picture. It writes briefs, launches subagents, reviews what comes back, runs the full test suite, looks at the screenshots, fixes or sends back what isn't right, and makes the commits.
• Subagents each get one job with clear boundaries: which files they may touch, which they must not, what "done" looks like, and how to verify it. They work in parallel and report back. They don't commit.

The human talks to one session, as before, and sees more finished work per hour.

By the numbers #

The coordinator's session log records every subagent it launched: 70 in three days.11 35 on day four, 24 on day five, 11 on day six, the later ones much bigger. Their one-line descriptions read like the changelog of the second half of this series: "Compose original game music", "Roll out organic quadrupeds", "Move tests to the test map", "Prototype 2D sprites in 3D world", "Fix D3D12 descriptor heap exhaustion", "Dungeon generator core + Crypt remake", "Story wave: First Shadow raid + finale", "Balance: combat simulation + tuning". The update of this very blog is number 70.

The commit history changed shape with it. Day four had 76 commits. Days five and six had 11 between them, each a reviewed batch of several agents' work; the largest touches 941 files.

The first job: music #

The first subagent job was the music. It suited delegation well:

• Self-contained: the composing tools live in tools/audio/ and write files to audio/music/. Nothing else in the game had to change except a "music" key per map.
• Verifiable without the game: each render prints its length, loudness and true peak, so the coordinator can check the numbers before anyone listens.
• Clear taste gate: whether it sounds right is the human's call. The Vale theme was the reference.

The result was "Music for every map": nine new tracks, a shared synth library and one data module per map, in one commit. Since then every dungeon got a track the same way, 30 in total.

Briefs are the new CLAUDE.md #

A subagent starts cold, just like every session did before. It doesn't know the conversation, the decisions of the last hour, or why the open world was switched off. CLAUDE.md gives it the project's rules, and the brief gives it the task. A good brief turned out to need:

1. The goal in one paragraph, including what the human has already decided ("NO shovel/digging: the user disliked it").
2. File boundaries: "you own these paths; read anything; don't touch these."
3. Facts it can't discover: the human's preferences, the reference to match, numbers agreed in conversation.
4. How to verify: which tests to run, which screenshots to take, and what to report.
5. What not to do: don't commit, don't kill Godot processes you didn't start (the human's editor often runs alongside), wrap test runs in timeout.

When four agents share one repository #

The plan said file boundaries would keep parallel agents apart. They mostly did. The interesting failures were all at the edges, in the files every feature has to touch: the one big test file, shared shader includes, the boss AI, the map generators. A selection from the agents' own reports:

• The test file. Every feature adds tests to tests/run_tests.gd, so every agent edits it. Two dungeon agents each added a helper function named _room_mid. GDScript doesn't allow two functions with the same name, so the whole test file stopped parsing for every agent until one renamed theirs (_caldera_mid).
• Shared shader includes. An agent named a new uniform in the sprite shader shade. A shared cloud shadow include already used shade as a local variable. The shader stopped compiling, and the player and every NPC turned into a white rectangle in the human's running game. Headless tests don't compile shaders, so every suite still passed. Another agent's first screenshots of its ice dungeon caught it; the human caught it first.
• Other people's half-finished work. Agents regularly saw failures that weren't theirs: a parse error in main.gd from a change in progress, a test failing in another agent's area, a physics warning from a map being regenerated. Without a rule, an eager agent "fixes" the other agent's file and both lose.
• The class cache. When one agent adds a new class_name script, the other agents' test runs fail to compile until Godot's class cache is refreshed. "Can't find class Waystone" is not a bug to fix; it's an --import to run.
• Rule slips. Several agents edited shared files with short Python rewrite scripts instead of the exact-match Edit tool, which the briefs asked for. Their own reports flagged it. Nothing was lost, because the scripts refused to write when the target text had changed, but it's exactly how a silent overwrite would happen.
• The machine. Godot test runs and Blender builds are heavy, and they all run on the human's PC. One map agent wrote in its report that it couldn't measure the frame rate cleanly "with several agents running".

The rules that came out of it #

Each of those turned into a line in the briefs (and some into CLAUDE.md). The current shared brief for a batch of parallel agents includes, in substance:

1. Who owns what. Each agent owns its files outright. Shared files (data tables like items.json, the test file, the boss AI) are "edit carefully with Edit (never rewrite whole files)", re-reading first if the file changed. In the test file you ADD your own test_* methods and touch nobody else's.
2. Unique names for anything you add to a shared space. Temporary screenshot scripts get names like tests/_tmp_<job>_*.gd and are deleted afterwards. The _room_mid collision showed the same goes for helper functions.
3. Don't fix what isn't yours. "If something fails in files you didn't touch, it may be another agent's work in progress: say so, don't fix it." The coordinator sorts it out after merging.
4. Refresh the class cache (--import) before believing a "missing class" error.
5. Shader edits need a windowed check. Headless runs never compile shaders; after any shader change, take a windowed screenshot and grep its log for errors.
6. At most about four agents at once on the human's PC, and anything that measures performance runs when the others are done.
7. Report what you touched outside your lane, including slips. Agent reports end with a list of the shared files they edited, and several of the most useful lines in them were confessions.
8. Nobody but the coordinator commits. After merging a batch, the coordinator runs the full suite, the smoke runs and the network bots, and looks at the screenshots, before one commit with a message that lists everything in it.

Work also got split along the lines that collide least. Maps went out two per agent, each writing its own generator file, with portal links fixed afterwards by one script. Dungeons went out three or four per agent, each with its own spec, kit theme, monsters and music, and shared building blocks added with tests.

Approval gates #

The second rule of the setup: the human approves designs before builds. A subagent can produce something in an hour that would take a day to undo. So anything with taste in it goes through a design step first. Three gates from day four, and how they ended:

• UI: the HUD and windows were drafted as a design in Claude Design and shown to the human; the approved lacquer-and-gold pixel style was then built into the game's UI code and textures. It landed.
• Monsters: the organic rebuild that replaces the "Pinocchio doll" primitives22 See the Blender post. went to the human as a single wolf first, then rolled out to every four-legged monster and critter. It landed.
• Player characters: real 3D player models to replace the capsule. This gate did its job by saying no six times. The 3D drafts never shipped; the human chose to render them into pixel sprites instead, which became the HD-2D post.

Quality control: before and after #

The coordinator's main job is to catch problems before the human sees them. The checks are the same ones a single session used, applied to someone else's work:

• The full test suite (now about 13,800 checks) plus the grep for engine errors, after merging each agent's work. A subagent may have run only the tests near its own files.
• Smoke runs of the menu and the game, and the network bots when anything networked changed.
• Before and after screenshots for every visual change, looked at side by side. A shader change that "should only affect monsters" deserves a shot of a building too, and after the white-wall incident, a windowed run.
• A read of the diff: scope (did it stay inside its files?), the CLAUDE.md conventions (static typing, no := on Variant expressions, command_* methods only, content in data), and new tests for new behaviour.

It doesn't catch everything. The white wall reached the human's screen before the coordinator saw it. Balance numbers from the agents are "a first guess, not playtested", and every dungeon report says so. What the setup guarantees is that problems are found by one session looking at everything, not by the human finding them one by one.

What changes for the human #

Less waiting, mostly. Instead of one stream of commits, there are several lines of work moving at once, and the human's time goes where it matters most: approving designs, judging feel, playtesting. They don't supervise each agent. The coordinator is the single point of contact and the single gate to the repository.

It also changes how decisions are kept. Since a brief has to be self-contained, a preference the human states in conversation gets written down sooner and more precisely: first in a brief, then in a design, then in an approval, instead of living only in a chat.

A meta note #

This blog series is itself a subagent job, twice. A subagent wrote the first drafts from the git history; another (number 70) updated them three days later, counted everything again in the repository rather than trusting the old numbers, and wrote the newer posts. The coordinator reviews them, and the human decides what gets published. Most of what you've read comes from commit messages and agent reports, which is a good argument for writing both well.

What we'd tell another team #

• Parallelize the long, separable jobs. Music, a UI theme, a model rebuild, two maps, three dungeons: each has its own files and its own way to verify. Keep the tightly coupled work in one place.
• Expect collisions at the shared files, not the owned ones. The test file, shared shader includes and central AI code are where parallel agents meet. Give those files explicit edit rules.
• Write briefs like contracts. Goal, boundaries, facts, verification, don'ts. A cold-start agent only knows what you give it.
• Ask agents to report their slips. An honest "I edited a shared file the wrong way" is cheaper than finding it in the history.
• Gate on taste, not on code. Let the human approve designs; let the tests approve code.
• One committer. A single reviewer between the agents and the repository keeps the history clean and the rules enforced.

What's next #

The posts after this one cover what the parallel phase built: the HD-2D sprite pipeline, the dungeon generator, the story, the 40-hour balance model, the living towns and the Fullmoon weapons. What's left after that is the part no agent can do: the human's playtest, and the notes on how all of it feels.