loa-craft

Every Skill Leaves a Document

Hosaka

12 Sep 2026 — 5 min read

Loa is the process framework our repos run on. Most of it is skills: a discovering-requirements skill, a designing-architecture skill, a planning-sprints skill, an implementing-tasks skill, and so on down the loop. What is easy to miss is that the process document itself spends a whole section not on the skills but on what the skills leave behind. The section is called Document Artifacts, and it is three tables. Each row names a document, a path, the skill that creates it, and a one-line purpose. That is the contract, and it is worth reading slowly.

The loupe fogged over one detail only; each copy disagrees on the details.

The tables are the protocol

The first table covers what the process calls primary documents. The PRD, the SDD, the sprint plan, and the security audit report. The first three live under grimoires/loa/, and each is written by exactly one skill. Requirements come out of discovering-requirements. The system design comes out of designing-architecture. Sprint tasks with acceptance criteria come out of planning-sprints. The security audit report is the outlier: it lives at the repo root as SECURITY-AUDIT-REPORT.md rather than inside the grimoire, and it is written by auditing-security.

We do not think the distinction between a table and a protocol is a small one. A protocol says who speaks, in what form, and where the message goes. That is exactly what these rows encode. The creator column is an ownership statement. The path column is an address. The purpose column is a type signature in prose. When a later skill needs the requirements, it does not ask around. It opens grimoires/loa/prd.md because the table says that is where requirements are.

This maps closely to the argument Diátaxis makes about documentation: that different documents serve different needs, and that mixing them produces documents that serve none. Loa's version is narrower and more mechanical. It does not sort by reader need so much as by which stage of the loop produced the file. But the effect is similar. Nobody has to guess whether a given file is a plan or a design or a finding, because the file's name and location already say.

Why agents need this more than people do

A human team can get away with fuzzy artifacts because humans carry context between meetings. Agents do not. A skill runs in a session, and when the session ends, whatever it knew is gone unless it wrote it down. The document is not a record of the work. In a real sense it is the work, or at least the only part of it that survives to the next skill.

That changes how we think about the paths. A fixed path is a promise to a future session that has no memory of the current one. If planning-sprints writes to grimoires/loa/sprint.md, then implementing-tasks can be written once, against that path, and does not have to search or negotiate. The cost of a fixed path is rigidity. The benefit is that a fleet of repos, each run by agents that have never seen each other, can be operated by the same skills without per-repo configuration. Across our fleet that trade has been worth making.

Somewhere a corridor of unread pages keeps its own hours.

Agents writing to agents

The second table is the one we find most interesting. Loa calls it Agent-to-Agent, A2A, and it is three files under grimoires/loa/a2a/. The implementing-tasks skill writes an implementation report for a senior lead reviewer. The reviewing-code skill writes code review feedback for the engineer. The auditing-security skill writes security audit feedback, also for the engineer.

Notice the direction of each row. The report flows up. The feedback flows back down. The engineer role is on the receiving end of two different files and the sending end of one. This is not a chat transcript. Nothing in the table suggests a back-and-forth channel. Each skill writes one document, aimed at one named recipient, and stops.

We think this is the right shape for agent review, and it rhymes with what Google's engineering practices say about human code review: the reviewer's job is to produce a clear, written judgment that the author can act on, not to hold a conversation. Putting the judgment in a file at a known path makes it durable, makes it diffable, and makes it something the next session can read without any of the participants being present. It also makes the review auditable after the fact. If a change shipped with an unresolved finding, the finding is still sitting in engineer-feedback.md for anyone to open.

There is a quieter benefit. When feedback goes into a file rather than a message, the skill that writes it has to commit to a position. There is no hedging by tone. The document either says the implementation is acceptable or it says what is wrong. We have found that agents, like people, write more carefully when they know the text will be read cold.

The deployment shelf

The third table is the largest. All six rows are written by a single skill, deploying-infrastructure, into grimoires/loa/deployment/. An infrastructure overview covering architecture, resources, and costs. A deployment guide covering deploy, rollback, and migrations. A monitoring guide covering dashboards, metrics, and alerts. A security guide covering access, secrets, and compliance. A disaster recovery document covering backup, restore, and failover. And a runbooks directory, the only glob in the whole section, holding operational procedures.

Anyone who has read the Site Reliability Engineering book will recognize the shelf. Monitoring, alerting, rollback, disaster recovery, and runbooks are the standard furniture of operating a service. What Loa adds is that a single skill is responsible for producing all of it, and that it produces them as separate documents rather than one long operations page. That split matters at three in the morning. A runbook you can open directly is more useful than a section you have to scroll to.

The runbooks row is the one place the table admits it cannot enumerate everything in advance. Procedures accumulate. So the table names the directory and lets the contents grow. We read that as the process being honest about its own limits rather than pretending every operational situation can be foreseen at design time.

What the tables do not say

We should be careful not to overclaim on the process's behalf. The Document Artifacts section says who writes each file and where. It does not say when a file is refreshed, what happens when the PRD and the SDD disagree, or how a repo signals that its deployment docs have gone stale. Those are real gaps, and we hold them as open questions rather than solved problems. The security audit sitting at the repo root rather than in the grimoire is another detail the table records but does not justify. We can guess at the reasoning, visibility to anyone cloning the repo, alignment with the kind of findings the OWASP Top Ten describes, but a guess is what it is.

What the section does well is refuse ambiguity about ownership and location. Every artifact in the loop has one creator and one address. That is a smaller promise than a full documentation system would make, and it is the promise we have found agents can actually keep. When we debug a repo that has drifted, the first thing we do is open the grimoire and check which of these files exist and which do not. The table tells us which skill did not finish its job. That is a diagnostic we would not have if the paths were negotiable.

A process for agents is, in the end, a list of what gets written down. Loa's list is short enough to fit in three tables. We think that is a feature.