How we build

AI writes most of the code, but it doesn't decide what to build, and it doesn't decide when something is ready to ship.

Thirty years ago, change control at a lot of banks was a developer, a live system and a late night. We'd like to say we were better than that, but we weren't.

Everything on this page is the opposite of that. Every change starts in writing, gets argued with before anything is built, and has to pass the full test suite before it lands, and the auditor is welcome on every floor, because every decision and every change is written down.

The build loop: record, grill, plan, plan grill, bites, gates, landSeven steps left to right, with a human at every step.Decision recordthe design, writtenGrillfour seats challenge itPlanbites and scenariosPlan grillpressed againBitesfailing test firstGatesbuild · unit · integrationLandfull suite greenA human at every step
Every change walks this row. Nothing skips a step.
  1. Every change starts as a decision recordIt sets out the context, the decision, the consequences and any standard it touches, and it becomes the specification, kept in the repository alongside the code. Its number is a GitHub issue, opened first so that two people can never grab the same number, and the project board is updated from the record, never the other way round.
  2. The grillBefore anything is built, the design is challenged from four seats: the clerk who uses it under time pressure, the auditor reconstructing what happened months later, the financial director who answers for the numbers, and the salesperson trying to show it in a demo. Only what survives gets built.
  3. A plan of bites, with scenariosThe plan names every file each step (we call them bites) will touch, and what has to be true when it's done. For anything that moves money those criteria are written as scenarios, given this, when that, then the other, and the plan names the commands and events they rely on, so the tests can be written before any of the code exists.
  4. The plan grillThe plan gets the same treatment as the design, the moment it's written. We look for a bite that can't actually be built and proven on its own, a file the plan forgot, or a screen the change affects that nobody checked, and anything we change is recorded on the plan.
  5. The failing test comes firstA separate AI agent writes the acceptance tests from the scenarios alone, without ever seeing the implementation, so the tests can't quietly bend to fit the code. They fail to begin with. A bite can't be committed while its test is red, and it can't be made green by changing the test.
  6. Guarded developmentArchitecture tests fail the build if one feature reaches into another, a permission is missing, a handler is never exercised or an identifier loses its type, so the rules live in code rather than on a wiki page nobody reads. Line-by-line code review earned its way out. Our founder read every AI-written change until the output could be trusted, the same way you come to trust a new developer by watching their work, and then the review moved to where it does most good: the design, the plan, the blind-written tests, the full suite, and a regular audit of the whole codebase. The last audit, and its grade →
  7. The merge queueEvery change reaches the main branch as a pull request, and the merge queue is the only thing allowed to put it there. The queue runs the full suite on our own build machine, with the change sitting on top of the latest main and anything queued ahead of it, so two people landing at the same time are never testing against a main that has already moved. A red goes back to the lane that sent it, and a change never gets an easier ride because someone else is waiting to land theirs.
The whole loop

The row above is one change. Around it runs the loop that decides which changes get made at all, and it never really stops.

Several changes are built at once, each in its own lane with its own branch, and a coordinating session keeps track of them all and sorts everything they turn up. It never builds anything itself. A finding is parked, sent to a human for a ruling, or turned into a decision record, and only a human accepts a design or decides when staging moves. The merge queue is the only thing allowed to write to main, so two people landing at the same time can't break each other's work, and a red goes back to the lane that caused it, because that's where the context is.

The development loop: triage, design, lane, merge queue, and back to the next findingA finding or idea is triaged by the coordinator: parked, sent to a human for a ruling, or promoted to a decision record. The record is grilled, planned and accepted by a human, then built in its own lane with blind tests first. The land opens a pull request, the merge queue runs the full suite on the latest main, and a red goes back to the lane. What reaches main is deployed to staging when a human says, used on the UAT desk, and what turns up there or at the weekly retro becomes the next finding.Finding or idealane, desk, retro, auditCoordinator triagestracks, never buildsA human rulesand the ruling is writtenParkedin the register, with whyDecision recordthe design, writtenGrillfour seats, with a humanPlan and plan grillbites and scenariosLane cutown branch and worktreeBlind testsfrom the scenarios, redBites builtto green, guards onLandrecord shipped, PR openedMerge queuefull suite on latest mainMerged to mainonly the queue writes itStagingdeployed when a human saysUAT deska human uses itWeekly retrowhat bit us, and whyTriageAccepted?Green?ParkNeeds a designNeeds a rulingNeeds revisionAcceptedRed: the lane fixes itGreenA new findinga human decides

Swipe sideways to follow the whole diagram.

Everything the loop turns up comes back round as the next finding.
The skills

38 skills and 6 agents, each with one job, and they all ship with the source.

A skill is a written procedure the AI follows to do one job the way this codebase does it. An agent is a skill that runs with its own context, which is how the test author is kept from seeing the code it's testing. This is the set that works for us, and because they're plain text files you're free to change them, drop the ones you don't want, add your own, or bend the whole loop to fit how your team works.

Design

Create a decision record, opening its GitHub issue · grill it · write and grill its plan · model a contested concept · keep the status map, the issue and the project board in step

Build

Implement an ADR bite by bite · scaffold a command slice · author an account type from a template · write tests the suite's way · write the help article · sync settings YAML with the database · regenerate API types · draw a diagram

Prove

Run the full suite on the build box · bring up the UAT desk · audit shipped claims against the code · audit event-to-projection coverage · read the coverage report · speed up a slow test · read a CI failure

Land and run

Land through the merge queue · sync the day’s docs to main · deploy staging on demand · partition work into lanes · coordinate the lanes · the weekly retrospective · seed and reset an environment · sweep the dependencies for upgrades

The agents

The acceptance-test author, who never sees the implementation · the cross-feature guard · the bootstrapper auditor · the seeding-impact analyser · the UI-to-API sync checker · the CI-failure analyser

The loop ships with the source, so your team can run it with the same skills, gates and records we use, or with its own version of them.