How foundry works
This is the long version of the main page: the checks, the guards code enforces, and how a run ends. Numbers come from foundry's run records on Navigo Bau, 11 to 19 November 2026.
The three loops
Discovery drafts the requirements and build turns approved ones into merged code. Before a release, UAT tries the whole app. A discovery run's notes and drafts land on the product's main branch by themselves once their checks pass, but every requirement still waits for my approval. The build loop runs under the foreman; discovery's eight runs on Bau used simpler scripts on the Agent SDK. In UAT, personas use the whole merged app on unscripted missions, and what they find goes back to discovery and build. A normal release waits for their report.
Foundry sits above coding-agent sessions as a plain program that orchestrates them. The sandbox is the same idea as in other agent harnesses. What I'd call its own is in how it checks. Tests come from a separate role and must fail before the build. A guarded commit puts test files back. Blame rounds pin a red on one task. A judge picks the most reversible option and writes it into the requirement. And the self-merge rule is code. Inside a run the features are built one after another. The foreman allows several runs of one product at once when they share no requirement, but my hardware fits one run room, so runs queue and go one at a time.
Yellow: where I decide. Ink arrows: the way through a loop. Dashed grey arrows: what passes between the loops.
Checks, and where they run
There are two checks at the bottom of the work tree, and only one of them counts.
| Step check | Task check | |
|---|---|---|
| what runs | Typecheck, lint and the unit tests next to the files the builder touched | Typecheck, lint, the product's tests for the folders the task touched (the whole unit suite if a file sits outside every listed folder), and the tests of the feature's finished tasks |
| who runs it | The builder or fixer, inside its own round | The foreman, after the round ends |
| a verdict? | No. It never freezes anything | Yes. Green freezes the task, red sends a fixer |
| how long | Not measured: it leaves no record | 4.7 minutes at the median on Bau, over 131 task checks |
Above them, a feature check runs the feature's acceptance tests by id, then the tests its files can affect (6.1 minutes at the median over 100), and the goal check runs the review, then the full suite and the product's CI, normally once per run (again only after a goal-level fix or a send-back). A warm suite room also runs the full suite in the background for all runs, so a break between tasks shows early.
The agents' own shell has no network: every command a round runs goes through the Agent SDK's sandbox, with the model credential unset and writes allowed only in the room's checkout and the round's own folder. Build roles get no web tools. The test commands the foreman runs go to the run's throwaway virtual machine, which can reach the internet but nothing on my own network.
What that means if a test command broke out: it would find no repository token and no credential for production or the cloud, and it couldn't reach my network. Two secrets do enter the room: the model credential, on standard input to each round while it runs, and the product's package-registry token, which only the install command gets; no check ever sees that token. It could still reach the internet, so it could send the product's code out. And the test commands run as the same user in the VM as the rounds: a process a test leaves running could read the model token of a later round and send it out too. That's the open risk. The cures are known and not built: checks under a user of their own, every leftover process stopped before each round, and an allow list that lets only the package registries through during install and nothing during tests. The other way in is the input. Customer recordings become requirements, and requirements become prompts, so every requirement and every plan is approved before a build starts from them. Discovery's own notes merge without me, though, and sit in the repository a build round reads.
Flaky tests get one rule: a red test command runs a second time, the second result counts, and a green on the second go is listed in the report. Acceptance tests at the feature check get no second go; a red there goes to blame. A test stack that doesn't come up, or a room that goes away, is no verdict at all: the check runs again. One weakness is left. A real red also runs twice, which costs a whole suite.
What the builder can't touch
Every builder and fixer round ends in one guarded commit. The foreman makes that commit after checking what changed, so an edit to the files below doesn't survive the round.
- Put back. The foreman puts back any change to the feature's acceptance tests, the config chain above them, the product's profile, CI, test-runner configs, lockfiles,
.gitignoreand the test sections of the build config, and the task check goes red. The round's tools can edit them; the foreman restores them from the test writer's commit. - Held for review: a unit test file deleted, left with fewer tests, or given skip or only marks. Each becomes a point the next review must answer, and an unanswered one keeps the run from merging itself.
- Tests come first, from another role. The foreman checks that each new test fails on the code before the build, or that the test writer openly declared it already met. A test changed later must still fail on the pre-build code.
- The verdict comes from the foreman running the tests by id. What the round says doesn't count. An id that runs no test counts as red.
A test declared already met is listed in the report but doesn't hold a self-merge; only the reviewer looks at it. That isn't rare: on Bau, 99 of the 244 acceptance tests written in the fifteen runs were declared already met: they prove nothing about the new build, though they still guard against a later regression. Nothing measures whether the test writer's tests are strong enough either. That rests on the review round too: foundry runs no mutation testing of its own.
Models, and moving up a size
Each role has a size: small, mid or large. Today those are Claude Haiku, Sonnet and Opus. The planner, the test writer, the reviewer, the judge and the overseer run large; the builder and the fixer mid; blame small, because it's triage.
Moving up is a rule written in code; no agent gets to decide it. After two failed rounds on one task the next round runs one size up, and after four the task blocks. On Bau that happened for ten fixer rounds and one builder round. Blame has its own rule: it starts small and runs once more at mid if its first answer names no task or isn't sure. Over all Bau runs: 170 rounds large, 185 mid, 62 small.
What a round gets
Every round is a fresh agent session with one job. It starts from files the foreman writes for it. Anything it learns is gone unless it writes it back. Where a role has a shell, it's the sandboxed one described above. Only the builder and the fixer keep changes to product code, and the test writer to the feature's acceptance tests. Anything else a round changes is put back when it ends. The overseer has no write tool at all.
| Role and size | What it gets, and its tools |
|---|---|
| Planner, large | The approved requirements of the batch, the product's profile, the code. Reads, writes its plan file. |
| Test writer, large | One requirement with its acceptance lines, the labels a test may look for, how the product's tests run, the code as it is. Reads, edits acceptance tests only, has a shell. |
| Builder, mid | One task with the notes of earlier rounds, its requirement, the acceptance tests to read, the profile, the code. Reads, edits, has a shell. The foreman makes its commit. |
| Fixer, mid | The task and its notes, the red check's whole log, and for a reopened task the blame round's answer. Tools as the builder. |
| Blame, small | The red check's whole log and the candidate tasks, each with its diff. Reads, has a shell, writes its answer file. |
| Reviewer, large | The feature's diff, its requirement, the code around it. Reads, has a shell to confirm a suspicion, writes its findings. |
| Judge, large | One gap, the whole requirement and the claims under it, the decisions already taken on it in this run. Reads and searches the code, writes its answer. |
| Overseer, large | The stop, the record around it, its own earlier moves in this run, the moves it may pick. Reads only, no shell. |
The sheets behind three of these rows are published: the builder's, the test writer's and the judge's.
When a run merges itself
On 13 November gate two was the merge: the pull request waited until I approved it. Now a clean run merges itself, as two did for the first time on 19 November, and my gate is the production release. A run is clean unless one of these holds:
- a feature is neither built nor set aside (a feature whose work never reached the run's branch may be set aside, its work kept on a branch of its own)
- a line for me is open and isn't marked as information
- a review finding or question is open
- a unit test was weakened after the last review and no review answered it
- the goal check is red
- a red from the background suite isn't settled
The merge goes through GitHub's auto-merge, so the product's required checks on the pull request have to pass too. A product can switch self-merge off. With the UAT loop, a normal release waits for a UAT report: a soft block, with hotfixes exempt.
The judge and the overseer
A gap can reach the judge from the test writer, a builder or fixer, or a reviewer. If the answer exists, it gives a fact and its source. If there's a real choice, it picks the option that's easiest to undo, writes it into the requirement as the loop's, and the work goes on. It asks me instead when the choice would contradict an approved line or something a person said, can't be undone (money, data deleted or rewritten for good, messages to people outside the app, who may see or do what, anything a law or contract governs), or would be the sixth decision on one requirement in one run. Then that feature parks and the others go on. It doesn't add features or change what I approved. What a requirement leaves free on purpose, such as layout, controls and wording, is the builder's choice, with one line of why.
The overseer wakes only when a run is about to stall. It makes one move per wake from a fixed set: recheck, retry with a hint, hand to another role, ask the judge, add a task, raise a limit once, repair, wait, set aside, ask, or stop the run. Its tools only read, and code checks each move before it's taken. It wakes at most three times for any one task or feature, and at most six times the number of features in a whole run. If the overseer itself fails, the run carries on.
How I check them: on Bau the judge made nine calls. Its four decisions are written into the requirements, where I can read them. I haven't overturned any, and I haven't confirmed any either. The overseer hasn't woken on a real run.
One example, followed through
An invented shop, taken from the examples that ship with foundry's contract (the schemas laneboard reads, described under Parts). A claim about shipping, C-4, was replaced by C-11 (a flat rate per country). So one requirement, REQ-2, was redrafted, the plan changed, and at gate one the owner is asked to approve the plan's new text.
The requirement
REQ-2 redrafted (C-4 replaced by C-11)
A buyer sees the full price, shipping included, before paying
- outcome
- Before the last step a buyer knows the total they will pay.
- workflow
- choose the destination country
- see the total with shipping
- enter the full address
- pay
- rules
- the total shown before paying equals the total charged
- shipping follows from the country alone (C-11)
- acceptance
- A-2-1 Given a cart and an address, when the buyer reaches payment, then the total includes shipping
- A-2-2 Given an order, when it is charged, then the charge equals the total shown
The plan (a recipe, in laneboard's words)
Guest checkout: recipe revision 2 (more rounds)
goal: [REQ-1, REQ-2] status: proposed
revision: sha256:8ed771e8d2fc03fd
The owner approves the plan's exact text, tied to this hash
Shortened from the example file; quoted lines are verbatim.
The same REQ-2 as a chain of blocks: source, claim, requirement, acceptance test, task, code. Beside it stands REQ-1, which the change doesn't touch.
One claim changes: C-4 is superseded by C-11. Only what depends on C-4 is rebuilt: the tests get rewritten first, and whichever now fail define the work. REQ-1 isn't touched.
Two chains from the same shop, REQ-2 and REQ-1.
Pale: source, claim and requirement, which have no check of their own. Green: its checks pass. Red: a test now fails. Cover lifted: the task is reopened. Cover down: frozen.
What foundry is made of
Foundry is written in TypeScript, and most of it is plain code. Agents only get the steps that need judgement: planning, writing tests and code, review, blame and the judge's calls.
| Part | What it does |
|---|---|
| Foreman | A program, run as a service. It makes the room, starts every round, runs every check, and merges. |
| Roles | Planner, test writer, builder, fixer, blame, reviewer, judge, overseer. Each is its own agent session with one job, started fresh. |
| Runner | The only part that talks to a model: today Claude, through the Claude Agent SDK. Another provider means another runner. |
| A room per run | A throwaway virtual machine. No repository token and nothing for production or the cloud: the foreman clones and pushes. Only install gets a package-registry token, for that one command. The model credential reaches a round there on standard input, only while the round runs, never in a file, an argument or a log, and the round's shell commands run with it unset. |
| State folder | Every plan, event, check and report as a plain file in a private repository. Runs resume from it. |
| Contract | Versioned schemas and example answers. Laneboard reads foundry only through it, so either side can change on its own. Fig. 5 and Fig. 6 are one of its examples. |
Where it runs
The foreman, laneboard and the state live on a small always-on server. The runs themselves happen on a stronger machine, and when that one is off, they wait.
Ink arrows: the foreman's work. Thin grey arrows: what goes to GitHub, and the checkout that comes back.
What runs underneath
Foundry runs on my own homelab: three machines, each running its own virtual machines, and not joined into a cluster on purpose. Nothing here would ever move between them. The always-on server (16 threads, 64 GB) holds the foreman, the products' CI and an 8 GB GPU that transcribes recordings. My gaming PC (20 threads, 64 GB) does the heavy work when it isn't running a game. The third node takes no part in foundry. The rule: what must always be on lives on the server, what is heavy lives on the gaming PC, and nothing that must keep running depends on the gaming PC.
- A room is born and destroyed with its run. The foreman clones a template that already holds Node, Python, Docker, a test browser and the usual database images, plus foundry's own room agent, and no product code, no repository key and no token. The clone gets 8 virtual cores and 16 GB. When the run ends, or just waits at a gate, the room is destroyed, and a resume gets a fresh one in about 30 seconds. The account the foreman uses can make and destroy those rooms and do almost nothing else. A room starts only if the gaming PC has 16 GB free beyond what the game needs, so one run goes at a time.
- One warm suite room sits beside them and runs the product's whole test suite, queued, one job at a time for all runs, at the lowest CPU priority on the machine. A build never waits on it, and it holds no secret.
- The fence. A run room takes SSH from my home network and nothing else. Going out, it reaches the internet and nothing on my home network: not the hosts, not the foreman, not the suite room, not the other rooms. The open way out to the internet is the risk named under checks.
- Runs pause when the gaming PC is away. Playing a game doesn't stop them; rebooting into Windows does. The foreman notices after about half a minute of missed answers, holds every start and resume, and counts nothing the missing machine broke against a run. When the machine is back, the runs go on from their files. There's no fallback on the server: CI there was starving at its peaks.
- The CI clean room came first. On 12 October 2026, before foundry, I moved the products' CI home. Every job that runs at home gets its own throwaway virtual machine with a single-use runner, destroyed after that one job. A small controller holds the GitHub credential and writes each VM its one-time runner config from the host side, never over the network, and its hypervisor token can touch nothing but those VMs. Hosted CI fell from about 470 minutes a day to under 135. The bill went from USD 111 in September to USD 69 in October, though most of September's was a repository retired that month. The run rooms copy the pattern: a template with no secret in it, a clone per run, destroyed after. Their secrets come per command, on SSH standard input from the foreman, never in a file or an argument.
Running it taught me two things. More CI in parallel made CI slower: at peaks 28 virtual cores fought over 16 threads, and a lint-and-test job took 27 to 36 minutes instead of 12.5. With half the parallel jobs, each one ran two to three times faster. And rights can die with a VM: the first setup gave the foreman's account its rights per room, the hypervisor deleted them with the room, and the second run's clone was refused. The rights now sit on the group the rooms belong to, which outlives every room.
What a run costs
Every round records its cost at API prices, per run, role and model size, and each recipe caps the rounds: the build recipe allows 10 plus 6 per task by default. The fifteen build runs on Bau cost about $220 together. Discovery runs, eight of them on Bau, cost $2.46 to about $250 each; the $250 one was the first survey, counted before its report round. The figures are a lower bound, because a failed round that hit its turn limit was recorded with no usage.
How a run ends
Foundry's own pattern sheet for building until every check is green, quoted from its toolbox.
A review/fix loop ends on a fix, never on a review
- a review is never the last step of a feature or of the goal. Its findings are fixed and checked before anything ends;
- after the last allowed review (
review_cycles), its findings are still fixed and checked, but no new review runs; - findings that can't be fixed inside the caps go to the run report as open, and the stop reason says so. Never silently.
Stop conditions
| Stop reason | When |
|---|---|
done | goal check green, PR open, the merge decided |
checks-red | the plan could not be made (the planner's round failed twice, or it stopped), before anything is built (until 15 November, also a red goal check blame couldn't explain, as in Fig. 2's second run on the main page) |
budget / window-7d | the recipe's share of usage, or a brake on a rolling seven-day usage window. The round budget doesn't stop a run: a used-up budget ends like a run where nothing can move. |
errors | no room, an unreadable profile |
stopped-by-person | a person stopped it; it finishes the current round first |
Not a stop but a gate: if the goal check stays red after its retries, or blame can't explain it, the run waits at the merge gate with its pull request open and the red listed first. Foundry won't merge it; a resume runs the goal check again. In each case the work is on the run branch and a resume takes it up.
In the run records: until a rule change on 15 November, a goal check that stayed red and that blame couldn't explain also ended a run as checks-red, as in the second run of 15 November. The overseer's "stop the run" move ends a run as checks-red too.
Shortened. The review and fix lines are quoted exactly; the stop table is reworded for this page.
The UI loop, before foundry
Before foundry, a simpler loop rebuilt the front end of Navigo Bau in eleven runs from 23 October 2026. It has run in production since 1 November. Its tasks, run by run:
One block per finished task, ten to a layer. A chevron is the time between two runs.
The new front end: 392 files, about 70,000 lines, 27 end-to-end test files.
| Run | Tasks finished |
|---|---|
| Run 1 | 61 |
| Run 2 | 50 |
| Run 3 | 51 |
| Run 4 | 48 |
| Run 5 | 35 |
| Run 6 | 23 |
| Run 7 | 21 |
| Run 8 | 31 |
| Run 9 | not counted |
| Run 10 | 18 |
| Run 11 | not counted |
| Nine counted runs | 338 |
338 tasks in nine of the eleven runs. The records don't say why the count fell from run to run.
Why it came out usable
Persona reviewers went through screenshots after every run. All styling came from one design system, and a lint rule rejected any screen that tried to style itself. I wrote the requirements to say what each workflow had to do and left the layout alone. Whatever people tripped over on site went into the next run's plan.
What the runs taught
The series of real runs on 13 and 14 November took about 32 hours of wall time. About 5% went to actual work, and only about 2% to product code that was genuinely wrong. Half went to a runtime bug and to waiting until I resumed a run, about 40% to acceptance tests that couldn't run or a flaky product test. Four of the causes behind that:
- The checks were far heavier than the work. Every feature check ran the product's whole unit suite, about five minutes, and in one run it ran at least 38 times. Acceptance tests go first now, and the whole suite stays with the suite room and the goal check.
- Blame used to see only the last 5,000 characters of a log; blame and the fixer now get the whole log, and blame gets each candidate task's diff.
- A red goal check that blame couldn't explain ended the run with nothing marked built. A run now keeps its work when it ends red: it waits at the merge gate, and a resume picks it up.
- What could be known at the plan gate turned up hours later, such as a requirement that needs something the test room can't give. A check before the gate, while I'm there to answer, would catch it, and there isn't one.
A later failure, on 18 November: a fix round ran out of its 60-turn limit twice within ten minutes, with twelve files changed and nothing committed. A blocked task parks its feature and resets the room, so that work would have been lost; I copied it out by hand. Now a round that ends on its limit with work in the room goes on from there, and work no check has seen is kept on a ref and handed to the next round. That is built and tested, but no real run has needed it yet.
Limits
- One product, one stack, one provider. Products plug in through a profile, but every real build run has been on Navigo Bau, Python and TypeScript, on Claude. The runner has one real adapter.
- No baseline. I split the roles so the builder never grades its own work. Whether that beats one strong agent session given the same tests and profile, I haven't measured: no such run exists.
- Self-merge is young. It first fired on real runs on 19 November 2026.
- Delegated gates. A Claude session approved the plan of every build run on Bau and five of the merges, on my standing go-ahead, so for those calls "I decide" meant I set the rule, not that I made each call.