What is an AI agent today? It’s actually quite simple. There is a language model — the brain and the center of decision making. And there is a harness around the model: the environment where the model works — the thing that makes the model an agent. Without the harness the model is just a text generator, sometimes quite a smart one.
Most of the resources of the labs around the world go into improving the models, which we use as is — and thank god, it’s not us who pay for their training. The harness gets much less attention from the research community. So I have good news for you: the harness is exactly the place where an indie researcher can make a contribution, without having the resources of the frontier labs.
Today the harness mostly means two things: MCP and Skills. Skills explain to the agent in free text how to approach a task; MCP gives it the tools for that. The idea is quite elegant: give the model a minimal kit — and let it assemble the solution on its own.
But all this elegance rests on one assumption, that the model will follow the received instructions. And a skill is just text in the context window, which the model is not obliged to follow. Skills today are basically prompt engineering on a new lap: they raise the odds, but they give no guarantees. And the problem is not the quality of skills: you can write an excellent instruction, covering all the nuances. But if the model can simply ignore these instructions — it’s a bad foundation for a reliable system. A good foundation needs something else — a structure that the model doesn’t read but executes, with no way around it.
I got here not by theorizing but by hitting walls, project after project: I built an AI mobile developer, taught an agent to actually test things, made a harness repair itself between tasks, and finally moved everything onto a local 27B model, replacing the LLM orchestrator with a finite state machine. I wanted my agents to solve complex tasks autonomously, for many hours, without my intervention. And ideally — to do all of it with lightweight local models that can run right on my laptop. And in every new project, while raising the bar for autonomy and quality, I had to make the harness a bit less advisory and a bit more structural, until it stopped being instructions and became code. Why orchestration with deterministic state machines beats orchestration through reasoning is a separate post; the one-line version: control flow lives in code, and the model is only responsible for judgment at the leaves.
But when the harness of my agents collapsed mostly into code, I was still writing it by hand. For every new task I decided what the topology of the state machine will be, what happens in each state, what contracts between the agents, etc. The essence of this process is reasoning about the task.
An attentive reader will say: but this is how we solved agentic tasks a few years ago, and then we dropped it in favor of orchestration through reasoning, when the models became smart enough — am I trying to sell an old idea? And he will be absolutely right: deterministic orchestration returns control, but it takes away the main achievement of the reasoning era — the model’s ability to derive the solution on its own. To fix this problem, today we will go up to the level of meta-agents and bring the model back into the loop of orchestration decisions. But we will do it in a clever way: we will build an agentic system that spends reasoning once to build a deterministic machine, which then can run as many times as you want, without spending any additional reasoning on orchestration.
This is what reharness does — a reasoning compiler. It is open source, published on npm and installs with one command — at the end of the post I will show how to try everything in a couple of minutes, but first let’s see how it works.
Let me defend my right to use the word “compiler” for reharness. For this I will use two ideas.
First, a compiler takes something expensive to interpret and makes it cheap to execute. A JIT analyzes the program execution, finds the hot paths and compiles them into machine code — so it stops re-interpreting them on every pass. reharness does essentially the same. The hot path is the model’s reasoning, which the agent repeats every time it faces the same class of tasks. The machine code is a finite state machine. Here the analogy works on the level of intuition.
To explain the second idea, we need to recall a rather beautiful trick from the distant 1971 — the first Futamura projection. Let’s start with partial evaluation: if a part of the program’s input is fixed, you can hardcode it inside. For example, for pow(x, n) with fixed n=3, we can do an in-place substitution pow(x, 3) = x * x * x. Now take an interpreter — it’s also a program, it just receives another program as input. And if we specialize the interpreter with respect to one concrete program, we get a standalone artifact that does the same as the original program, but without the interpretation overhead. Futamura’s observation here was that the essence of specializing on a program is exactly compilation.
Now let’s draw the analogies between classic compiler theory and modern agentic systems. The agentic loop — think, call a function, look at the result, think again — is an interpreter. A concrete request, or a trace of a task solved once, is a program. And if you clean out everything that depends on the concrete run, what remains is a deterministic pipeline. So “compiling reasoning” is the same formal move, just one level higher up the stack. This way, I allow myself the word.
Now let’s look at the economics of compiling reasoning. The compilation itself costs real money, because you need to spend reasoning to build the deterministic pipeline. As for the runtime, let’s look at the limit cases. If the task is fully mechanical, the compiler pulls everything into code and the pipeline doesn’t call the model at all. If the task is purely creative, the compiler will build for it a machine with one agent state, and the number of spent tokens will be the same as before compilation. Everything between these two cases is the most interesting part — tasks that are hard to turn into pure code, but where the amount of reasoning can be reduced a lot. As we can see, by construction, after compilation the cost of every new run at least doesn’t grow, and often becomes lower.
And the nicest thing here is that compilers are a well-researched area with a known anatomy, which we now can use. There is a target language (the deterministic FSM runtime). There is an intermediate representation (skeleton.xml — the single artifact that all the passes work on). There is a static analyzer that checks the correctness of the built machine. There is a pipeline from the source language to the executable code — with a multi-language frontend, exactly one creative pass, and everything else deterministic. And there is a profile-guided optimization loop from real runs, which gcc doesn’t have, but every grown-up JIT does.
Let’s walk the whole system in the order it is actually designed — from the target up. Because the promises of a compiler are based on the guarantees of the target.
The runtime itself appeared before any attempts to formalize it strictly, and it was naive. Since then it grew up and became formal, and its formal name is a mouthful: a deterministic hierarchical Moore-action transducer with run-to-completion semantics. Sounds scary, but the name is a specification, where every word corresponds to some design decision. So let’s unpack it word by word, and for each one understand what problems it saves us from.
…transducer is simply an automaton with output: not a textbook recognizer that answers “accept / reject”, but a machine that does work while it moves. Formally the pipeline is a six-tuple (Q, q₀, F, Σ, δ, λ): states, the start one, the terminal ones (each marked success or error), the alphabet of events, the transition function δ and the action function λ. All the useful work — agent calls, code, artifacts — lives in λ. And all the other words of the name are restrictions on how δ and λ are allowed to behave.
Moore-action means that the action is tied to the state — and only to it. Each state runs its action to the end and emits exactly one event — the result of its own computation, not a reaction to something arriving from outside. Thanks to this we can answer the question “who did that?”, because all the computations happen only in the nodes and never on the transitions between them. Want to understand what a state does — read it, there is nowhere else to look.
…with run-to-completion semantics means that the machine fully finishes the state’s action and only after that thinks about transitions. No event queues, no preemption — strictly one event per step. There is only one allowed source of external signals — the wait state (timer, file, shell, webhook), and it is an explicit state type, not a side door. This allows to always understand at which stage of computation the machine is right now, because a run is a sequence of finished computations, not a pile of half-done actions.
Deterministic is the most loaded word, it saves us from several problems at once.
First, δ resolves an event by taking the first transition with a true guard, in written order. UML, as we know, doesn’t define the order of guards — we nail it down. So the situation “this time it somehow went differently” is impossible for the same scalars — the route will always be the same.
Second, we forbid the machine to hang silently. For any reachable pair (state, event), either a transition is defined, or the machine stops with an explicit error pointing at the problem — an unhandled event, no guard matched, a switch with no suitable branch. And the fail path first persists the machine state and then dies: even a failure leaves a resumable run behind. This, by the way, forbids skipping the verification steps — paths around the checks just don’t exist in the graph.
Third, guards execute at the transition points, when no stage is active, and they can read only the scalar bus — small values in memory: flags, counters. Try to do something with the file workspace inside a guard — and the machine will fail loudly. Thanks to this, the whole configuration of the machine is a pair (current state, dictionary of scalars). So restoring an interrupted machine is trivial — you saved this pair, and then you restored it. This also simplifies the static analysis: to trace the transitions, the analyzer needs to model a handful of scalars, not a file system.
But it’s worth noting that while the machine itself is deterministic, the agent state stays stochastic inside, because it’s an actual LLM call. But with fixed outputs of the agent states — the full run of the machine is reproducible. Splitting the task into a deterministic skeleton and stochastic reasoning only where you can’t avoid it — this is basically the product.
Hierarchical means that a state can be not only a leaf but also a composite: parallel — fork/join over an array, loop — bounded iteration, call — invoking another compiled pipeline. A composite executes by recursion as an RTC computation, it doesn’t break any of our machine’s restrictions.
Infinite loops are forbidden by design: for loop the maximum number of iterations is mandatory, though an early exit by a corresponding predicate is also allowed. The reason is simple: if the exit predicate is written by a stochastic LLM, you can easily end up in a situation where the loop diverges — we strictly forbid this.
As for parallel, the parallelism is real only where it actually matters: for agent states the parallelism is implemented at the level of OS processes. Each branch gets its own copy of the bus, which excludes the race for shared data; the branches communicate through isolated output directories, which the join then reads as a list.
And now if we return to the name of our runtime, it stops being scary and turns out simple and logical:
The poverty of the target is not a bug, it’s a feature. We deliberately restricted the machine to the necessary minimum to get checkable guarantees.
Our runtime is a processor that executes programs. The programming language for this processor is the intermediate representation of the machine in XML format. The DSL consists of 12 state types (agent, interactive, code, set, switch, check, parallel, loop, wait, call, approval, final), which the runtime collapses to eight constructs — the first four are one active state with different actions, check is sugar over switch.
Here is an example program describing a multi-model code review:
<skeleton id="multi-review" initial="ingest">
<usage>multi-review <repo></usage>
<inputs>
<arg name="repo" positional="true" required="true"/>
<arg name="models" type="list" default="claude-sonnet,claude-opus"/>
</inputs>
<state name="ingest" type="code">
<contract><![CDATA[Collect the diff of config.repo into c.out()/diff.patch;
set c.data.empty = true if there are no changes.]]></contract>
<on event="DONE" target="has_changes"/>
</state>
<state name="has_changes" type="check" expr="data.empty">
<on event="TRUE" target="ok"/>
<on event="FALSE" target="review"/>
</state>
<state name="review" type="parallel" over="config.models" branch="reviewer" concurrency="4">
<on event="DONE" target="gate"/>
</state>
<state name="reviewer" type="agent">
<contract><![CDATA[Read the diff from the input directory, write findings.md
with a list of findings (severity: blocking | advice).]]></contract>
</state>
<state name="gate" type="code">
<contract><![CDATA[Read c.dirs('reviewer') - one directory per model - merge
findings into c.out()/report.md, count blocking ones into c.data.blocking.]]></contract>
<on event="DONE" target="route"/>
</state>
<state name="route" type="switch">
<go guard="expr:data.blocking > 0" target="bad"/>
<go target="ok"/>
</state>
<state name="ok" type="final" status="success"/>
<state name="bad" type="final" status="error"/>
</skeleton>
Every working state has a short <contract> — this is the only place that stores the intent of the node. The reviewer state is an example of the parallel composite: it runs once for each model, and then control returns to the parent. The gate → route pair exists because of our machine’s restriction that agents can’t touch the scalars, so there is always a small code bridge for choosing the direction, which reads the files and puts one number on the bus.
If you look at the code carefully, you won’t find a single file path there. The reason is not that I simplified the example — the language has no such constructs. In the whole IR there is only one declaration — <inputs>, which defines the external arguments that are impossible to derive from the graph. From <inputs> the codegen generates the argument parser, and a static check requires that every argument the pipeline reads is declared. Implicit declaration of global variables is forbidden. Everything else is derived from the graph.
One more deliberate poverty of the target is the guard language, which is not Turing-complete on purpose. It allows only identifiers over config.* / data.* / retries.*, comparisons, boolean logic, arithmetic and literals — no function calls, no assignments, no ternary. A guard must be a cheap, total, statically checkable expression over scalars, and the grammar is simply not able to express anything else. Routing inside the machine is a function of scalars, and the guard grammar makes violating this requirement impossible.
You may object: the stages obviously pass data to each other (diffs, reports, build artifacts, etc.). Who declares what flows where? Nobody. And this is not a hole in the language — this is my favorite part of the whole system.
Working on the compiler, at first I tried the obvious ideas. And the most obvious one here is to make the model somehow understand the data flow inside the graph and annotate it on its own. All the attempts failed for a simple reason: the model’s opinion on this question is a second source of truth about the graph, and there is no guarantee it won’t diverge from the real graph. To be honest, in my experiments it diverged almost always, which led to generating a broken machine. Things were especially bad with loops and parallel branches.
The important insight for solving this problem was that a graph edge already is a contract by itself. If stage B is reachable from stage A, then the output of A is by definition available to B. So the most reliable solution turned out to be deriving the visibility from the topology: the producers visible to a node are its ancestors, and there is nothing more to invent here.
One important question remains, which is easy to miss and run into bugs: how many instances of the producer’s output does the reader see? In compiler theory there is an instance-wise rule for this, in the spirit of the polyhedral model. The same classic that is used in loop optimizers for resolving array accesses in loop nests. If you ever wrote results[i][j] inside two nested loops — you have all the necessary theory: a thing that executes inside loops is addressed by its loop indices. For us it’s all the same: every state has an iteration space — the chain of composites enclosing it, from the outer to the inner. An instance of a state is addressed by an instance vector: one index per enclosing composite (which parallel branch, which loop iteration). For a top-level stage this vector is empty — there is one of it.
The cardinality rule then fits in one sentence, verbatim from the code:
Producer
Pis visible to readerNas a collection ⇔P’s chain is longer than the common prefix of the two chains. Otherwise — as a single instance.
All of this is easy to understand on our review example. As long as reviewer works in its own process, it sees its own copy of the bus and its own working directory, and it doesn’t see the neighbors — the question “which instance?” is resolved trivially for it: for example, there is exactly one ingest for it. But gate runs already outside the parallel, and from its point of view reviewer is not one result, but one per each parallel branch. From here the simple rule: from inside we read one branch (c.dir), from outside — a list (c.dirs). For loops it unrolls the same way. Even the tricky case “the actor reads the critic from the previous iteration” resolves by itself: the runtime gives the latest existing instance. In compiler theory this analysis is called instance-wise dataflow — the classic theory of array accesses, which fit the agentic pipeline like it was made for it.
And physically it’s all almost disappointingly simple: every output directory is named by the full instance vector — work/<stage>/<i0>/<i1>/…. The producer’s write, the branch bookkeeping and the consumer’s read are computed from the same pair (stage, vector). They can’t diverge — there is nothing for them to diverge about.
So in total the data travels over three channels:
<inputs>.We have the runtime, we have the IR to program it, the last important step before building the generator is static analysis. We must be able to tell AI slop from correctly working programs. For this we will again turn to compiler theory, instead of writing our own bicycles whose robustness I really don’t want to prove myself. In reharness there are just two lightweight engines for static analysis, together they take 78 lines of code.
The first engine checks the reachability of states in the graph using breadth-first search, nothing much to discuss here.
The second engine is more tricky, and it’s easiest to understand on our same review example. gate writes the scalar data.blocking, and route reads it. What we want to know here: is this scalar actually written on all the paths leading into route? Because the graph was drawn by a model — and if it created a path around gate, then on that path route will read something that doesn’t exist.
We could do a full enumeration over all the paths for this, but computationally it’s hard, and besides, a more beautiful solution was already invented for this. The trick is this: instead of paths, we compute for every node the set “what is guaranteed to be written by the moment we arrived here”. There are just two rules: a node that writes a scalar adds it to its set, and where several branches merge, we take the intersection of what arrived along them — only what is guaranteed on every branch stays guaranteed. If the question is not “is it guaranteed” but “is it possible on at least some path”, everything works the same but with the union — this is exactly how “whose outputs are visible to a node” from the previous section is computed. Loops remain, but they are also simple: we walk the graph again and again until the sets stop changing, and they can’t grow forever — there is a finite number of scalars, so the stop is guaranteed.
That’s the whole engine: in the textbooks it’s called the Kam–Ullman monotone dataflow framework, where the version with intersection is the MUST analysis, the version with union is the MAY analysis, and “the sets can’t grow forever” is its convergence theorem. The whole machinery is two lines:
IN[n] = merge of OUT[p] over all predecessors p (entry: IN = ∅)
OUT[n] = IN[n] ∪ gen(n)
Every check in reharness is a thin instance on top of these two engines:
| check | what it is, formally |
|---|---|
| every state is reachable from start | forward reachability |
| every state can reach a final (no dead ends) | backward reachability from the finals |
| no scalar is read before it’s written | forward MUST dataflow = definite assignment |
| visible producers and their cardinality | MAY reachability + the common-prefix rule |
Look at the bottom row of the table: deriving the data wiring and checking it is one and the same analysis, not two pieces of code that have to negotiate with each other. And a second trick of the same kind: the question “where does a state lead?” is answered in the whole system by one function — successors, and it is used by the reachability check, the data analysis and the codegen. Three consumers look at the graph with the same eyes — and the whole class of bugs “the validator assumed one thing, the codegen did another” disappears by construction.
So, piece by piece our compiler is almost ready, what’s left is to tie everything together. And here is a fun thing: the compiler is a reharness pipeline, a machine running on its own runtime. This proves that the target language is expressive enough.
The machine itself looks like this:
research → prd → [review_prd: approval] → design → construct → fill → check_dataflow → polish → verify → done
verify FAIL → fix_verify (≤2) → verify
polish escalate → redesign (rare)
The frontend is multi-language — like gcc, which compiles C, C++ and Fortran into one IR. There are three source languages: a request in natural language; an amendment (amend) — folding a new feature into the existing PRD as an intent delta, keeping the already filled leaves; and a recorded trace — the log of a task solved once. All three converge on the PRD: a short document about what should be built.
Of the three source languages, the trace deserves a separate pause — it’s the most unusual one. A recorded session is a demonstration, and turning a demonstration into a reusable program is programming by demonstration: generalization from one example. The generalization here is explanation-based, and the recipe is exactly what it sounds like: explain why the trajectory reached the goal, keep the weakest preconditions that this explanation needs, and throw away everything specific to the run. The concrete repository becomes a parameter, dead ends and wandering are discarded, and what survives is the structure — and it is exactly the thing worth compiling. Two properties make this robust in practice. First, the trace is grounded before generalization, and the priority order matters: what the trace actually shows (the real call, the real response) beats the documentation, the documentation beats the web, and the web beats the model’s memory. Second, the whole construction is format-agnostic by design: the session is read raw — JSONL, markdown export, a pasted chat, doesn’t matter — because the universal parser here is the model itself, and you need no per-vendor adapters and no lock-in to anyone’s log format.
Next comes the only human gate, placed exactly where it’s cheap. The human approves the PRD — the intent, never the structure. It’s worth spelling out the asymmetry here: validating intent is cheap, and people are good at it; reviewing a generated state graph for semantic correctness is expensive, and people are, let’s be honest, bad at it. So the gate stands on the only truly catastrophic failure — “built the wrong thing entirely” — and everything downstream belongs to the compiler. A demonstration, by the way, buys no special trust: traces go through the same gate.
There is exactly one creative pass — design. It emits the only thing that really requires a model: the topology graph plus a behavioral contract per node — that same IR. And it self-corrects in a hot context: design runs under RPC, and after every turn the runtime re-prompts it with the errors from the analysis library, until the IR comes out clean. Essentially these are semantic compile errors returned to the author — it’s just that the author here is a model, and it fixes them without leaving the room.
Everything below design is deterministic. construct is the lowering: codegen from IR into TypeScript, stubs for the agent prompts, the argument parser from <inputs>. fill writes the leaf implementations against their contracts — the only LLM work below design, and strictly local: a leaf sees its contract, not the graph. check_dataflow runs the definite assignment. polish is one review pass of the whole pipeline against the PRD, editing only the leaves; deliberately not a review→fix→re-review loop — the loop was expensive and bought nothing. verify is the objective backstop: type compilation plus structural checks; a failure goes to a bounded fix_verify (two rounds maximum), which edits only the implementations.
And the final check is done by execution, not by faith. The result of compilation is an executable graph, which means it can be dry-run with the model leaves stubbed out: zero tokens, while the control flow, the guards and the derived wiring actually walk all the way to a terminal. Don’t trust that it “compiled” — watch how it runs. And on real runs the cost is observed, not estimated: every agent leaf reports its actual spend, the runtime sums it into the verdict. A fully amortized pipeline prints 0 agent runs · 0 tokens · $0.0000. The central claim of this post is falsifiable with one line of output — any day.
One organ remains — the one that AOT compilers don’t have, but grown-up JITs do: profile-guided optimization. A compiled pipeline keeps improving from its own runs; it’s just that the profile is not branch counters, but agent traces. The precise name for this is speedup learning, a relative of explanation-based generalization, at the granularity of a sub-routine.
Every run leaves a verdict behind, and on failure the repair step reads the trace, finds the root cause and fixes the offending leaf, without touching the node’s contract — it escalates to a graph change only if the fix doesn’t fit into a leaf. After the repair the pipeline is re-verified and re-run on the original arguments: “fixed” is confirmed by execution, not by faith — the same principle that verify lives by, the system is consistent in its epistemology.
On success the system walks the agent leaves: it refines the attached skills, if the trace showed that a skill lied, and it hunts for a repeating deterministic sub-routine that the agent reinvents by hand on every run — to freeze it into a callable tool.
And here the eighties have a warning prepared for us, called the utility problem: if you cache everything you learned, you become slower — every cached item itself costs context and selection time. The field burned itself on this decades before LLMs made it expensive also in dollars. So a frozen tool passes two gates: acquisition — it is correct by construction (parses, passes its self-test, respects the sandbox) — and retention — it keeps its place only while the call frequency justifies it. If nobody calls it — the tool gets unbound and goes to the archive, and this way the system learns what pays off and unlearns what didn’t.
If you step back, you can see the ring that closes here: the runtime executes what the pipeline built, and produces traces. The traces feed the frontend — compiling a demonstration is, after all, compiling someone’s trace — and they feed the optimizer, which improves the pipeline from its own runs. The same artifact ends up both on the input and on the output, and for a reasoning compiler this is not a coincidence: reasoning is its raw material.
So, the compiler exists — but what to compile with it? The ladder of applications starts on your own desk and ends, surprisingly, in the enterprise.
Rung one: your own routine. Everything you do with an agent regularly is a candidate for compilation. Mail digests, log triage, weekly reports, dependency checks, changelogs: a recurring task compiles once for a couple of dollars and then runs on cron for months. The sweet spot is exactly the repetition: a one-off task doesn’t justify the compilation, a live agent is cheaper; but everything you run at least weekly amortizes the compilation within a couple of runs. And if the task is mechanical, the pipeline doesn’t call the model at all — I have compiled commands that haven’t spent a single token since the compilation day, and they are doing fine. The cheapest agent is the one that never calls the model.
Rung two: compiling traces — including other people’s. This is where it gets interesting, because the source language stops being your head. Solve a task with a live agent once, take the trace, compile it — and nobody solves this task from scratch anymore. In a team it looks like this: the most experienced engineer shows once how to deploy, review or migrate properly — and his session becomes a tool that everyone runs. A demo instead of a spec, and no broken telephone. And since HuggingFace started putting agent traces right on the Hub, you can compile other people’s demonstrations too: I ran reharness on open trace datasets — someone else’s session turns into your working pipeline. The more open traces exist, the more ready-made programs lie in the commons — for now, in unassembled form.
Rung three: a backend for assistants. Conversational harnesses of the OpenClaw/Hermes class are great at dialogue and judgment — and they pay tokens for every run of the routine they grind daily. The industry already considers it normal that an agentic task burns 10-100x more tokens than a direct model call — and the lion’s share of this multiplier goes not to judgment, but to re-interpreting the same structure: what’s next, did I check, what was there last time. Plug the compiler in as a backend — and the assistant keeps the conversation and the judgment, while the recognized routine drives off into a compiled pipeline at ~$0. This hits hardest for small local models: their token budget is tight as it is, and burning it on orchestration is exactly the waste this whole series started from.
Rung four: the enterprise, surprisingly. The main brake on agents in serious organizations is not the price, it’s the nondeterminism. The auditor needs “which rule fired and why”; the agent reasons differently on every run; compliance reaches for the cigarettes. A compiled pipeline cuts this knot: the agent’s flexibility stays at compile time, and the execution gets the auditability of the good old RPA — deterministic transitions, a full trace of every run, observed cost, byte-for-byte reproducibility on the mechanical parts, and exactly one labeled node where the judgment happened. The classic automation cases — invoice processing, ticket triage — are exactly high volume plus one recurring decision: one agent leaf in a deterministic skeleton, straight from the textbook.
Four rungs, one product: a recurring task stops paying for reasoning on every run. Big models made us lazy — “the model will figure it out” — and we pay for this figuring-out again and again. A compiler is a refusal to pay twice.
And the part that still makes me smile: the foundation for all of this was found not in fresh papers about agents, but in compiler theory that is decades old. Futamura, Moore machines, polyhedral analysis, Kam–Ullman fixpoints — it all was lying on the shelf, waiting for a domain that didn’t exist when it was written. The machine I used to write by hand for every task, the compiler now derives on its own.
npm install -g reharness
# compile a pipeline from a request
reharness compile "code review FSM for this project"
# or from a recorded session
reharness compile --from-session ./session.jsonl
# dry-run: the whole graph, stubs instead of agents, zero tokens
reharness <command> --dry-run
# run it for real
reharness <command> args
For the agent leaves you need at least one backend on PATH: Pi (the default) or Claude Code (--provider claude — the agents run on a subscription instead of per-token billing). A compiled pipeline is just a regular reharness/ directory in your project: read it, version it, carry it with you.
Apache 2.0: github.com/bes-dev/reharness · npm: npmjs.com/package/reharness
]]>T+0.0. ALT 10. VEL 0. GAM 90.0. Vertical launch. Cape Canaveral, Pad 39. Computer: not a UNIVAC 1100.
“I have not been able to get the test case from the report working yet.”
Ralph Carmichael, author of PDAS – the largest public archive of aerospace software. Program MSC-13914 is listed on his site as “work in progress.” Since 2009. Seventeen years.
The program was written in 1970. In FORTRAN IV. For a UNIVAC 1100 computer that hasn’t existed for half a century. Documentation – four volumes, 700 pages, test data preserved only in illegible dot-matrix printer scans. Nobody has been able to run it.
In 2024, NASA published the COSMIC archive – a catalog of software the agency distributed through the University of Georgia from the 1960s through the 1990s. Hundreds of programs for computing orbits, aerodynamics, structural loads. Most in FORTRAN, targeting long-vanished machines.
Among them – MSC-13914. Space Shuttle Synthesis Program. Developed by General Dynamics in 1970 under contract NAS9-11193 for the Manned Spacecraft Center in Houston. 7,811 lines of FORTRAN IV. Automates trajectory, weight, and performance calculations for a two-stage Space Shuttle system.
I found it as a single text file. 608 kilobytes. ELT format – a punch card image for the UNIVAC 1100 loader. No Makefile, no readable documentation. Just code.
Remarkably, after nearly sixty years, getting the program to run on a modern computer required no major surgery. Ten fixes total. None touching logic – only half-century-old syntax. IFIX() instead of INT(). ALOG() instead of LOG(). A PUNCH statement for card output. A typo in the original: HARTBL87) instead of HARTBL(7). UNIVAC loader directives that have nothing to do with FORTRAN.
gfortran -ffixed-form -std=legacy -fno-automatic -o sssp sssp_fixed.f
It compiles. 2026, Apple Silicon, macOS.
But -fno-automatic isn’t cosmetic. It’s the key to everything. Original FORTRAN IV on UNIVAC stored local variables statically. Subroutine STORE saved orbiter data through entry point ORBSTO and restored it through ORBCAL – a different entry point in the same subroutine. Without -fno-automatic, gfortran puts local variables on the stack, and data evaporates between calls. The program compiles, runs, and produces garbage. A silent, insidious bug that Ralph Carmichael probably never found.
First quest cleared. The program builds. But running it requires input data – 300 weight coefficients, aerodynamic tables, a pitch schedule.
The original test case exists – in Appendix VII of NASA CR-114985. I found the PDF. Opened it. Scanned pages. Dot-matrix printouts. Every page marked: “REPRODUCIBILITY OF THE ORIGINAL PAGE IS POOR.” Digits blur together. 3 is indistinguishable from 8.
But even if the scans were legible – the 1970 test case doesn’t describe the real Shuttle. It’s a General Dynamics concept: a fully reusable two-stage system, both stages winged. Nothing in common with what actually flew in 1981.
If we can’t read the old data – we’ll create new data. For the real Shuttle.
We have a program that can calculate weights and trajectories of spacecraft. But it has 300 tuning coefficients and not a single known value.
What we do have are answers. Not the coefficients – but what the right coefficients produce.
Orbiter dry weight: 151,000 pounds. Wikipedia. Wing weight: 16,200 pounds. NASA weight statements. Thermal protection: 18,895 pounds. Wikipedia. RS-25 engines: 7,004 pounds each, 512,300 pounds vacuum thrust, ISP 452.3 seconds. Wikipedia. Solid rocket boosters: 1,100,000 pounds of propellant, 123 seconds burn time. Wikipedia. Launch pad LC-39 coordinates: 28.608 N, 80.604 W. Google Maps.
Data from an encyclopedia and fact sheets. Rounded. Averaged across missions. But sufficient.
The classic approach to reviving such code: read the documentation, understand the meaning of each of the 300 coefficients, tune them by hand. For a program with illegible documentation and a half-century gap in context – a dead end.
A different approach: reverse engineering. We know the answer – wing weight equals 16,200 pounds. We know the formula inside SSSP: WWING = C(1) * f(geometry) + C(2) * area + C(3). We need to find C(1), C(2), C(3) such that the formula gives the right answer.
Not for one component – for all of them simultaneously. 14 target categories: wing, fuselage, thermal protection, landing gear, engines, hydraulics, electrical, avionics, orientation control, crew, payload. Each category – a number from Wikipedia. Each depends on several C() coefficients. The coefficients are coupled: changing C(15) (fuselage structure) affects total weight, which affects required propellant, which affects tank volume, which affects body surface area, which affects thermal protection.
A nonlinear system with cross-dependencies. Manual tuning is impossible – changing one coefficient shifts ten others.
Solution: scipy.optimize.minimize, Nelder-Mead method. The objective function is the sum of squared relative errors across all 14 categories. At each iteration of the optimizer:
SSSP-in-the-loop. A 1970 Fortran program as a black box inside a 2026 Python optimizer. Each call – 2 seconds. 429 calls. Five minutes.
The same method – for the trajectory. Different target points: altitude, velocity, and flight path angle at T+60, T+90, T+120, T+200, T+300 seconds – from STS mission data. Different parameters: average SRB thrust, specific impulse, liftoff weight. Same loop: generate input, run SSSP, parse trajectory, compare against targets, minimize error.
And for aerodynamics – the same method. Drag coefficient scale as a parameter, target points – altitude and flight path angle from real flight reconstructions.
Three optimizers. One principle: don’t guess parameters – fit them to known answers.
A critical question: did we simply rig the numbers to produce a pretty result? Did we create an unphysical vehicle that exists only in the optimizer’s parameter space?
Every coefficient found maps to real components.
C(15) = 39,448 pounds – “basic fuselage structure.” This isn’t a magic number. It’s forward fuselage (10,800) + mid fuselage (8,000) + aft fuselage (8,000) + payload bay doors (4,600) + secondary structure (8,048). A sum of real components, each known from NASA weight statements.
C(180) = 1.44 pounds per square foot – thermal protection insulation unit weight. Real HRSI tiles: 1.5 lb/ft2. LRSI: 0.8. RCC on the nose and leading edges: 4.0. Our value is a weighted average. An engineer designing thermal protection would arrive at a similar number.
Average SRB thrust: 2,814,000 pounds. Real peak: 3,300,000, at liftoff: 2,700,000. Our value falls between them. For a constant-thrust model, this is the only physically correct approximation.
Aerodynamics: the optimizer returned CD_SCALE = 1.0. It didn’t touch the drag coefficients. Open-source data used as-is. Transonic drag rise of 2.2x – within the 2.0-2.5x range typical of launch vehicles.
The optimizer didn’t create an unphysical vehicle. It found the Shuttle in parameter space. Every coefficient is explainable. Every one falls within real engineering ranges. An aerospace engineer looking at these numbers would recognize the configuration.
This isn’t overfitting. It’s calibration.
The weight model is statics. Dynamics is where it gets interesting.
SSSP contains a complete trajectory module: three-dimensional equations of motion over a rotating oblate Earth with J2-J4 gravity harmonics. A fifth-order Runge-Kutta-Butcher integrator with adaptive step control – 245 lines, double precision for intermediate values (a luxury in 1970). Bilinear interpolation of aero coefficients by Mach number and angle of attack. Cape Kennedy Reference Atmosphere 1963 – 193 data points from sea level to 2.3 million feet. A propulsion model with ten operating modes.
All of it – original 1970 code. Not a single formula changed.
Getting it to work was its own adventure: dozens of undocumented flags, each silently disabling an entire module if not set correctly. Defaults in subroutine TRAJC that overwrite input parameters after they’re read. A singularity at zero velocity. But that’s engineering archaeology, of interest mainly to specialists. Details are in the EXPERIMENT_LOG on GitHub.
The result: aerodynamics from open data (11 points of axial force coefficient vs Mach), atmosphere from BLOCK DATA, pitch schedule from published I-load profiles of the real Shuttle – alpha=-2 degrees at max-Q, alpha=-4 degrees post max-Q, alpha=+3.5 degrees during second stage. All loaded through standard $DATA1 input blocks, using the original ALPC=22 mode – one of 31 attitude control modes built into the program.
T+0. Vertical launch. Three SSMEs and two SRBs. Liftoff mass 4,575,000 pounds.
T+60. Max-Q. Altitude 13.5 km. Velocity 549 m/s. Flight path angle 53 degrees. Gravity turn.
T+123. SRB separation. Altitude 50 km. Velocity 1,895 m/s. Boosters jettisoned – mass drops by 400,000 pounds in an instant.
T+300. Altitude 115 km. Velocity 5,205 m/s. Flight path angle 0 degrees. Horizontal flight. No atmosphere left – drag is zero.
T+389. MECO. Main Engine Cut-Off. Velocity 7,803 m/s. Orbital. Engines silent.
T+500. Altitude 109 km. Velocity 7,803 m/s. Flight path angle 0.4 degrees. Orbital coast. Stable.
SSSP has no built-in MECO – the 1970 program assumed engines burn until propellant depletion. Without MECO, the rocket accelerates to twice orbital velocity, and the program reports “VEHICLE ATTEMPTED SUBTERRANEAN FLIGHT.” Five lines in subroutine PRPSN: if velocity exceeds orbital – thrust equals zero.
Gravity turn: GAM=75.6 degrees at T+30s versus 75.0 real. Half a percent error.
Velocity at T+200s: 9,843 m/s versus 10,000 real. 1.6% error.
MECO altitude: 109 km versus 115 km real. 5% error.
The discrepancies are explainable from two sides.
On our side – SSSP doesn’t model SSME throttle-down through max-Q (the real Shuttle reduces thrust to 67%; we hold 100%). Doesn’t model closed-loop PEG guidance – the real Shuttle computes thrust direction in real time; we use a fixed alpha(Mach) table. Doesn’t model wind loads, roll program, yaw steering.
But there’s another side. Our “real data” are numbers from Wikipedia and NASA press kits. Rounded. Averaged across 135 missions, each flying with its own payload mass, in its own weather, to its own orbit. SRB separation altitude varied from 150,000 to 174,000 feet between missions – a 15% spread. Some of our target points (T+200s, T+300s) are interpolations, not measurements from a specific flight. We couldn’t find detailed per-second telemetry from real missions in the public domain.
We’re comparing an approximate model against approximate data. The 5-15% error isn’t just a limitation of SSSP. It’s also the uncertainty of the targets themselves.
For a predesign tool – that’s enough. It answers the question “will this configuration work?” And it answers correctly.
The experiment started as curiosity – code from a NASA archive, illegible scans, a forgotten tool. It ended with a working simulation of a real spacecraft’s flight.
The Space Shuttle program ended in 2011. 135 missions. The technology that defined an era of crewed spaceflight. The Artemis program is preparing a return to the Moon – SLS uses the same modified RS-25 engines and 5-segment SRBs.
And program MSC-13914, written 11 years before Columbia’s first flight, can still calculate its trajectory. On a laptop. In 10 seconds.
In subroutine SOLVE, line 6439, there’s a construct IF(0) 5005,10,5005 – an arithmetic IF that always branches to label 10. The developer’s comment: “THIS CARD NECESSARY TO PROGRAM AROUND COMPILER OPTIMIZATION BUG ON UNIVAC 1108 EXEC II.” A workaround for a 1970 compiler bug. Still works in gfortran 2026. We didn’t touch it.
7,811 lines. 44 subroutines. 10 fixes to compile. Three optimizers for calibration. One make run to launch.
Video: youtu.be/aavo1POfrZg
Code: github.com/bes-dev/sssp
]]>/build habtrack "Habit tracker with daily check-ins, streak counting, weekly bar chart...".
52 minutes. No cloud providers. No API keys. Just a 27-billion-parameter model running right on my laptop.
I didn’t babysit the process. Didn’t fix bugs in a chat window. Didn’t yell at the model in all caps for building the wrong thing. Fired off one command, switched to another task, checked back an hour later — the app was ready to test. Before that, an RSS reader: one hour. Before that, a calculator: 37 minutes.
Three apps in one evening. Zero hands-on. Not a single dollar spent on tokens. And the model is the least interesting part of this story.
For the past few months I’ve been experimenting with an autonomous AI publisher for mobile apps. Etnamute is one of the intermediate iterations, released as an open source agent built on Claude Code — 4,500 lines of instructions on how to build mobile applications. A single run takes anywhere from thirty minutes to two hours — a full cycle from idea to a finished cross-platform React Native app.
It works. But it’s a hired hand. We pay Anthropic for access to the models that serve as the agent’s brain. And the company can raise prices at any moment, decide that my use case violates their ToS, or the service can go down under load at the exact moment I need to run the agent. And my employee vanishes. Can’t do the job. Not because it was poorly built. Because I don’t own it.
When Qwen3.6-27B dropped (a fresh open source model from Alibaba) and Anthropic’s servers went down under load yet again, I started wondering: can I move this entire machinery onto hardware sitting right on my desk? A model whose weights live on my hard drive. Local inference on my machine. Zero dependencies on external providers or APIs.
No, you can’t move it. But you can reinvent it.
The very first idea — just take the existing Etnamute and feed it to Qwen3.6-27B.
Fired up the model in opencode. Typed /build-app feedwise "RSS reader with support for major feed formats. Dark theme.". Nothing.
The model went into deep meditation. Not metaphorically — it literally stopped responding, lost in reasoning chains that burned through the entire 128K token context before writing a single line of code.
The problem isn’t that the model couldn’t understand the instructions (a 27B model is perfectly capable of understanding what’s in Etnamute) — it’s the cascade effect: many rules spawn complex reasoning chains, and reasoning chains devour context and available compute.
The brute-force approach doesn’t work. But even if it did, there’s the controllability problem. OpenCode with oh-my-opencode plugins is a big system with its own logic. MCP servers, background sub-agents, hooks that modify model behavior on top of my prompts, a long system prompt. I had no control over what exactly happens between “I asked” and “the model did.” A black box inside a black box.
I didn’t need a Swiss Army knife with a million modes. I needed a system where I control every layer. I switched to Pi — a minimalist CLI agent. Four tools: read, write, edit, bash. System prompt — under a thousand tokens. Nothing else. A thin layer between my instructions and the LLM that lets me understand and control everything from prompt input to final output.
Michelangelo said the sculpture is already inside the stone — you just need to remove the excess marble. Turned out the same was true for Etnamute’s instructions. Not adapting 4,500 lines, but finding within them those without which a correct app cannot be built. Each rule — one question: what breaks if you remove it?
User interview: cut. The model can generate a spec directly from the user’s prompt. Market research: cut. RevenueCat integration: cut. None of that is needed for an MVP. E2E testing with visual analysis: painful, but cut too. Replaced with a shell script running grep checks and a smoke test for runtime errors. Instead of NativeWind, which gave the 27B model serious trouble, we use React Native Paper — Material Design out of the box. Three-level feature priorities — MUST, SHOULD, WONT: cut the middle tier. The gray zone for a small model means stubs, not implementations.
Total: 935 lines. Five thousand tokens. Five percent of the context window instead of “context exhausted.”
With a big model you think about what else to add. With a small one: what else to cut.
The compressed prompt worked. First test — 13 hours generating an RSS reader, ending with a white screen on launch. NativeWind, which I hadn’t cut yet, was silently crashing the renderer. DOMParser, which doesn’t exist in Hermes, was dropping the app on the first feed addition. Second run after accounting for these — 2 hours, works immediately. Third — a working pomodoro timer, a different class of app with its own set of problems. Then — a calculator, then — a habit tracker with charts.
Each run isn’t just a test of the model. It’s a test of the environment. An app breaks not because the model is dumb — but because the environment didn’t warn about potential problems. White screen from NativeWind — a line “use React Native Paper” in the prompt. DOMParser — have the model use fast-xml-parser instead. Buttons in a column — a flex grid layout template. Each bug isn’t an app fix, isn’t a long debugging session with ALL CAPS in the chat. No. We fix the harness. Apps are disposable. The harness is cumulative.
But this isn’t vibe coding in reverse — not “got an error, shoved a fix into the prompt, repeat until convergence.” Each rule must earn its place in the instructions. If the bug is specific, it means we missed something important in the overall methodology. DOMParser crashes Hermes — that’s not a rule “don’t use DOMParser.” It’s a runtime pitfalls table with ten entries: APIs that compile but don’t exist at runtime. Buttons in a column — that’s not a rule that creates grid layouts. It’s a section explaining how layouts work and the general principles behind them.
The harness isn’t a cookbook of errors and fixes. It’s a description of a methodology that sidesteps entire classes of problems. A specific fix helps with one specific problem. Well-formulated principles close hundreds.
After several runs the prompts stabilized. New generations didn’t produce unique problems — all the pitfalls had been covered not by fixes, but by rules. But for generating complex apps, our approach wasn’t enough.
All this time our harness was a single instruction describing how to properly generate mobile apps.
A monolithic instruction that the Pi agent followed during generation. One single agent.
Everything lived in one context: the spec, reasoning about the plan, package installation logs, TypeScript errors it had already fixed, old file versions it had already rewritten.
In one run the agent burned through 12 million tokens — most of them on repeated npm install attempts with wrong versions.
The context window is a budget. Not a buffer you can dump into endlessly, but a budget that runs out. And in a monolithic architecture it runs out at the most interesting part.
To solve this, I did something the author of Pi considers an anti-pattern: I split the monolith into sub-agents.
Each pipeline step is a separate Pi process with a clean context. The PRD agent sees only the app idea and nothing else. The skeleton agent — only the spec. The logic agent — TypeScript interfaces. The UI agent — types and stores. A few dozen lines of prompt per agent. Each agent sees exactly what it needs to do its job. Nothing more.
Mario is right: parallel agents working in the same layer can generate garbage.
But my agents aren’t parallel. They’re sequential and layered.
Each with its own zone of responsibility: Logic doesn’t touch UI, UI doesn’t touch stores.
The contract between agents — TS interfaces created by the skeleton agent first.
If the UI agent calls a method that doesn’t exist in the store — tsc catches it in a second.
Context passes through the file system. One agent writes a file. The next one reads it. No variables, no shared memory, no intermediate formats. Unix way. Simple debugging.
Sub-agents solved the context problem. But created a control problem.
Launching sub-agents in Pi is done through extensions, and above them sits a parent agent — the main Pi process from which everything is launched. Inside it — an orchestrating model that was supposed to manage the process. In practice, it hijacked it. It would see a sub-agent’s problem and try to solve it itself, through long trial and error. Often it burned millions of tokens on something a shell script could handle in seconds — it just never ran the script.
A parent agent is an LLM that makes decisions about the process. And every such decision costs tokens. And every such decision can be wrong. The model decides “let’s try a different approach” — and gets stuck in an infinite loop. The model can skip pipeline steps, and does. The model refuses to delegate to a sub-agent and breaks everything itself.
I solved this with finite state machines. A deterministic state machine where transitions are defined in advance, conditions are formalized, and terminal states are inevitable.
The model can’t skip verification — there’s no transition bypassing that state. Can’t jump straight to UI development when the app skeleton isn’t ready — that transition is invalid. Can’t endlessly fix code — after several failed attempts, the machine automatically transitions to an error state.
The model doesn’t decide what happens next. The machine decides. The model just executes the current step’s task.
For this I built a small framework — reharness. An FSM engine for orchestrating Pi agents, deterministic functions, and the like.
It’s worth noting that our approach is fundamentally different from what many people have gotten used to as vibe coding.
Vibe coding is when you chat with an agent, ask it to build something, get a result you don’t like, ask it to redo, still wrong, you get frustrated and start writing in ALL CAPS — and every unstructured comment of yours pollutes the context and degrades the quality of the next response. You pay for every iteration. The provider is happy.
Our pipelines are different. You don’t chat with the agent in real time. You design the environment: which prompts, in what order, with what checks, with what transition conditions. Then you set the task. The machine attempts to solve it, operating within the designed environment. You go about your business in the meantime. If something breaks — you fix the environment, not the app. Add a check. Refine a prompt. Run again.
This isn’t “vibes.” This is engineering. Building a vertical that predictably produces results. And the fundamental difference is in scalability. Vibe coding scales linearly: more apps = more of your time in the chat. Pipelines scale differently: every improvement to the environment benefits all future app generations.
Pipeline: scaffold → prd → skeleton → logic → ui → verify ↔ fix → complete. Each step is a pure function of the file system: files in, files out.
No information passes outside this rule. Makes debugging straightforward.
Before anyone writes a single line of implementation, the skeleton agent creates all necessary TypeScript interfaces with JSDoc documentation.
These aren’t TODO stubs — they’re contracts. What each method is expected to do, what its edge cases are, what happens under concurrent calls.
The logic agent implements these contracts, and the UI agent builds screens on top of them. If anyone violates the contract — a simple tsc check catches it immediately.
Why does this matter? The skeleton constrains the solution space. If the model sees an interface with three methods — it will implement those three methods. Give it a blank slate — it implements whatever it sees fit, forgetting half of it along the way and making up the rest. Types are rails for each subsequent agent. This is the core principle of our entire approach: the narrower the corridor, the more precise the movement.
The second pillar is scoping. Each agent sees only what it needs to do its job. The UI agent doesn’t care what problems the logic agent ran into — that’s not its zone of responsibility.
Generating code is only half the job. The other half — figuring out whether it actually works.
In the full Etnamute, a dedicated QA agent handles this — it can launch the app, analyze screenshots, tap buttons simulating user actions, and compare results against expectations. Heavy artillery that even in Etnamute runs slowly but catches bugs with high confidence. On a local 27B model it’s an unaffordable luxury — we don’t have that much compute.
Here we make do with smoke testing: launch the app in a headless simulator and check the logs. If it crashed — we see the stack trace. Didn’t crash — we call it working. Five mechanical checks with zero LLM involvement: tsc, bundle, runtime smoke, stub detection, anti-pattern scanning.
But catching bugs isn’t enough — you need to fix them. And here another contract turned out to be critical — the file verify-report.md.
During testing, the verify step writes a detailed report when it finds an error — which file, which line, what type.
The fix agent reads it and makes surgical fixes, without wasting time exploring the codebase or guessing at the problem.
Before this contract existed, the fix agent had free rein to run even longer than all other generation steps combined. Adding this single file cut the cost of error correction by an order of magnitude.
Between the first and last run, the model didn’t get any smarter. We used the same Qwen3.6-27B throughout. What changed was the environment.
DOMParser crashes Hermes — that’s not an app bug, it’s a gap in the prompt that didn’t mention fast-xml-parser. Calculator buttons in a column instead of the familiar button grid — our UI agent didn’t receive instructions on how to design that type of interface. app.json conflicts with Expo Router — that’s not an app bug, it’s a scaffold bug that didn’t prohibit creating that file.
Every bug becomes a line in a prompt, a check in the verify scripts, or code in the scaffold. The model doesn’t learn between sessions — it has no memory, and we don’t have the resources to fine-tune. But the environment remembers the minefield and won’t let anyone step on the same mine twice. Shell scripts don’t forget checks. Grep doesn’t miss patterns. The FSM won’t let you skip steps or call them out of order.
I truly saw this the moment when, after the first 13-hour run that produced a broken app, the agent spent just 37 minutes generating a fully working calculator. The pipeline ran, verify caught one error (SafeAreaView from the wrong package), the fix agent surgically replaced one import line, verify passed, smoke passed, the app works. 37 minutes from command to working application. The model didn’t do anything remarkable — it simply fulfilled the contracts. The environment didn’t let it fail.
And this is the key insight. Improving the environment closes the gap between open and closed models more effectively than improving the model itself. Scaffold installs the right packages — the model doesn’t need to guess versions through trial and error. Verify catches errors deterministically — the model won’t waste time on diagnostics. The model doesn’t need to remember the pipeline step order — the FSM remembers for it.
Large models make us lazy. Massive context — no need to think about prompt structure, and you can fix problems by piling on even more instructions. No need to design the environment, because the big model “will figure it out anyway.” Small models don’t forgive that laziness. Every token is expensive. Every rule must earn its place. Every check must pay for itself — if its false positive rate is higher than the frequency of real bugs, it hurts more than it helps.
And the most interesting part: systems designed under these constraints work better for any model. Minimalism doesn’t hinder a strong model, but it saves a weak one. This isn’t a limitation. It’s a design principle.
Three apps, all built in one evening:
| App | What’s inside | Time |
|---|---|---|
| Feedwise | RSS + Atom, bookmarks, full article text | ~1 hour |
| Calculus | iOS-style calculator | 37 min |
| HabTrack | Bar chart, pie chart, calendar, streaks | 52 min |
The trend is obvious. Models are getting cheaper. Hardware is getting cheaper. Quality is going up. Qwen3.6-27B, released just days ago, can generate mobile apps in reasonable time on an ordinary laptop. What will local models be capable of in a year? Two?
Last night I looked at the habit tracker and thought not about which model built it. I thought about the six markdown files that told it how. A few dozen lines each. Not a single line wasted.
]]>So I picked one. Multiple languages, multiple databases, zero documentation, an architecture that clearly accumulated over years without any coherent plan. The kind of project where most people turn around and walk away already at the “how do I even run this” stage. Over a weekend, Claude Code and I rewrote it from the foundation up and got a working prototype running.
This isn’t a post about how fast things are now. It’s about a specific technique without which that scale would have been impossible.
Vibe-coding works on small projects because the context fits in your head and in the context window at the same time. On large legacy code that breaks fast: the agent doesn’t know what’s already in the codebase, repeats the same mistakes, and loses the thread between tasks.
The obvious answer is more context in the prompt. But that scales poorly and gets expensive. The right answer is to structure what the agent needs to know — and automatically update that knowledge between tasks.
The key insight: each logical task needs its own session with a properly prepared scaffold. Not one giant context for the entire project, but targeted preparation for the specific ticket at hand.
Phase 1 — Harness assembly. Before each task, a supervisor agent reads the project (manifests, schemas, API surface, existing scaffold) and does something like a deep research pass: how do other people solve this kind of problem in this stack, what MCP servers exist for the tools we need, what anti-patterns are typical. The output is a harness tailored to the ticket:
CLAUDE.md with project context and critical rulesThe harness isn’t rebuilt from scratch each time — it reads what already exists and adds only what’s missing for the new task.
Phase 2 — Work session. A normal interactive Claude Code session. Claude works within the prepared context, I steer and course-correct. Nothing magical.
Phase 3 — Analysis and update. After the session, the supervisor reads the JSONL log (Claude Code writes a full transcript of every session) and looks for signals:
is_error: trueA single incident gets documented as inherent complexity. A repeating pattern (×2 or more) becomes a concrete harness patch: a new rule file, a strengthened existing rule, an MCP addition for missing docs, or an entry in the project Wiki.
Between tasks the harness doesn’t reset — it accumulates. The key artifact is project-wiki.md, a living document of compiled project knowledge. Four sections:
Reuse Map — what’s already implemented and where. Agent tried to write its own implementation on top of something that already existed? The path goes here, and the next task reads it first — before any research.
Anti-Patterns — not generic “don’t use raw SQL”, but project-specific: “this codebase already has a client for X right here — don’t reinvent it.” Rules in .claude/rules/ hold general principles; the Wiki holds what’s specific to this project.
Tips — approaches that worked in non-obvious ways.
Gotchas — non-linear dependencies, initialization order, hidden contracts between components.
The idea comes directly from Karpathy’s LLM Wiki: don’t store raw observations and RAG over them — compile them into a structured knowledge base that updates incrementally. The Wiki is read before each new task and before each iteration inside loop skills. The effect is noticeable by the third or fourth task: the agent stops hitting the same walls and navigates the codebase faster — not because it got smarter, but because the accumulated context won’t let it forget what’s already been figured out.
From Karpathy’s AutoResearch comes another idea: each successful iteration becomes the new baseline. Here that’s the harness — it never rolls back, only grows. By task N the agent operates as if it’s done this in the project many times before.
By the end of the weekend I had a strong sense of working with someone who was gradually learning the project — not a tool that starts from zero every time.
Building a harness for each task feels like overhead, but in practice it pays for itself by the second or third task within a project. And the most surprising part: harness assembly itself is fully automatable. You don’t need domain expertise in every stack — you just need to describe the scope of work and let the agent do the deep research. It finds what you need more accurately than you would in the same time.
This direction — automatic context adaptation per task, accumulating project memory across sessions — feels like where the next meaningful jump in AI-assisted productivity is going to come from.
I used to joke that while my AI agents do the real work, I’m their errand boy — the tester. The joke stopped being funny around the third app, when I toggled the theme to dark and the screen stayed white. The agent swore everything works. Fifty tests green. The app — white.
I decided it was time to build one more agent. A junior QA engineer that would take over testing. Here’s how we raised it — and what it taught us.
First thing Claude does when you ask it to test an app — it writes unit tests. Lots of them. Fifty in five minutes. Every state action verified. Every screen renders without crash. Every button press calls the right handler.
Looks solid. There’s one problem.
The test confirms that setTheme('dark') writes 'dark' to settings. Test passes. Screen stays white. The value got saved — the UI didn’t re-render. From the code’s point of view, everything is correct. From the user’s point of view — the dark theme toggle doesn’t work.
I asked Claude what’s going on. It said: “Visual theme application is a design gap.” Not a bug. A gap.
That’s when I got the fundamental problem. Claude was testing code. It should have been testing promises.
Every button on screen is a promise to the user. A toggle labeled “Dark Theme” promises the screen will go dark. A currency selector “€” promises all prices will show euros. A “Save” button promises data will be saved.
A human tester gets this intuitively. They look at the screen, tap the toggle, look at the result. If the toggle says one thing and the screen shows another — that’s a bug. Not a “design gap.” A bug.
I turned this into what I call an interaction map. Before writing any test, Claude has to go through every screen and answer one question for each interactive element: what does the user expect when they look at this? Not what the handler code does — what the button label promises.
Then Claude reads the code and compares. User expectation vs actual behavior. If they don’t match — it’s a broken promise.
The difference is subtle but it matters. A “Notifications” switch saves a setting for a background service — no visible change on screen, and the user doesn’t expect one. That’s fine. But a “Dark Theme” toggle with no visible effect — that’s a broken promise. The label says one thing, the screen shows another.
The first run with this rule found something real. A subscription tracker app had a currency setting. User picks euro — the spending widget on home shows €15.49. The subscription card right next to it — still $15.49. Same screen, two components, one has a hardcoded dollar sign. The interaction map caught it because it asked: “currency change — which screens does it affect?” — and checked each one.
Could you write a unit test that catches this? Sure. But you’d have to predict that this specific component would forget to read the currency setting. You can’t write a test for every possible oversight. A human tester solves this differently: change the currency, look at the screen. If something didn’t update — you see it right away. No prediction needed.
The interaction map is a plan. But the plan needs execution. Someone has to open the app and tap through it.
That’s what Maestro does — a UI testing framework for mobile apps. You describe a scenario in YAML: launch, tap here, type text, check what appeared. Maestro runs it on a real iOS simulator or Android emulator.
The key difference from unit tests: Maestro tests the built app. Same binary the user will install. If a library crashes on launch — Maestro sees it. If the keyboard covers the submit button — Maestro can’t tap it. If an animation leaves an element in the wrong spot — the check fails.
Here’s what it looks like:
- launchApp:
clearState: true
- extendedWaitUntil:
visible: "Add Subscription"
timeout: 10000
- tapOn:
id: "catalog-netflix"
- tapOn:
id: "btn-submit"
- extendedWaitUntil:
visible: "Netflix"
timeout: 15000
- takeScreenshot: home_with_netflix
Every action waits for a specific result. Not sleep(3) — “wait until this text shows up.” If it doesn’t — the test fails and you get a screenshot of what the screen actually showed.
The scenarios come from the interaction map. Visual effects — verified by Maestro. Cross-screen effects (currency change in settings affects home and statistics) — navigation between screens plus screenshots. Effects with no visual feedback — regular unit tests. Each effect type is covered by the right method.
The whole thing is wrapped in one shell script — smoke.sh. It builds the app, boots a headless simulator (no GUI window), installs the binary, runs all scenarios, kills processes when done. One command. The agent is not allowed to run these steps by hand — if the script breaks, fix the script.
Maestro confirms that taps worked and text appeared. But it doesn’t know how the app should look. The button might be there, but the color is wrong. Spacing is off. Layout doesn’t match the mockup.
Claude can look at images. After all scenarios pass, it opens every saved screenshot and compares against three sources of truth:
Stitch mockups. If the app was designed with Google Stitch, the original screen designs are saved next to the code. Claude compares the real screenshot to the intended layout — element placement, proportions, visual hierarchy.
Design tokens. A DESIGN.md file has exact colors, font sizes, spacing values. Claude checks if the screenshot matches.
The interaction map. If the scenario changed currency to euro, Claude checks that the screenshot actually shows euro signs everywhere, not dollars.
That’s exactly how the currency bug got caught. Maestro confirmed settings accepted the choice. The interaction map pointed to which screens should change. Claude looked at the screenshot — and saw that one component didn’t update.
Put it all together and you get something that looks a lot like how a real QA team works:
Planning. Read the spec. For each UI element, decide what the user should see. Flag anything suspicious before testing starts. That’s the interaction map.
Execution. Open the app. Go through every scenario. Check that buttons work. Data survives restarts. Bad input shows error messages. That’s Maestro.
Visual review. Compare each screen to the mockup. Check colors, typography, spacing. If you changed a setting — make sure the change reached every screen. That’s Claude looking at screenshots.
Each layer is a separate Claude Code skill — a markdown file that other skills can use. /build-app runs the full testing cycle after building. /improve-app uses just the interaction map and visual review — enough to check the impact of small changes. /test-app runs everything end to end.
In practice, this approach catches bugs in four categories that standard AI testing misses:
Broken promises. Theme toggle that saves the setting but doesn’t re-render. Currency selector that updates some components but not others. Search button with an empty handler.
Runtime crashes. Libraries that compile fine but crash on launch — because they need features not available in the user’s environment. TypeScript compiler and bundler see nothing. Maestro catches the crash on first launch.
Cross-screen mismatch. A setting that reaches one screen but not another. Data visible on one tab, missing on the next.
Design drift. Layout that shifted from the mockup. Colors that don’t match the design system. Inconsistent spacing between similar screens.
Nothing exotic. Normal problems every mobile developer deals with. But they’re invisible to unit tests — because unit tests check pieces in isolation. The interaction map checks promises. Maestro checks the assembled app. Visual review checks the visual contract.
The testing pipeline is part of Etnamute, the AI app factory I described earlier.
interaction-map/SKILL.md — builds a test plan from UI analysisvisual-review/SKILL.md — compares screenshots to mockups and design systemmaestro/SKILL.md — scenario templates, Expo Router gotchastesting/SKILL.md — runs all three layers in orderscripts/smoke.sh — build, simulator, Maestro, cleanup — one commandThe approach is not tied to Expo or React Native. The interaction map works with any UI framework. Maestro supports iOS and Android. Visual review works with any screenshot. The idea — test promises, not code — works anywhere.
Honest note: this is not a silver bullet. The agent skips steps sometimes. Complex forms need extra work. And it all depends on how well your UI elements are addressable — if a button has no test ID, Maestro can’t tap it.
But between “AI runs tests and declares victory” and “AI opens the app and checks what the user sees” — that’s where most real bugs live.
The whole thing runs on top of Claude Code. No custom framework, no cloud service, no SaaS subscription beyond what you’re already paying for. Just markdown files telling Claude how to do its job.
I wanted to ship mobile apps fast. Like, multiple-apps-per-week fast. Not prototypes — actual store-ready products with monetization, ASO materials, and marketing copy.
Tools like Rork exist, but they’re a black box. You pay per prompt, the code lives in their cloud, and you can’t customize the pipeline. I wanted something I own and can plug into a larger system.
A folder with ~25 markdown files and a few scripts. That’s it.
The markdown files define a pipeline:
discovery.md — adaptive interview, generates questions based on your specific app ideaspec.md — PRD generation with web research and user approvalqa.md — self-review with dynamic checklists generated from the PRDrelease.md — fastlane config, Maestro screenshots, local buildsheadless.md — accepts a PRD file, no interactive steps, runs autonomouslyClaude Code reads these files and follows the instructions. Skills and rules in .claude/ get auto-discovered. An MCP server serves Expo and RevenueCat docs on demand so Claude doesn’t hallucinate API calls.
You run claude in the project directory and describe your app idea. From there:
Phase 0 — Discovery. Claude analyzes your idea and asks 5-8 adaptive questions via structured UI — not generic “what type of app” stuff, but domain-specific questions with relevant options. Then it runs web searches to find competitors, validate pricing, check market demand. You get a PRD summary to approve before any code is written.
Phase 1 — Plan. A 9-section implementation plan generated from the approved PRD. Tech stack, file structure, milestones with checklists.
Phase 2 — Build. Five milestones executed sequentially: scaffold, screens, features, monetization (if you chose it — it’s optional), polish + launch materials. QA check after each milestone.
Phase 3 — Finalize. Final QA pass across the entire app.
Phase 4 — Release. Optional. Generates fastlane config, captures screenshots via Maestro on a simulator, builds IPA/AAB locally, uploads to stores. You confirm before it submits.
There’s also an Improve Mode — point it at an existing app in apps/ and ask for changes. It reads the PRD and code, clarifies what you need, applies targeted changes, verifies.
This is not magic. Claude can still ignore instructions. The QA step is self-review — the same model checking its own output. The “97% quality score” is a number Claude assigns to itself.
But the difference between “generate an app” and “follow a structured pipeline with checkpoints” is real. It’s the difference between a junior dev with no process and a junior dev with code review. Not bulletproof, but way less random.
The whole point of having a formal PRD schema is that other agents can generate it. An upstream agent analyzes the market, picks a niche, writes a PRD, hands it to Etnamute — and out comes an app. No human in the loop.
That’s what I was actually building: an AI-first app publisher. Etnamute is just the developer in that chain.
./setup.sh
claude
> I want an app for tracking daily water intake
Apache 2.0: github.com/bes-dev/etnamute
]]>