The shape of a machine brief

The two dives before this one taught how an agent reads a brief: links before prose, then every reference exact. Those two rules add up to a shape — a fixed skeleton every machine brief follows. The Portal's real f6.1.llms.md has five sections, in this order: ## References, ## Requirements, ## Execution topology, ## Agent stories, and ## Comprehensive implementation prompt.

The order is the convention. References comes first because the agent reads its sources before it acts on anything that cites them. Requirements come next — numbered, testable statements. Then the execution topology fixes the runtime shape and the build order. Then the agent stories make each unit of work executable with a closing gate. The implementation prompt comes last because it runs everything above it. The brief opens with the line “Read the references first, satisfy the requirements, build in task-topology order, and close each agent story on its gate” — the skeleton stated as an instruction.

Moving the links to the top is only half the shape. The other half is what the brief drops. A document written for a person carries motivation, history, and prose transitions — the story a reader needs to follow the work. A machine brief keeps the lines the agent acts on and removes the rest. The same five sections carry the same decisions under both readers; the machine brief sheds only the narrative.

Toggle the meter below between a person doc and a machine brief over the same five sections of f6.1.llms.md. The decision lines — the references, the numbered requirements, the task DAG, the gates — stay constant. Only the narrative lines change: the person doc keeps every one; the machine brief removes them all.

The Portal's web bootstrap ships from f6.1.llms.md, and its skeleton is the worked instance of the shape. Its top-of-file line states the order as an instruction; the five ## headings then follow it exactly. Every other brief in the companion Phoenix chapter — the routing rung, the persistence rung, the LiveView rung — uses the same five sections in the same order. The sameness is the value: an agent that has read one brief knows where the sources are, where the requirements are, and where the prompt that runs them sits, in every brief after it.

# f6.1.llms.md — the fixed five-section skeleton (the machine-brief shape)
#
# > Read the references first, satisfy the requirements, build in task-topology
# > order, and close each agent story on its gate. This brief is self-contained.
#
## References                         # the links block — read first
## Requirements                       # F6.1-R1…R8, numbered and testable
## Execution topology                 # the runtime tree, the T1→T7 task DAG, the file list
## Agent stories                      # F6.1-AS1…AS4, each a Directive + an Acceptance gate
## Comprehensive implementation prompt  # runs the stories in task order, ends on the gates

A machine brief is a fixed five-section skeleton: References, Requirements, Execution topology, Agent stories, the implementation prompt — links first, narrative removed. The sameness is the value: every f6.N.llms.md reads the same way, so an agent never re-learns where to look. This closes A5.1, the convention. The next module fills the skeleton's first two parts — the references the agent reads, then numbered, testable requirements.

Primary sources for the machine-readable brief form and the value of writing an explicit, well-structured task for an agent, and where this dive's convention and the brief it grounds on are defined in the course.