runfoundry Write to Marcel on LinkedInWrite on LinkedIn

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.

Fig. 4 The three loops Drawn from foundry's design notes
The discovery loop, the build loop and the UAT loop Recordings and documents go into a discovery run, which writes claims, questions and draft requirements and merges itself when its checks are green. Open questions are answered, and I approve the requirement. In the build loop I pick a batch, a planner splits it, and I approve the plan. A test writer writes failing acceptance tests, a builder works task by task with checks and a fixer, the whole run is reviewed and checked once, and a run that is built and green merges itself. The product's pipeline puts it on dev, I approve production, and what real users do comes back as new material. A judge decides gaps in a requirement; an overseer picks one move when a run is about to get stuck. In the UAT loop I approve a UAT run, personas use the whole merged app on missions with no script, and the report sends gaps back to discovery as questions and confirmed defects to the build loop as tests; a normal release waits for a UAT report, hotfixes excepted. what real users do comes back as new recordings 1 · Discovery loop Recordings, documents,my own words Discovery run: claimswith quotes, questions,draft requirements Merges itself whenits checks are green Open questions answered I approvethe requirement 2 · Build loop A planner splitsthe batch I approve the plan Test writer: acceptancetests, red first Builder task by task,checks, fixer on red Review, full suite and CI,once per run Clean and green:the run merges itself red: blame reopens one task Inside a build run Judge decides a gap in a requirement and writes it down Overseer picks one move when a run is about to get stuck Production The product's pipelineputs it on dev I approvethe release In production,with real users merged, to dev 3 · UAT loop synthetic users on the whole app I approvea UAT run Personas use thewhole app, no script Report: defects,friction, gapsa soft block on a release,hotfixes exempt the merged app gaps go back to discovery as questions; confirmed defects become candidate tests for the build loop 1 · Discovery loop Recordings, documents, my own words Discovery run: claims with quotes, questions, draft requirements Merges itself when its checks are green Open questions answered I approve the requirement an approved requirement 2 · Build loop A planner splits the batch I approve the plan Test writer: acceptance tests, red first Builder task by task, checks, fixer on red Review, full suite and CI, once per run Clean and green: the run merges itself red: blame reopens one task Inside a build run Judge decides a gap in a requirement and writes it down Overseer picks one move when a run is about to get stuck the merged app 3 · UAT loop synthetic users on the whole app I approve a UAT run Personas use the whole app, no script Report: defects, friction, gaps a soft block on a release, hotfixes exempt Production The product's pipeline puts it on dev I approve the release In production, with real users merged, to dev Gaps go back to discovery as questions; confirmed defects become candidate tests. What real users do comes back as new recordings for discovery. 1 · Discovery loop Recordings, documents, my own words Discovery run: claims with quotes, questions, draft requirements Merges itself when its checks are green Open questions answered I approve the requirement 2 · Build loop A planner splits the batch I approve the plan Test writer: acceptance tests, red first Builder task by task, checks, fixer on red Review, full suite and CI, once per run Clean and green: the run merges itself red: blame reopens one task Inside a build run Judge decides a gap in a requirement and writes it down Overseer picks one move when a run is about to get stuck Production The product's pipeline puts it on dev I approve the release In production, with real users 3 · UAT loop synthetic users on the whole app I approve a UAT run Personas use the whole app, no script Report: defects, friction, gaps merged, to dev the merged app gaps go back to discovery as questions; confirmed defects become candidate tests a soft block on a release, hotfixes exempt what real users do comes back as new recordings

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 checkTask check
what runsTypecheck, lint and the unit tests next to the files the builder touchedTypecheck, 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 itThe builder or fixer, inside its own roundThe foreman, after the round ends
a verdict?No. It never freezes anythingYes. Green freezes the task, red sends a fixer
how longNot measured: it leaves no record4.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.

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 sizeWhat it gets, and its tools
Planner, largeThe approved requirements of the batch, the product's profile, the code. Reads, writes its plan file.
Test writer, largeOne 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, midOne 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, midThe 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, smallThe red check's whole log and the candidate tasks, each with its diff. Reads, has a shell, writes its answer file.
Reviewer, largeThe feature's diff, its requirement, the code around it. Reads, has a shell to confirm a suspicion, writes its findings.
Judge, largeOne 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, largeThe 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:

  1. 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)
  2. a line for me is open and isn't marked as information
  3. a review finding or question is open
  4. a unit test was weakened after the last review and no review answered it
  5. the goal check is red
  6. 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.

Fig. 5 Gate one: the requirement that changed, and the plan's header Example answer, invented product

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
  1. choose the destination country
  2. see the total with shipping
  3. enter the full address
  4. 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.

Fig. 6 One claim changes, one chain reopens Example from foundry's contract, invented product

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.

sourceS-2026-10-30-carrier-termsS-2026-10-30-carrier-terms claimC-4C-11supersedes C-4 requirementREQ-2 acceptance testA-2-1, A-2-2 task in G1.F2G1.F2.T2 code source claim requirementREQ-1 acceptance test task in G1.F1G1.F1.T4 code

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.

PartWhat it does
ForemanA program, run as a service. It makes the room, starts every round, runs every check, and merges.
RolesPlanner, test writer, builder, fixer, blame, reviewer, judge, overseer. Each is its own agent session with one job, started fresh.
RunnerThe only part that talks to a model: today Claude, through the Claude Agent SDK. Another provider means another runner.
A room per runA 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 folderEvery plan, event, check and report as a plain file in a private repository. Runs resume from it.
ContractVersioned 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.

Fig. 7 Where foundry runs Drawn from foundry's setup and design
The always-on server, the gaming PC, a third node and GitHub On the always-on server (16 threads, 64 GB): the foreman, a program running as a service on its own virtual machine; laneboard, which reads the runs and gates through the contract, and the state folder of plain files; the UAT room, which deploys the product with invented data for one UAT run at a time; the CI clean room, which gives each of the products' CI jobs its own throwaway virtual machine; and the GPU room, which transcribes recordings on an 8 GB GPU and keeps no audio. On the gaming PC, the stronger machine (20 threads, 64 GB): a throwaway run room per run with 8 virtual cores and 16 GB, cloned from a template, which reaches the internet but nothing on the home network and is destroyed when the run ends or waits at a gate; a warm suite room that runs the full suite in the background, one job at a time, at the lowest CPU priority; and the game's virtual machine, which can always start, because a run room starts only with 16 GB to spare. The foreman makes the rooms and syncs each round into them. When the gaming PC is in Windows or off, runs pause and resume from their files. A third node takes no part in foundry. On GitHub: the product's repository with its code, requirements, pull requests and CI, and a private repository with the record of every run, pushed every minute. Always-on server 16 threads, 64 GB Foreman, a program run as a service on its own VM: proposes the plan, starts rounds, runs checks, opens the pull request Laneboard, the page: runs and gates State folder: every decision as a file UAT room: the product, invented data personas use the app, one UAT run at a time CI clean room: the products' CI a throwaway VM per job, destroyed after it GPU room: an 8 GB GPU for speech-to-text transcribes recordings, keeps no audio Gaming PC 20 threads, 64 GB Run room: a throwaway VM per run 8 virtual cores and 16 GB, cloned from a template; rounds and checks run inside it; destroyed when the run ends or waits at a gate. Reaches the internet, nothing at home. Suite room, kept warm the full suite in the background, one job at a time, at the lowest CPU priority Game VM: always able to start a run room starts only with 16 GB to spare In Windows or off, its runs pause and resume from their files when it is back. Third node takes no part in foundry makes rooms, syncs each round suite jobs GitHub The product's repository code, requirements, pull requests, its CI A private state repository the record of every run, nothing secret checkout, run branch, pull request the run record, pushed every minute Always-on server 16 threads, 64 GB Foreman, a program, run as a service proposes the plan, starts rounds, runs checks, opens the pull request Laneboard, the page: runs and gates State folder: every decision as a file UAT room: the product, invented data personas use the whole app, one UAT run at a time CI clean room: the products' CI a throwaway VM per CI job, destroyed after that one job GPU room: an 8 GB GPU transcribes recordings, keeps no audio makes rooms, syncs each round, sends suite jobs Gaming PC 20 threads, 64 GB Run room: a throwaway VM per run 8 virtual cores, 16 GB, from a template; rounds and checks run inside it; destroyed when the run ends or waits. Reaches the internet, nothing at home. Suite room, kept warm the full suite in the background, one job at a time, lowest CPU priority Game VM: always able to start a run room needs 16 GB to spare In Windows or off, the gaming PC's runs pause and resume from their files. Third node no part in foundry GitHub checkout, run branch, pull request The product's repository code, requirements, pull requests, its CI the run record, pushed every minute A private state repository the record of every run, nothing secret Always-on server 16 threads, 64 GB Foreman, a program, run as a service proposes the plan, starts rounds, runs checks, opens the pull request Laneboard, the page: runs and gates State folder: every decision as a file UAT room: the product, invented data personas use the whole app, one UAT run at a time CI clean room: the products' CI a throwaway VM per CI job, destroyed after that one job GPU room: an 8 GB GPU transcribes recordings, keeps no audio Gaming PC 20 threads, 64 GB Run room: a throwaway VM per run 8 virtual cores, 16 GB, from a template; rounds and checks run inside it; destroyed when the run ends or waits. Reaches the internet, nothing at home. Suite room, kept warm the full suite in the background, one job at a time, lowest CPU priority Game VM: always able to start a run room needs 16 GB to spare In Windows or off, its runs pause and resume from their files. Third node no part in foundry GitHub The product's repository code, requirements, pull requests, its CI A private state repository the record of every run, nothing secret makes rooms, syncs each round, sends suite jobs checkout, run branch, pull request the run record, pushed every minute

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.

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.

Fig. 8 Pattern: build-until-green Excerpt from foundry's toolbox, pattern sheet

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 reasonWhen
donegoal check green, PR open, the merge decided
checks-redthe 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-7dthe 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.
errorsno room, an unreadable profile
stopped-by-persona 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:

Fig. 9 The UI loop: tasks finished per run Counted on the product's main branch, 11 November 2026

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 161 Run 250 Run 351 Run 448 Run 535 Run 623 Run 721 Run 831 Run 9not counted Run 1018 Run 11not counted
Tasks finished per run of the UI loop, Navigo Bau's new front end
RunTasks finished
Run 161
Run 250
Run 351
Run 448
Run 535
Run 623
Run 721
Run 831
Run 9not counted
Run 1018
Run 11not counted
Nine counted runs338

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:

  1. 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.
  2. 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.
  3. 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.
  4. 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

Back to the main page