The Rollout
Agent-legible repositories: your repo now has two kinds of readers
The highest-leverage file in this repository contains no code. It is an instructions file that every agent session reads before touching anything, and one line in it — use this script to register new Swift files with the Xcode project — has prevented more broken builds than any test we have. Not because agents are careless, but because a macOS project file is exactly the kind of global, fragile, undocumented state a fresh session cannot infer from the code around it.
That is the general situation now. A repository has two kinds of readers: humans, who read it warm, with months of accumulated context, and agents, who read it cold, from zero, dozens of times a week. Sessions are stateless; the repo is the only memory they all share. Which means repo structure has quietly become interface design, and the question “can a competent stranger be productive here in ninety seconds” is no longer hypothetical. You are running that experiment several times a day.
The five memory surfaces
After a year of running multiple agents against the same repos daily, the structure that works has settled into five layers, distinguished by when they load and how long they stay true.
Instruction files are the always-loaded layer, which means every line in them taxes every session. The discipline is the same as for any hot path: rules and invariants only, with pointers down the stack for detail. “Read the newest handover entry before starting” is one line; it makes layer 4 work. The common failure is treating this file as documentation and letting it grow until the agent’s attention budget is spent before the work starts.
Playbooks and skills hold multi-step procedures — how a release ships, how QA runs, what the deploy gate checks. They only load when the task matches, so they can afford detail the instruction file cannot. The test for whether something belongs here: it has steps, and doing the steps wrong has a blast radius.
Executable scripts are the layer people underrate. An agent asked to add a file to an Xcode project will, from first principles, edit the pbxproj — sometimes correctly. A script removes the “sometimes.” Anything global, fragile, or full of tribal knowledge (project registration, code signing, notarization, database migrations) should be a script the agent runs rather than a procedure it re-derives. Scripts are the difference between telling every new hire how the coffee machine works and just labeling the buttons.
The handover file carries time: what is half-done, what was rejected and why, what comes next. It deserves its own discussion, and has one in the handover problem.
The transcript archive is the layer you already have whether you maintain it or not: every agent writes complete session logs to your disk (here, exactly). Unqueried, it is dead weight. Searchable, it is the answer to “have we hit this error before” and “what did we decide in May” — questions the other four layers are too terse to answer. A local browser like Agent Sessions makes this layer usable without any setup.
The test
The measure of an agent-legible repo is what a cold session does in its first two minutes. In a repo with these layers: reads the rules, reads the briefing, and starts the actual task. In a repo without them: greps around, re-derives the build system, makes a reasonable-but-wrong assumption about the one fragile thing, and spends your review cycle discovering what the last session already knew.
None of this is agent-specific, which is the quietly satisfying part. Terse rules, written procedures, wrapped operations, shift-change notes, and a searchable record are what good teams do for humans; agents just remove the option of pretending the onboarding docs are fine when they are not. The stateless reader was always coming. Now it reads your repo before lunch, every day, and it grades the structure by how much of your money it burns on archaeology.