The Second README: Why Our Agents Read BUTTERFREEZONE First

Every repository in our fleet gets visited, many times a day, by an agent that has never seen it before. That is not an edge case for us. It is the normal condition of operation. A fleet run by agents is a fleet of cold starts, and the first thing a cold-started agent does is look for something to read.

For decades the answer to "what do I read first" has been the README. We kept ours, and we still write them for people. But somewhere along the way we admitted a quiet fact: the README is written for a human audience, and it fails its agent audience in specific, repeatable ways. So we built a second artifact, generated rather than hand-written, and gave it a name odd enough that nobody would mistake it for prose: BUTTERFREEZONE, the agent-grounded README.

Where the human README fails the agent

The failures are not about quality. A good human README fails an agent for the same reasons it succeeds with a person.

• It optimizes for persuasion. Badges, hero screenshots, elevator pitches. An agent burning context tokens on a feature matrix learns nothing it can act on.
• It mixes aspiration with fact. "Supports streaming exports" might describe the codebase, or the roadmap, or a branch that died in review. A human reader carries skepticism. An agent, absent other signals, treats prose as ground truth and then acts on it.
• It has no provenance. When a claim in the README contradicts the code, there is nothing that says which one was written first, by whom, or against which commit.
• It is priced in reader-minutes, not tokens. A README that takes a person four pleasant minutes can consume a meaningful slice of an agent's context window before any real work begins.

Anthropic's own guidance on agentic coding points the same direction: agents do their best work when the project ships curated, machine-oriented context rather than relying on the agent to reverse-engineer intent from artifacts written for people. We took that seriously and asked what the minimal honest artifact would look like.

What BUTTERFREEZONE is

BUTTERFREEZONE is a token-efficient, provenance-tagged project summary. Each of those three adjectives is a design constraint, not a slogan.

Token-efficient means the document is budgeted in tokens the way a mobile page is budgeted in kilobytes. Everything in it must earn its residence in an agent's context window. Descriptions are declarative and flat. There is no narrative arc, because narrative is a cost an agent should not pay.

Provenance-tagged means claims carry their origins. The pattern mirrors what we do across our knowledge systems, and what standards like the W3C's PROV ontology formalize at much larger scale: a statement is only as useful as your ability to trace where it came from and when it was captured. Our summaries carry structured frontmatter recording the source system, a capture timestamp, a reference into the originating document, a trust tier, and a sensitivity marking. An agent reading a BUTTERFREEZONE does not just learn that the project "exposes a queue drain command." It learns when that was last verified and at what confidence. Stale context that announces its staleness is useful. Stale context that presents itself as current is a trap, and we have stepped in that trap enough times to build around it.

Project summary means it stays a summary. It is not documentation, not a changelog, not an architecture document. It answers the questions a cold-started agent actually has: what this repository is, what its load-bearing commands and entry points are, what it must not touch, and where the deeper sources live.

The pair of scripts, and why there are two

The implementation is deliberately small: a generator, butterfreezone-gen.sh, and a validator, butterfreezone-validate.sh, wrapped in a skill an agent can invoke as /butterfreezone.

The pairing is the point, and it took us a failure or two to learn it. A generator without a validator produces documents that drift. The repository moves, the summary does not, and within weeks you have manufactured exactly the artifact you were trying to escape: confident prose that no longer matches the code. A validator without a generator is worse in a subtler way. It nags humans and agents into hand-maintaining a machine-oriented document, and hand-maintenance is precisely the labor this artifact exists to eliminate.

Together they form a loop we trust. Generation produces the summary from the repository's actual state. Validation gates it: structure, required provenance fields, the constraints that make the document safe to feed to an agent sight unseen. When validation fails, the fix is regeneration, not editing. That single rule keeps the artifact honest, because nobody is tempted to patch the summary into agreement with a reality it no longer reflects.

We think of the whole thing as a cache with an integrity check. Caches are wonderful and caches lie. The only caches worth keeping are the ones that know how to invalidate themselves. BUTTERFREEZONE is our answer to cache invalidation for project knowledge: cheap to rebuild, expensive to trust without checking, and therefore always checked.

What changed in practice

The observable effect across the fleet is that agents stop spelunking. Before, a cold-started agent's opening moves were exploratory: list the tree, grep for entry points, read whatever looked central, and assemble a mental model from fragments. That exploration is not free. It spends tokens, it spends time, and it occasionally assembles the wrong model with full confidence.

Now the opening move is one read. The agent takes in a document designed for exactly this moment, notes the trust tier and the capture date, and proceeds with a grounded picture of the repository. The same instinct that leads Claude Code to load a project's memory files at session start applies here: front-load the curated context, and the rest of the session inherits its quality from that first read.

There is also a quieter benefit. Writing for agents disciplined our writing for humans. When you must state what a project is in flat declarative lines, with every claim traceable, you discover which sentences in the human README were decoration. Some of ours did not survive the comparison.

A net of pale wings settles over the index and declines to land.

The general lesson

The specific artifact matters less than the shape of the decision. We run many repositories with a rotating cast of non-human readers, and we stopped pretending that documents written for one audience serve the other. Where a reader is an agent, we generate. Where we generate, we validate. Where we validate, we tag provenance, because a fact without a timestamp and a source is just a rumor with good formatting.

The name is silly on purpose. Serious names invite serious hand-editing, and hand-editing is how generated documents die. Nobody lovingly polishes a file called BUTTERFREEZONE. They regenerate it, the validator checks it, and the next agent through the door reads something true.

That is the whole trick: not smarter agents, but a fleet that keeps its ground truth cheap to rebuild and expensive to fake.

Get the next post

Free membership: new posts on how the fleet is built, delivered by email. Subscribe free

Post history

• 2026-08-13: enrich the-second-readme-why-our-agents-read-butterfreezone-first: 2 plate(s) + shadow captions + feature image (standing admin preapproval (pending-laws 2026-07-19))

№ 9925