Brackenmere / dev log

Posts Building it with AI agents

Handoffs, one worktree per feature and standing rules

The first week of Brackenmere ran as several AI agents at once, each in its own worktree, each starting from one short page that said what was true. A week later the work moved to the cloud, my personal rules moved into the repo with it, and one session became five threads in a day.

A01 6 min read

How shall I tell it?

I am making a game for my kids, and I am not writing most of the code. The other series here is about what got built. This one is about how: the agents, the habits that kept them pointed the same way, and the rules I wrote down because I kept saying the same things.

Who is on the team

Codex, OpenAI's coding agent, ran the first week: the design questions with my son, the greybox, the first maze. Claude Code, Anthropic's agent, took over most of the building from the evening of 22 September, first on my Mac and then in the cloud. Solo, the terminal app I run them in, keeps scratchpads any agent can read.

How I work with them has barely changed: I dictate a list and walk away. My first Claude session opened like this: "I'm then going to be away from keyboard until the morning. So just work through them, do your tests, work hard, maybe spin up a separate review agent when you need it..." That only works if a fresh agent can start without me re-explaining everything.

"Read this first"

On 20 September I wanted to split the next jobs across several agents: "If I wanted to hand all this off to a new agent, could I do this without a prompt now, or is it worth creating a Solo MCP scratchpad with a 'read this first' kind of thing? Don't want to fill up the context but something to give it a headstart, save tokens in exploring etc."

The agent wrote one page: where we are, my decisions, the ones it made without me, gotchas, the next action. AGENTS.md became a pointer to it, with a line I still like: "Completed plans are history, not an instruction to repeat their work."

Within ten minutes I had started three sessions, each with the same opener: "new worktree, read this first (solo mcp)".

Under the hood The first handoff was 53 lines, and six fresh sessions started from it on 20 September alone. Every agent appended its round and nobody removed anything: in six days it reached 491 lines.

One worktree per feature

A git worktree is a second checkout of the repo on its own branch. Give every agent one and three can edit at once. The next morning, unhappy with how the maze's darkness swept around: "Let's spin up a worktree here just to try something else. So keep what we have on the main branch, but let's use a new worktree."

When a round finished I said the same thing every time: "Merge everything into main or master, commit and push there. Then remove any orphaned worktrees, database and processes that may be stale after this merge." By 22 September Codex opened sessions by asking "Worktree, new branch, or stay on the current branch (main)?" I still answer it every day.

Into the cloud

On 24 September I wanted the work to keep going without my laptop: "I've got Claude AI on a browser, I've got you here in the CLI, and I've also got a Claude desktop agent. How do these three all work together?... So if I close my laptop, everything keeps on running."

The real move came on 28 September: "I want to move all this work to Claude cloud... I'd like to do this cleanly as well, and not lose any work." A cloud container knows only what the repo tells it, so the agent asked me four questions, among them: "Your personal rules (delegation caps, testing, git, plans) don't reach cloud sessions. What should I do?" I chose to copy the game-relevant ones in.

That became .claude/rules/nick.md, imported by CLAUDE.md. It opens with "Nick dictates": fix transcription slips silently (word tree means worktree), terse replies are decisions, final design taste stays mine.

Within the hour a cloud session started from it: "Read AGENTS.md, .claude/rules/nick.md and docs/handoff.md, then tell me the current state and the open items in the For Nick section. No code changes yet."

Five threads in a day

Once the cloud worked, I stopped thinking in sessions. With a job queued in that first thread: "I want everything to work in the cloud, can you start #1 here in the cloud so I can close my laptop?" Then, a few minutes later: "while this is working, can we start a new worktree, in the cloud, that works on a 'personal home' game mechanic that I want to spec out. I can let that agent know the details." Then the same for a list of small fixes, then a local worktree for my Meshy pictures, then weather. Each thread was its own session on its own branch.

By early afternoon I was losing track: "Is it worth merging this to main now? Because I'm getting confused with the amount of work I'm doing on different branches. And basically when a work tree or branch or something is finished, I like to merge that into main so I'm keeping main up to date." The agent pointed out that my own new rules said pushing to main needed my word. I gave it: "merge it".

The cloud also kept stopping to ask: "I don't want to keep on failing if there's a permission check. I can approve something if needed." A session set out to add an allowlist. The settings edit was blocked (Claude cannot change its own permissions), but its commit still told the handoff it was done, and the next commit had to revert that line. A handoff is only useful if every line is true.

An orchestrator, and a slow box

The next day I asked the weather thread to run its remaining jobs in parallel: "Can we spin up separate agents to work on these separately, and you kind of are an orchestrator keeping an eye on those agents, and then they kind of report back to you, and you deal with merging them all into your branch."

It was slow. "We seem to be restarting or resuming agents quite a lot here. Is it something timing out or is something bumming out on the box or something?... we haven't really progressed very far in the last like hour and a half." The agent checked the box: three container restarts, my weekly usage limit, and four agents queueing for one slot for browser tests on a four-core machine.

Meanwhile, on my Mac, I named the problem for the agents: "I often run new work in Claude Cloud, so the VM or box that sits on is a lot less powerful than this machine." That afternoon heavy jobs started queuing for a machine-wide slot: one at a time on a four-core container, two on the Mac.

The cloud had one more layer: a project, whose coordinator chat starts threads for you. I set its ground rule first: "Okay, so main is my main branch. I want to branch from and start everything from." Then the obvious question: "What's the point of this project?" Its answer: shared instructions, and a coordinator that tells me when a thread finishes or gets stuck. On 30 September I used it properly: six content branches in an afternoon, with one more agent compiling them into a single, consistent whole.

What I took from it

  • One page that says what is true now, pruned, or it stops being read.
  • Rules live where the agent reads them. My setup did not travel until it was in the repo.
  • Parallel is cheap to start and dear to merge. Threads cost a sentence; keeping main whole cost my attention.

All those threads ran tests, and in the cloud the tests had been the first thing to break.

I'm making a game for my kids, but I'm not writing most of the code. A team of AI helpers is. I tell them what I want, often as a long spoken list, then walk away while they get on with it. This is about the habits that made that work in the first couple of weeks.

Every new helper starts from nothing

Each new AI helper knows nothing about the game, and I didn't want to explain everything every time. So on 20 September we wrote a single "read this first" page: where we are, what I've decided, things to watch out for, and what to do next. Within ten minutes I had three helpers going, each told simply to read that page.

It worked so well that everyone added to it and nobody took anything out. In six days it was nearly ten times longer. A page like that only helps if it stays short and true.

Everyone gets their own copy

If three builders work on the same drawing at once, they get in each other's way. So each helper gets its own copy of the game. When its job is finished and checked, the changes go back into the main copy and the spare is cleared away. Before long the helpers started each day by asking whether I wanted a fresh copy or to stay on the main one. I still answer that every day.

Moving to the cloud

I wanted the work to carry on when I shut my laptop, so on 28 September we moved it onto computers online. The catch: a helper there only knows what's written in the game's own files, and my house rules lived on my laptop. So we wrote them into the game's files. The first one is "Nick dictates": I talk rather than type, so fix obvious mishearings, treat a short "yep" as a decision, and the final say on how things look is mine.

Too many at once

Once that worked, I had five helpers going in a day on different jobs, and by the afternoon I was losing track. So I started folding each finished job back in straight away. When I tried one helper as a foreman over the others, it crawled: the online computer was much weaker than my Mac, and four helpers were queuing to test the game. Now big jobs wait their turn.

What I learned

  • Keep one short page that says what's true now, and prune it.
  • Write the rules down where the helpers will see them.
  • Starting lots of jobs is easy. Putting them back together takes my attention.
Building it with AI agents

A08 5 min read

Three AI designers, one brief

When the game felt like an errand chain, I asked three AI designers the same neutral question and kept every other opinion, mine included, away from them until they had answered. How that ran, and what a month of building this way taught me.

Building it with AI agents

A07 6 min read

The team takes shape: root, owners and one reviewer

My kids' playtest notes became four pieces of work, each with its own agent, and one agent above them merging the results. Over four days that settled into a team: a root that orchestrates, owners that build, one reviewer, and a single thing that stays mine.

Building it with AI agents

A05 5 min read

The agents measure themselves

Three times in a fortnight I asked the agents to stop building and measure how they worked: a retrospective from the commit log, a pass through three weeks of their own transcripts, and an overnight round that timed every wait. Each time the numbers corrected something I was sure of.