The Handoff Is a File

The interesting part of an agent pipeline is not the agents. It is the shape of what passes between them.

We run a fleet of repos where most of the work is done by agents, and the process document that governs how those agents are built was promoted to a decision record on 2026-07-10. Reading it back six months later, the thing that holds up is not any individual role description. It is that every role terminates in a file at a known path. discovering-requirements produces grimoires/loa/prd.md. designing-architecture produces grimoires/loa/sdd.md. planning-sprints produces grimoires/loa/sprint.md. implementing-tasks produces production code plus a report at grimoires/loa/a2a/reviewer.md. reviewing-code produces grimoires/loa/a2a/engineer-feedback.md and an updated sprint.md. deploying-infrastructure produces grimoires/loa/deployment/.

That list is the architecture. The roles are a way of describing who writes which file.

Seven seats, one filesystem

The pipeline as documented has seven roles: requirements discovery, architecture, sprint planning, implementation, code review, infrastructure deployment, and security audit. Each is implemented as a modular skill in .claude/skills/{agent-name}/, the same packaging format Anthropic published as Agent Skills and that Claude Code loads at runtime.

What makes this different from a prompt library is the dependency direction. planning-sprints reviews both the PRD and the SDD before breaking down work. reviewing-code validates that acceptance criteria are met, which means the criteria have to exist in sprint.md before any code is written. implementing-tasks addresses feedback from the review skill and iterates until the sprint is approved. You cannot skip a stage without producing an obviously empty file, and an obviously empty file is a thing a human or another agent can notice.

This is the ordinary discipline of separation of duties applied to a context window. The engineer skill writes an implementation report. The reviewer skill writes feedback. Neither writes the other's file. When one model plays both seats in sequence, the artifact boundary is most of what keeps the second pass from being a rubber stamp, because the reviewer's input is the report and the diff, not the reasoning trace that produced them.

Three levels are a token budget

Each skill uses a three-level structure, and the level sizes are the point:

1. index.yaml, roughly 100 tokens, holding metadata, triggers, and dependencies.
2. SKILL.md, roughly 2000 tokens, holding framework instructions and workflows.
3. resources/, holding external references, templates, checklists, and scripts, loaded only when a workflow reaches for them.

Read that as a cost model rather than a filing convention. The always-resident cost of knowing a skill exists is about 100 tokens. The cost of activating it is about 2000. The cost of its long tail is paid only on demand. Seven roles at level 1 is a rounding error against any modern context window; seven roles fully expanded is not. This is progressive disclosure with an explicit price list, and having the price list written down changes what we are willing to add. A new capability that cannot state its level 1 and level 2 footprint is a capability we have not finished designing.

The failure mode this guards against is the one Anthropic describes in Building Effective Agents: complexity added at the framework layer that the model then has to reason around. A skill that dumps its checklists into the always-loaded tier is not more capable. It is more expensive at every unrelated turn.

Personas are register, not credentials

The role definitions in the process document read like job postings. Senior Product Manager with 15 years of experience. Elite Software Engineer with 15 years of experience. Battle-tested DevOps Architect with 15 years of crypto and blockchain infrastructure experience. Paranoid cypherpunk for the security auditor.

We want to be exact about what those strings do, because it is easy to overclaim. They are not credentials, and they do not add knowledge the model lacks. They select a register: which vocabulary, which default concerns, which questions get asked before work starts. "Fifteen years" is shorthand for "do not produce the tutorial-grade version of this artifact." "Paranoid cypherpunk" is shorthand for "assume the adversary reads the source."

Treating them as anything more than register selection is where teams get hurt. A persona string does not make a review thorough. The acceptance criteria in sprint.md and the explicit checks in the reviewing skill (completeness, testing, security, performance, and whether previous feedback was actually addressed) do that work. The persona sets tone; the checklist sets floor. When we have cut something from a skill, it has usually been persona prose, and the checklist has usually survived. That pattern matches the general advice in Claude Code best practices: specific, checkable instructions outperform atmosphere.

The mailbox in the middle

The a2a/ directory is the part we would keep if we had to throw everything else away. Two files, one written by the engineer role and one written by the reviewer role, both living in the repo and both surviving the session that produced them.

An agent-to-agent message that is a file has properties a conversational handoff does not. It is diffable, so we can see whether feedback changed between rounds or repeated itself. It is greppable across repos, so recurring feedback becomes evidence about the skill rather than an anecdote about one sprint. It outlives the context window, so a resumed session inherits the same grievance list the previous one left. And it is reviewable by a human who was not present, which matters when one operator is accountable for a fleet of repos.

The cost is real: a pipeline that writes six or seven durable artifacts per feature can produce documents nobody reads. We treat unread artifacts as a defect in the pipeline, not a tax to be accepted. The test we apply is whether a downstream stage consumes the file. The PRD is consumed by architecture and planning. The SDD is consumed by planning. sprint.md is consumed by implementation and updated by review. reviewer.md and engineer-feedback.md are consumed by each other. Anything with no downstream reader is ceremony, and ceremony is the thing that makes agent pipelines look productive while shipping nothing.

What the shape decides for us

Conway's law applies with unusual directness here, because the communication structure is not emergent. We wrote it. Seven roles with fixed outputs means the system will be described in seven documents whether or not seven documents are warranted, and a small change will still walk the whole path unless we let it skip stages deliberately.

We do let it skip. The pipeline is the default for work with real design uncertainty, not a mandatory rite for a config change. Knowing which mode we are in is the operator's judgment call, and it is the judgment call we get wrong most often. That is an open problem in the fleet, not a solved one.

The provenance record on the process document says trust_tier: verified, status: promoted. That means it describes what runs, not what we intend to build. We think that distinction is worth more than any of the role descriptions in it.

The night shift signs the log in a hand nobody recognizes.

Get the next post

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

Post history

• 2026-09-07: enrich the-handoff-is-a-file: 2 plate(s) + shadow captions + feature image (standing admin preapproval (pending-laws 2026-07-19))

№ 3496