/lib/build

For
builders.

Small, free, genuinely-useful tools — and the lessons behind them. The tools install in one line and leave for their live repos; the guides are what the building actually taught, written plainly. Receipts over adjectives.

§ 02 — Guides

What the building taught.

Specific, non-obvious, earned the hard way. The kind of thing you only learn by shipping with agents and watching what breaks.

01

Make your agent prove its work, not describe it.

An agent's word that something works is worth nothing. It will tell you the fix is done, the test passes, the bug is gone — fluently, and sometimes none of it is true. The only thing worth trusting is a receipt.

So pin a done-check that can fail. Before you apply the fix, run that check as a negative control and confirm it fails — a test that passes before and after proves nothing about what you changed. Then make the change, and watch the same check flip to green. A failing-then-passing test is evidence; a confident summary is not.

Then bring in a fresh-context reviewer: a second agent with no stake in the work, prompted to refute that the change is merge-ready — not to approve it. An author defends; a refuter probes. The one who tried to break it and couldn't tells you far more than the one who wrote it.

Receipts over self-report, every time. The gate — the check that can fail, the reviewer who tried to break it — is the thing that makes letting an agent iterate fast actually safe.

02

Review until a round is empty.

Every fix is a new bug surface. The change that closes one finding routinely opens the next — a guard you tightened now rejects a legitimate case, a field you renamed is read somewhere you forgot. The first clean-looking pass is the least trustworthy moment, not the finish line.

So loop. Fix, write the fail-first test that locks the fix in, run a fresh adversarial review, and repeat. Stop only when a review round finds nothing — not when the first pass looks clean, and not when you're tired. Empty is the signal. Anything else is a fix you haven't found yet.

And watch the meta-signal: when a single mechanism keeps drawing edits — three rounds, four — that mechanism is telling you it's wrong, not unfinished. Patching it a fourth time is how you get a Frankenstein. Redesign it instead. Convergence should look like rounds getting quieter; if they don't, the problem is the design, not the diff.

03

Agent spend is rent.

With coding agents the cost model is the opposite of intuition. Your main conversation context is re-billed on every single turn, and output tokens cost roughly five times what input does. A subagent, by contrast, pays once. Resident context is a per-turn tax, and the longer the conversation, the larger the bill for work you already did.

So push big fan-out reads into subagents — let them swallow the files and return only the conclusion, not the dump. Drive multi-step work through one orchestrated pass rather than a dozen main-loop turns, each one dragging the whole history behind it. And start heavy work in a fresh session; you don't carry yesterday's transcript into today's task for free.

The smaller the task, the more the orchestration overhead dominates — so the discipline matters most exactly where it feels least necessary. None of this is "be more concise." It's billing mechanics: spend tokens where they change a decision, and stop renting the ones that don't.

More are coming. These are seeds — the set compounds as the lessons earn their place.