Making the repo agent-ready, then guarding its rules with tests

The first week's handoff habit had a cost. Every agent appended its round and nobody removed anything, so a fresh session started by reading a long diary, then took the rules on trust. Twice in four days the work stopped being about the game and became about the repo.

A start page, not a diary

On 26 September, straight after a big merge of new worlds, village art and the kit, I asked the cloud session for the next layer of the game and tacked a question on the end: "Also is the code base ready for future agentic development in an expedited way". The agent's answer began "It's partly ready", and it put that work first, "because it speeds up everything after". The first weak spot it named: "The handoff doc is now enormous. Every new agent is told to read it, which burns context and time."

The repo work took a quarter of an hour. The handoff was archived word for word and replaced with a short page of current facts. One command, npm run check, ran the build and the fast tests and ended with a single exit line an agent could wait on, and scripts printed their usage with --help.

The biggest change was skills. A skill is a short instruction file an agent loads when its description matches the job: add a world, add a kit piece, run the right tests, run an art review. The commit promised "Each skill uses real paths and runnable commands." The local know-how now sat next to the job, so I stopped repeating it in every brief.

Under the hood AGENTS.md went from a seven-line pointer at the handoff to a 119-line start page: golden rules, commands, a folder map and which skill to use. The handoff went the other way, from 491 lines to 63.

The next afternoon I opened a fresh session on my Mac with nothing more than: "Let's work on the maze game repo that you have connected to. Read your agents.md and read the docs/handoff.md... Let me know when you're ready to go." It came back confident and wrong: there was no docs/handoff.md, so it had read the old diary. I pasted its reply into the cloud chat ("I started a new chat and it said:"), and the cloud agent saw why. My Mac had not fetched from GitHub since 25 September, so "in sync with origin" meant in sync with an old record. A start page only helps an agent with the latest copy.

In the cloud the opener stuck. New threads started with some version of "Read the readme and make sure you're up to speed with where we're at here. Make sure you're also on the latest main branch." The next day I made it a project rule: "There's a readme in there that I want all new agents to read before we begin as well."

"What do you read?"

Three days later I wanted to know what that start cost. "If I start a new agent in a new branch such as this, what do you read? How much do you read? How much do you know? Things like, are there potential we have skills for doing certain things? Should we create some more skills?" I had a gap in mind: "What about a skill for generating a new 3D asset... I don't think that's in a skill yet."

Test speed has its own post. The skills got a quick audit that evening: "What skills do we have that are specific to the game here?" Some overlapped: "Not sure we need a Meshy import batch now, we can remove that. Also is add-kit-piece and new-3d-asset similar?" The import skill was folded into new-3d-asset, one skill for any model.

"Actually do them, not just propose"

Late that evening I dictated something bigger: "After this has finished, do another pass on all the code ensuring: performance, properly built so that we can build using blocks without opinions baked in to the current layout etc, look and feel consistency, audit drift, ease of use (and performant) for agentic development, without wasted context..." Then a way to keep it: "build 2, 3, 4 or 5 skills that we can run at the end of any worktree or branch."

Two more messages set the tone of the night: "do all this on main. Nothing is currently using the system so we don't need to worry about porting over anything." And: "and also proposed fixes, then actually do them, not just propose. Let's go. See you in the am."

Five read-only audits came first: performance, building blocks, drift, look and feel, and agent ergonomics. It opened kindly ("The documentation is unusually good") and then made the real point: "Most golden rules are enforced only by prose." AGENTS.md promised every script answered --help. Nineteen did not, and on the texture optimiser --help started a pass that rewrote files.

Under the hood The audit measured a cold start: about 43,000 tokens in the repo against 35,000 in an empty folder, so the project added roughly 8,500 before any work began. The town's architecture page alone was about 19,000.

Rules that fail

The fixes ran overnight as parallel streams on disjoint files. The heart was one table-driven test, code-rules.spec.ts. Each row names a golden rule, the folders it scans, what it forbids and the helper to use instead: shared code never imports a world, textures load only through their loader, browser storage only in the save, no real-time waits in tests.

The trick was the allow-list: rather than rewrite everything, each rule listed today's offenders with a reason and failed only on new ones. An entry that no longer matched also failed, so the list could only shrink.

Then came the skills I had asked for: npm run health and four end-of-branch skills (health check, architecture review, look review, doc sync) that every branch runs before it merges.

Under the hood The runtime file every feature touched went from 1,127 lines to 498. Refactors were held to the pictures: of 42 High shots retaken after the room and bestiary changes, 40 were identical to the pixel, and the other two varied as much between two runs of the same code.

The morning after

"Where are we up to?" Then: "I got asked about a rm command in the castle, what was that for (the blocking call). I said no but wanted to know more." The performance stream had sat for hours overnight waiting on a prompt to delete its own scratch files. I read the summary and started cutting: "No need for that page. Remove those 629Mb of old screenshots." Later: "let's remove those 629Mb from git history as well. What's the proposed permission rules?" Then: "apply them". Unattended agents could now run tests, builds and commits without asking, while git add -A and commit -a stayed blocked.

My own rules leaked in too: "Let's ensure the laravel and php rules don't load into this project." By mid-morning, with a Laravel backend about to start: "anything in server/ should be using it."

What I took from it

• Put local know-how next to the job. Skills ended the repeated briefs.
• A rule in prose erodes; a rule in a test holds. Every fresh agent is a new reader.
• Ratchet, don't rewrite. Freeze today's offenders and let the list only shrink.
• What an agent reads at start is a running cost. Every agent pays it, every time.

This one isn't about the game. It's about the team that builds it. Brackenmere is built by AI helpers, and every time I start a new one, it arrives knowing nothing. It has to read up on the project before it can do anything useful. For a while, what it had to read was a mess.

A start page, not a diary

At the end of each job, every helper wrote a note about what it had done. Nobody ever crossed anything out. So a new helper started by reading a long diary, then had to trust that the rules in it were still true.

When I asked whether the project was ready for faster building, the answer began "It's partly ready". The first problem it named was that diary. So the diary was put away in an archive and replaced with one short page of current facts: the golden rules, where things live, and how to check your work.

It also wrote little instruction cards for jobs that come up again and again, like adding a new world or a new piece of furniture. A helper picks up the right card when it starts that job. I stopped having to repeat the same instructions every time.

Overnight: check everything, then fix it

Late one evening I asked for a full check of the whole project: speed, tidiness, consistency, and how easy it is for helpers to work in. And I was clear: "actually do them, not just propose." Then I went to bed.

Five helpers looked first, each at one area. The report opened kindly, then made the real point: most of the golden rules were only written down. Nothing actually checked them.

Rules that check themselves

So the rules became automatic checks. If any new work breaks a golden rule, the check fails straight away and the helper has to fix it.

The clever part was not rewriting everything at once. Each rule kept a list of the places that already broke it, with a reason, and only complained about new ones. When an old problem got fixed, it had to come off the list. So the list can only get shorter.

Every piece of work now also runs a few end-of-job checks before it joins the main game, a bit like a building inspector signing off each room.

The morning after

One helper had sat stuck for hours overnight, waiting for my permission to tidy its own scratch files. So I set clear rules for what helpers may do without asking and what still needs me.

What I learned

• Put the know-how next to the job, and you stop repeating yourself.
• A rule that is only written down wears away. A rule that checks itself holds.
• Don't fix everything at once. Freeze today's problems and only let the list shrink.
• Whatever a new helper has to read is a cost it pays every single time.