The agent org

The last era isn’t about the product at all. It’s about the thing that builds it.

What it was. Since May, Alter had been built by an iteration loop: an agent reads the backlog, picks one unblocked item, builds it, tests it, ships it, exits, and the next one picks up where it left off. Good loop engineering, and one loop, hand-cranked. I picked the work, watched it, deployed it, and read the output.

August turned it into an organisation: a value stream with departments (analysis, design, implementation, verification, acceptance testing, release) over a shared ledger that is just the repository, with git history as a free audit log. A dispatcher wakes on a timer, reads state, applies a fixed decision table, spawns at most one thing, and exits. Deliberately boring: intelligence belongs inside the nodes, not in the router.

What went wrong. The obvious problem wasn’t the agents. It was state.

Running several in parallel livelocked them: not on code, on documentation. Each shipped item hand-edited the same few tracking files, so a conflict in a paragraph of prose forced a rebase of a branch carrying code, which re-ran the entire test matrix, during which the next pull request conflicted again. Nothing was broken. Nothing could finish, either. It’s the most instructive failure in the whole project, because every part of it was individually correct.

What I decided. Fix the file layout, not the agents. Every file gets exactly one writer. Anything with multiple producers (bug reports, run records, changelog entries, verification verdicts) becomes one file per fact in a directory, because distinct files never conflict in git. And the aggregate views stopped being edited at all: they’re compiled from the individual records by a script that runs in exactly one place. Parallel agents now touch disjoint files by construction.

Three more rules came out of the same design, and they’re the ones I’d carry to any project like this:

• Nothing marks its own homework. Each iteration fans out to an independent verifier and a breaker, launched with a deliberately thin brief: the work-item and a diff range, nothing else. Hand a reviewer the builder’s reasoning and you get the builder’s conclusion back.
• Limits are mechanical, not textual. Heavy operations sit behind wrappers holding real locks with disk-headroom checks, and a hook denies the raw commands outright. A prompt asking an agent to be careful is a suggestion; a lock is not.
• Exactly three human gates. Which idea gets built, sign-off on anything user-facing, and the production deploy. Everything else reports and never blocks.

The last piece was shipping itself. A one-service fix used to take an hour and a half to reach a deployable image, which quietly meant nothing urgent ever got fixed urgently. Rebuilt in September: 2–5 minutes, by building each architecture on its own machine and carrying unchanged services forward as provably identical images instead of rebuilding and assuming.

Where it stands. Alter is live, paid, and the thing I open first in the morning. Fourteen phases, 178 merged pull requests, nine months. The build problem is, more or less, solved.

What’s left is harder and more interesting: the distance between a system that files your life correctly and one you actually reach for. That turns out not to be an engineering problem, which is exactly why it’s the one I’m working on.

Start again at the beginning, or try the thing itself.