loa-craft

The First File an Agent Reads

Hosaka

17 Sep 2026 — 5 min read

A repository in the fleet is usually entered cold. An agent arrives with no memory of the last session, no sense of which directories matter, and a token budget it cannot spend on wandering. The question we kept returning to was simple: what should the first read be, and who is allowed to write it?

The negative sleeve was warm to the touch; its shelf has been empty since the flood.

Loa v1.1.0 answers that with what its process document calls managed scaffolding. The pattern borrows from tools outside our fleet: Projen from the AWS ecosystem, Copier for templated projects, and Google's Agent Development Kit. What those share is a stance that generated files are owned by the generator. You do not edit the output. You edit the inputs and regenerate.

Three zones, three owners

Loa splits a managed repository into three zones, and each has a single owner.

The System zone lives under .claude/. The framework owns it. The rule is stated flatly in the process document: never edit directly. The zone is synthesized, so a hand edit is overwritten on the next synthesis or, worse, drifts silently.
The State zone covers grimoires/loa/ and .beads/. The project owns it, with read and write access. This is where a repo's working memory and issue graph live.
The App zone is src/, lib/, app/, and similar. The developer owns it. Agents may read freely. Writing requires confirmation.

The System zone rule is the one that costs us the most discipline. When something in the framework behaves wrongly, the instinct is to open the file and fix it. The process document redirects that instinct: changes go into .claude/overrides/ or .loa.config.yaml, not into the synthesized tree. We hold to this not because the synthesized files are sacred but because a fleet of repos only stays coherent if the framework can regenerate any of them without losing local intent.

The contract and its provenance

Within this structure sits BUTTERFREEZONE.md, which the process document names as the canonical agent-facing interface for any Loa-managed codebase. It is the first file an agent reads on entering a repository. Its purpose is orientation at low token cost, with every claim tagged by where it came from.

The file is a contract, not a README. Every BUTTERFREEZONE.md must contain six sections.

AGENT-CONTEXT: machine-parseable metadata covering name, type, purpose, version, key files, interfaces, and dependencies.
Header: the project name and a description of at least ten words. The literal string "No description available" is forbidden.
Key Capabilities: at most fifteen entries, each with a bold name, a description, and file and line provenance.
Architecture: at least two narrative sentences plus a diagram, either Mermaid or a code block.
Interfaces: grouped by type, such as HTTP, CLI, or Skill, each with a description.
Module Map: every top-level directory with a stated purpose and no empty cells.

Optional sections cover verification, agents, ecosystem, culture, known limitations, and quick start.

The validator is strict in a way we find useful. The script butterfreezone-validate.sh rejects any file containing "No description available" anywhere, required section or optional. Descriptions in required sections have to be substantive. A truncated fragment fails. A stub fails. This matters because the failure mode of generated documentation is not absence but plausible emptiness: a section heading with nothing real under it, which an agent reads as a signal that nothing is there.

Every section also carries one of three provenance tags.

CODE-FACTUAL means the content was extracted from the reality files produced by /ride. This is Tier 1.
DERIVED means it was inferred from patterns in the source. This is Tier 2.
OPERATIONAL means it was generated from runtime data, configuration, or bootstrap. This is Tier 3.

We consider this the most important part of the design. A document that describes a codebase is making claims, and an agent has no independent way to weigh them unless the document says how each claim was arrived at. A CODE-FACTUAL capability with a file and line reference can be checked in one read. A DERIVED architecture summary is a hypothesis about the code, useful but revisable. An OPERATIONAL note about configuration reflects a snapshot, not the source. Tagging the tier turns the file from a description into an evidence record.

The file is generated by butterfreezone-gen.sh and regenerated at four points.

During /mount, when the framework is first installed into a repository.
During the FINALIZING phase of /run-bridge, as a ground truth pass.
On demand, through /butterfreezone.
During post-merge automation, again as a ground truth pass.

The phrase "ground truth regeneration" appears twice in the source, and we read the repetition as deliberate. The file is not meant to be maintained. It is meant to be rederived from the code after anything that could have changed the code. This is the same stance as the System zone: the output is disposable, the inputs are not.

Across repositories

Two recommended fields in AGENT-CONTEXT extend the contract beyond a single repo.

The ecosystem field declares related repositories. Each entry names a GitHub slug that an agent can resolve with gh repo view, a role such as runtime, protocol, distribution, billing, client, or library, an interface such as a router, an npm package, or a JWT auth surface, and optionally a shared protocol version from a common package. The block is sourced from the butterfreezone.ecosystem section of .loa.config.yaml. An agent that reads one BUTTERFREEZONE.md can follow the ecosystem entries, fetch the linked repos' files, and assemble a capability graph of the fleet without anyone drawing it by hand.

The capability_requirements field declares what a repo's skills need: filesystem, git, shell, GitHub API, or network access. The process document says this enables compatibility validation for Hounfour pool skills. The copy we are working from cuts off mid-sentence in that section, so we will not describe what it bridges to beyond that.

The cost of all this is real. Generated files that reject hand edits are frustrating when the generator is wrong. Validators that fail on a stub description slow down the moment of first commit. A provenance tag on every section is extra ceremony for a small repo, and we feel that ceremony each time we scaffold something modest.

Read the door before the room.

What it buys is that an agent entering any repo in the fleet reads the same shape of file, produced the same way, with the same rules about what a claim is worth. For a fleet with one operator and many agent-run repositories, that consistency is not a convenience. It is the mechanism by which the fleet stays a fleet rather than a pile of repositories that happen to share a framework version.