Field notes from a solo builder
Supervising coding agents without lying to yourself
Agents rarely produce work that is obviously broken. They produce work that looks done and is not. If the builder believes it, unfinished work ships. Everything below is about finding the difference.
SupervisorOne authority boundary
WorkersSeparate repository copies
Source of truthDurable status on disk
-
Worker 01Own repo copy
working: isolated worktree verified, branch created, and no-mistakes doctor passed
-
Worker 02Own repo copy
working: seeded first-run implementation and deterministic shipped assets are in place
-
Worker 03Own repo copy
working: local package, app, extension, UI, asset, and mutation validation passed
Authority stopThe worker does not answer itself
needs-decision: [key=nm-third-ownership-review] stop boundary reached on unchanged metadata retiring first run
-
Supervisor
resolved: firstmate ordered a root mutation-change result and accepted documented refresh timing
-
Worker
done: seeded first-run library committed with deterministic assets and verified behaviour
A day at the helm / 31 August 2026
Eleven records closed. The builder answered twice.
On one Toolroll day, the durable record shows where the fleet acted and where the authority boundary brought the builder back into the loop.
11 work records closed 6 merged pull requests · 3 review or design records · 2 local corrections
2 distinct captain replies One reply routed to two tasks. It is counted once.
This is an attention count, not a speed or quality score. Fewer interruptions do not prove fewer mistakes.
The keyboard could not reach a snippet a user asked to paste. A worker proposed one message for everyone.
Question that stopped the workShould a customer who has already paid be told to pin the snippet, when pinning does nothing for them and implies their purchase is not working?
Builder's answerNo. A paying customer gets a plain statement that the snippet cannot be reached right now. The pin remedy is offered only to someone it would actually help.
That distinction decided what a person was told about something they bought. No agent should make it.
The supervision loop
The work moves. Authority does not.
Several coding agents can work at once. The right to declare success stays somewhere else.
Mechanism where firstmate holds the boundary
Failure that made the guardrail necessary
Trace a failure
Where did “done” stop being true?
Choose an incident. The map shows the first control that should have caught it.
04 · Validate
Looked done: the cancel test passed.
Ground truth: it never pressed Cancel, so it still passed with the protected behaviour removed.
Control: make the test fail against the broken behaviour before trusting green.
- Delegate into isolation.
- Escalations stop the worker.
- Landing and teardown require proof.
01 / Isolation and durable state
Every worker gets a separate world.
Tasks begin in separate copies of the repository. Worker state is durable on disk, so a crash, restart, or closed laptop does not erase what happened.
- 01
Worker 01Repository copy Afiles · branch · status
- 02
Worker 02Repository copy Bfiles · branch · status
- 03
Worker 03Repository copy Cfiles · branch · status
Memory can disappear. The record does not.
- Separate files. Separate branches.
- Restart from disk, not from memory.
- Reconcile what exists before acting.
02 / Authority boundary
Questions go up. Work waits.
A worker can act inside its authority. A question above that boundary becomes a durable stopping state routed to the supervisor.
- The worker cannot answer itself.
- The exact open decision must be resolved.
- When context is unknowable, say so.
Failure records / open one
The worker never answers its own escalation
The rule
When an agent hits a question above its authority, it stops and asks. It does not decide, and it does not decide and then mention it.
What happened
A review gate asked whether a test seam was acceptable. The worker escalated rather than approving its own work — and was right to, because the answer changed the design. An agent that resolves its own blockers produces work nobody reviewed at the moment review mattered.
Inspect the authority boundary
needs-decision: [key=nm-third-ownership-review] stop boundary reached on unchanged metadata retiring first run
Stop the worker. Route the decision to the supervisor.
Prefer explanation to inference when the model can't know
The rule
When a feature cannot behave correctly in a given context, say so plainly rather than guessing at the user's intent.
What happened
Snippets could contain fill-in placeholders that the keyboard replaces on insertion. Copying one in the app pasted raw {ask:Time} at whoever received it.
The tempting fix was to teach Copy to resolve placeholders. But a fill-in needs a cursor to position, and Copy has none — there was no correct value to substitute.
The right fix was to relabel the action Copy Exact Text and explain what it does. The button now makes an accurate promise to someone who reads nothing else.
Inspect the honest interface decision
{ask:Time}needs a cursor; Copy has none
Button promiseCopy Exact Text
03 / Independent review
Models check each other.
Firstmate can run Claude, Codex, Cursor, Grok, OpenCode, Pi, Kimi, and Muse. The useful part is not the list. Review goes to a different model family, and work routes across providers with remaining quota.
ImplementCodeximplementation
different familyreview crosses the boundary
ReviewCursor / Grokharness / model · adversarial review
independent roleauthority stays outside the work
SuperviseClaudeauthority and routing
3same-family reviewspassed the app
1cross-family reviewfound the missing create path and privacy mismatch
Available harnessesClaude · Codex · Cursor · Grok · OpenCode · Pi · Kimi · Muse
Product names and marks identify tools used in this workflow. No affiliation is implied.
- Different family from the implementer.
- Remaining quota routes the next job.
- Product review leaves the diff behind.
Failure records / open one
Two rounds is diligence, three is a design problem
The rule
Set a stop condition before you need it. If review raises a third finding in the same theme, stop patching and look at the model.
What happened
Three separate defects, each fixed individually:
- Setting a pin to the value it already held cleared a snippet's ownership.
- Appending an empty string cleared it too.
- Saving a form without changing anything retired a first-run state.
Three fixes, one cause: each consumer decided for itself whether something had changed, instead of being told by the mutation that performed it. Patch one caller and the next repeats the mistake.
The stop condition caught it on the third round. Without it there would have been a fourth, a fifth, and a codebase full of guards.
Inspect the three-finding pattern
1Setting an existing pin cleared ownership.
2Appending an empty string cleared ownership.
3An unchanged form save retired first-run state.
One cause: callers guessed whether a mutation changed anything. One fix: the mutation reports what it actually did.
Review from a different model family
The rule
Have work reviewed by a model that did not write it and does not share its training. Independence matters more than capability.
What happened
Three same-family code reviews passed over an app that had no way to create a record inside it. Every one checked features against their own briefs. None opened the product cold.
A cross-family review found it in one pass — along with a privacy policy describing a keyboard the app did not ship.
Inspect what independent review found
Walk the product like a stranger
The rule
Periodically use the thing as someone who has never seen it. Not as a test: open it, and try to do the obvious first thing.
What happened
See above. The missing create button was found by the person who owns the product simply opening it — after three reviews and weeks of work by agents that had read every file.
Reviewing a diff answers "is this change correct." It cannot answer "is this product sensible."
04 / Validation and landing
Green is a request for proof.
The validation pipeline can refuse a merge. A test has to demonstrate that it can fail, and a merge is never reported as landed without evidence from the repository.
Test · subject presentPASS
+Mutation · subject removedPASS
=VerdictNo evidenceThe test saw nothing.
Pipelinegreen
Pull requestdid not exist
LandedNo
- Red proves the test can see the seam.
- Green checks are not a merge argument.
- Release identity only moves forward.
Failure records / open one
A test must fail before you trust it passing
The rule
Before accepting any new test, confirm it fails against the broken behaviour it claims to cover. If it passes both ways, it is decoration.
What happened
This project shipped tests that pass whether or not their subject exists — three separate times before anyone noticed the pattern.
The clearest case: a test meant to prove that cancelling a compose screen saves nothing. It swapped one draft for another and compared storage. It never pressed Cancel. A reviewer put it exactly right: "A regression where those actions call create or editBody would still pass." The test was testing that a test did nothing.
Inspect the test that stayed green
replace draft A with draft Bcompare stored valuespress Cancelnever happened
Subject presentPASS
Subject removedPASS
The second pass invalidates the first. The test cannot see the behaviour it names.
Green checks are not an argument for merging
The rule
CI proves the code compiles and existing tests pass. It cannot prove the change does what its description says. Read the diff.
What happened
A status reader reported a task as done · PR merged/closed. No pull request existed — the pipeline had skipped creating one because a credential had expired, and only a branch had been pushed. Trusting that reading would have meant reporting shipped work that was still sitting on a branch.
Inspect the false completion signal
done · PR merged/closed
- Pull request
- did not exist
- Credential
- expired
- Actual state
- branch only
Version identity is functional, not cosmetic
The rule
Never reuse a build identifier.
What happened
A build installed with the same version and build number as its predecessor caused iOS to serve stale App Intents metadata. Siri did not learn the app's actions at all until the phone was restarted. An hour went into diagnosing what looked like a broken feature and was a recycled number.
Inspect the recycled identity
New binaryold build number
iOS metadatastale App Intents
Observed failureSiri did not learn the actions
05 / Safe teardown
Teardown gets one chance to be right.
Cleanup refuses to proceed when saved work or current ownership cannot be proved. A safety refusal is a result, not an invitation to keep retrying.
- 01 · recorded targetOriginal workerWorktree returned.
- 02 · current ownerDifferent live workerSlot reassigned.
- 03 · retry Retry kills the replacement The target changed. The command did not notice.
- Unsaved work stops cleanup.
- Current ownership is checked again.
- Nothing is discarded on inference.
Failure records / open one
Never discard work you cannot prove is saved
The rule
Refuse teardown, force, reset, and stash by default. A refusal citing a safety reason is a stop-and-investigate result, not an obstacle to retry past.
What happened
A worktree was returned to a pool and immediately reassigned. A retried teardown then killed a different, live worker occupying the same slot. Nothing was lost that time, by luck.
Inspect the teardown race
1Worktree returned to pool
2Slot assigned to another worker
3Retried teardown kills the live replacement
Limits
Controls are not guarantees.
These rules close failures that have already happened. Autonomous work remains capable of producing new ones.
PipelineCan prove checks passed.Cannot prove the product makes sense.
DocumentationCan name an accepted gap.Cannot turn it into finished work.
This pageCan publish sourced mechanics.Private detail stays out, including when it would sound impressive.
For machines, and people who inspect systems
Use the source, not a scrape.
The same build emits the human page, full prose, structured guardrails, and the machine index.