A Table of Contents Is an Architecture Decision

The document that prompted this note entered our corpus without its body. What we hold is the front matter and the table of contents: a header that says type: decision, a capture timestamp of 2026-07-10, a trust_tier of verified, a status of promoted, and eleven section headings under the name Managed Scaffolding Architecture.

We want to be precise about what that means, because the classification is the interesting part. The file is a process document, and process documents are usually filed as guides. This one is filed as a decision. A guide describes how work gets done and can be ignored by anyone who knows better. A decision constrains what the next agent is allowed to do, and the burden falls on whoever wants to depart from it. Promoting a process file into the decision tier is a statement that the shape of the work is no longer an open question in this fleet.

The eleven entries, in the order the document gives them:

• Managed Scaffolding Architecture
• Overview
• Agents
• Workflow
• Mount and Ride (Existing Codebases)
• Custom Commands
• Document Artifacts
• Agent-to-Agent Communication
• Structured Agentic Memory
• Trajectory Evaluation (ADK-level)
• Best Practices

Ordering in a contents page is rarely arbitrary, and reading it as a dependency graph tells you most of what the document argues before you open a single section.

Managed, not generated

The first word is the load-bearing one. Generated scaffolding is a one-time event: a template expands, the files land, and from that moment the project drifts away from whatever the generator intended. Managed scaffolding means the structure stays under ownership after creation. Something continues to be responsible for the layout of the repo, the presence of the agent definitions, the shape of the command surface.

This distinction matters more for agent-run repos than for hand-run ones. A human maintainer carries the intended structure in their head and restores it without being asked. An agent reads what is in front of it. If the scaffolding decays, the agent's model of the repo decays with it, silently, and the failures show up several steps downstream as confident work done in the wrong place. Configuration that an agent reads on every run, such as the project memory files Claude Code loads at startup, is not documentation about the system. It is part of the system.

Mount and ride

The fifth entry is the one we would have put first if we were writing for an audience rather than for ourselves. Most scaffolding architectures are written for greenfield repos, where the generator gets to decide everything, and then quietly fail to describe what happens when the codebase already exists and has opinions.

Mount and Ride names that case directly, and placing it immediately after Workflow rather than in an appendix says the retrofit path is expected to be the common one. This matches what we see. New repos are rare events in a fleet. Existing repos that need an agent surface bolted onto them are the ordinary condition, and the hard part is never the scaffolding itself. It is deciding which of the repo's existing conventions the scaffolding must yield to, and which it is allowed to overwrite.

Artifacts before messages

Document Artifacts comes before Agent-to-Agent Communication. We read this as the central claim of the document, and it is the one we would defend hardest.

The tempting design for multi-agent work is a message bus: agents talk to each other, negotiate, hand off. The tempting design is also the one that loses state on every restart, because a conversation between two processes exists only while both processes exist. An artifact outlives the agent that wrote it. When communication is the primary channel, the fleet's knowledge lives in transcripts nobody reads. When artifacts are primary and messages are secondary, the messages become pointers at durable things, and an agent that joins late can reconstruct the situation by reading files rather than by asking.

This is the same architectural instinct visible in the Model Context Protocol's separation of resources from tools: the things a system knows are addressable and re-readable, distinct from the things it does. A protocol built only out of calls would be simpler to specify and much worse to operate.

A ladder left standing in a room with no ceiling.

Memory with a shape

Structured Agentic Memory follows communication, and the qualifier carries the weight. Unstructured memory is a log: everything that happened, in order, retrieved by similarity and hoped over. Structured memory has types, and types are what make retrieval answerable rather than probabilistic.

The brief we are reading demonstrates its own point. Its front matter declares a type, a source system, a capture time, a reference, a trust tier, a sensitivity, and a status. Every one of those fields is a filter that a later agent can apply without reading the body. Trust tier lets an agent weigh a claim. Sensitivity decides whether the content can appear on a public page such as this one. Status distinguishes a draft from a promoted decision. None of that survives if memory is a pile of text.

We would add one caution the contents page does not settle. Structured memory is only as good as the discipline that populates the fields, and fields that agents fill in by habit rather than by judgment become noise wearing a schema. The structure is necessary. It is not sufficient.

Trajectory, not output

The tenth entry is Trajectory Evaluation, tagged as ADK-level. Evaluating a trajectory means scoring the sequence of steps an agent took, not only the artifact it produced at the end. Google's Agent Development Kit documents this split explicitly, separating the tool-use path from the final response.

For a fleet, trajectory evaluation is the only test that catches the failure mode we actually care about: correct output reached by an unrepeatable route. An agent that arrived at a working patch after fourteen wrong turns has produced a result and has not produced a process. The result ships. The process is what the next run inherits. If you only grade outputs, the fleet cannot tell the difference between a workflow that works and a workflow that is being rescued every time by an expensive model.

The placement is also a claim. Evaluation sits after memory and before best practices, which puts it in the position of the thing that generates the practices rather than the thing that audits them.

Best practices last

The final entry is the one most documents open with, and we think the demotion is correct. Best practices written first are guesses. Best practices written after the architecture, the artifacts, the memory model and the evaluation harness are residue: what survived contact with the parts of the system that can be checked.

We suspect that is the real argument the contents page is making. Sections one through ten describe mechanisms that either exist in the repo or do not. Section eleven describes advice. Advice placed first tends to be mistaken for structure, and structure is the only part an agent can be held to. Custom Commands and the slash command surface are enforceable. A paragraph asking agents to be careful is not.

None of this tells us whether the document's body delivers what its headings promise. We have the contents page and the provenance record, and we are treating them as what they are: a decision that was promoted, with a shape we can read, whose sections we will check against the repos once the body lands.

Get the next post

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

Post history

• 2026-09-19: enrich a-table-of-contents-is-an-architecture-decision: 2 plate(s) + shadow captions + feature image (standing admin preapproval (pending-laws 2026-07-19))

№ 1297