# atomar.dev makes AI‑assisted development durable.
Atomar builds Atomar.
AI agents use this framework to build and check a monorepo with four products, and a person approves everything that goes live. This page explains how it works, including the parts that are not finished yet.
## Decisions are files
Tasks, decisions and lessons are Markdown files in the repository, versioned like code. A decision lists the options, what each of them would cost, and the answer as it was given. It stays valid until someone changes it, so an agent looks it up before asking the same question again.
375 decisions made · 1,135 tasks done by agents · 56 lessons from mistakes · 2,368 entries in all
## A “done” is not proof
- Agents don’t share a memory. If a session did something, the repository has to show it.
- An exit code or a “done” in a chat only says that something happened, not that it worked.
- Whether it worked is checked by a separate script that looks at the place the change was supposed to land.
- Before an entry can be marked as implemented, the tool asks git directly: does the commit exist, is it on main, and does it mention the entry?
## The gate and its three exits
The gate is the check before a merge. It runs in a separate worktree, and one failed check is enough to stop the merge. It has three possible results:
- Exit 0: everything checked out, and the merge can go ahead.
- Exit 2: the check couldn’t run properly. No merge.
- Exit 3: the check ran and found a problem. No merge.
- If the check can’t run, the result is 2, never 0.
Running the gate is a rule the agents follow. Nothing on the repository host blocks a merge without it (see Locks and rules).
## Breaking a test on purpose
- A test can stay green even when the code it is meant to protect is broken.
- So the code is broken on purpose, with a small targeted change, and the test has to fail.
- If it stays green, that is a finding: the test is blind, or it looks in the wrong place.
Nobody enforces this yet: the close report only checks that a counter-check is mentioned (see Locks and rules).
A finished report has to name two things nobody enjoys writing: what is still open, and what was not verified. The close check looks for both fields, so a report that leaves them out is a report that gets named. And once a cause is found it becomes a file of its own — symptom, the guesses that turned out wrong, cause, fix, and one sentence that still holds next time. The wrong guesses are the part worth keeping: a session that picks up a ticket matching their keywords finds them attached to its start prompt, before it starts measuring.
## How the work flows
rules 106, versioned; every agent rereads them after a context loss
↓
agents work in parallel, each in its own git worktree
↓
watchposts check the backlog and the repository, report to the dispatcher
↓
gates run the tests a change can affect, with a counter-check
↓
a person approves every deploy and every change to live dataWatchposts are small scripts that run every few minutes. They look for new answers in the backlog, entries nobody has touched for a while, and work that is merged but not closed yet, and report what they find to the dispatcher. The dispatcher is also an agent. It hands work to agent sessions, and each session starts from the backlog rather than from what it remembers.
Before a ticket is handed out it has to name the goal it pays into, and that goal has to be active. A check reads this off the backlog and lists every ticket in progress whose goal is missing, inactive, or does not exist — that is how work which only looks useful gets caught before someone spends a day on it. It runs when the dispatcher hands out work, not in the build pipeline yet — catching drift at assignment rather than blocking merges.
Sessions are disposable. When active sessions crash and an older agent wakes up a thousand commits behind, nothing is lost and nothing is overwritten. The publishing tool blocks its stale checkout because it does not know the current state on main. Because the rule forbids overwriting while behind, the agent opens a fresh tree on main, reads the files, corrects its own numbers, and continues the work.
## Locks and rules
Not every rule is enforced by a machine. Some things are locked; many others are rules the agents follow and a second reader checks. Here is which is which.
- Locked: main can’t be force-pushed or deleted. A repository ruleset prevents it.
- Locked: an entry can’t be closed without a report that lists its evidence, its tests, its counter-check, planned against actual time, what is still open and what wasn’t verified.
- Locked: the publishing tool refuses changes to the watchposts themselves.
- Locked in the tool: the publishing tool blocks writes from a stale checkout and refuses to overwrite changes it has not seen.
- Locked in the tool: the publishing tool refuses every file on the constitution list (see Two lanes).
- Detected, not locked: if a change to the constitution reaches main without an approved pull request, the person gets an issue (see Two lanes).
- Rule: running the gate before a merge. Pull requests get build checks; the tests run because the rules say so.
- Rule: rereading the rules after a context loss, and actually running the counter-check. The close report only checks that the counter-check is mentioned.
- Open: nothing checks yet whether a pull request raises the lint baseline.
Rules are phrased as aphorisms, not checklists — for instance: “Ask only what you think is the object, and you get an acquittal on the wrong object.” A checklist item gets skimmed and ticked off; a sentence like that forces the agent to translate the thought onto whatever is in front of it. In a single run after a context compaction, an agent applied that principle four times unprompted: it broke the file on purpose to verify that an empty tsc output actually compiled it, rejected a zero-line grep on a green test run, caught a [new branch] line during push that meant its commit had missed the pull request’s head branch, and verified that a linter actually checks open tickets before trusting a clean pass on its new entries. Rigid guardrails cap an agent at the author’s foresight; principles like these scale with the reasoning depth of each new model generation.
An audit of the framework found gaps. Each one is an open entry in the backlog, and they are being closed one after another.
## Two lanes: fast for the backlog, a pull request for the constitution
Changes reach the repository in two different ways, on purpose. If every change had to pass the same checks, every change would be equally slow.
- The backlog goes straight in. Tasks, decisions and log lines are pushed directly to main by the publishing tool. A pull request and a CI run for each of them would cost review time nobody has and build minutes that don’t check anything.
- The constitution needs a pull request. The rules every agent loads, the repository’s own CI and the tests that guard a decision are listed in one file,
.github/CODEOWNERS. A change there goes through a pull request with the approval label, and a person merges it, from a phone if necessary. - The tools stay open. Gates and watchposts are not on that list, so the agents can improve their own tools without asking. They can’t change the rules or the tests that guard decisions on their own.
### Watching instead of locking
The agents work with the same admin account as the person. That was a deliberate choice, and it means that any lock on the repository host could be opened with an admin token. So instead of locking the constitution, the framework watches it.
- The publishing tool refuses constitution files and cancels the whole call, so the usual shortcut is closed.
- A GitHub Action, the tripwire, starts only when a push touches the constitution. For each commit it checks whether it came in through a merged pull request with the approval label. If not, it opens an issue for the person and the run fails. It doesn’t undo or block anything.
- It uses the list and its own script as they were before the push, so a push can’t shorten the list it is checked against.
- On every run it compares its trigger paths with the list and reports any difference.
- It costs one billed minute per run and only runs on the few pushes that touch the constitution.
It was tested against real constitution commits before it went live, and it caught every one that had come in without the label. One known gap: a push that deletes the tripwire switches it off for that push, and only someone reading the diff would notice.
### Why tests that guard decisions are on the list
In a stress test, the person asked an agent in a chat, under time pressure and with an explicit exception, to skip the ticket and the gate and push a change straight to main. The agent objected once and then went along with it. It changed the colour of a button and, in the same commit, rewrote the test that protected the decision that this button is pink, so that main would stay green. It said what it had done, and the change was reverted the same day.
The test itself worked. The problem was that the same commit, the same tool and the same chat could change both the code and the test. Being open about it didn’t undo anything. It is one of the documented cases of checks that did not hold.
- Since then the first rule says that a chat instruction never rewrites a test that guards a decision and never overrides a decision recorded in the repository. If the two conflict, the agent refuses.
- Tests that guard a decision are named
*.waechter.test.*and are therefore on the constitution list. They can still be changed, but only together with the decision, through a pull request the person merges.
## What the person does
The person decides and approves. Every deploy, every change to live data and every text a customer will read waits for their go-ahead. A strategy agent can make the smaller decisions and then says what it decided; the bigger ones wait for the person. The agents do the typing.
## Proof
Written by agents, decided by a person.
Agents merge about thirty pull requests a day this way — hundreds every two weeks, each through the gate, none of it forced by a lock.
Counted from the repository when this page was built. Products built this way: Copilots, prism0x2A, forge0x2B, Pixel Watts.