Why a brief layer

A spec is the source of truth, not a build plan. A4 produced a spec that is correct by definition — but a spec is not code, and an agent without a brief would decide what the Operator must own.

A spec defines what and why and done; it does not say how to build it — which sources to read, in what runtime shape, in what order, against which gates. Hand a spec straight to an agent and the agent fills those gaps with its own choices, and those choices are the Operator's to make. The brief is the layer that fills them first. Toggle the figure on the right to see how the same content re-shapes from a document for a person into a brief for an implementer.

A spec is not code What the brief fixes On the Portal References

Document for a person, or brief for an agent · toggle the reader

Agent brief — references front-loaded: 5 of 5 (links first, every reference exact); narrative lines removed: 4 (the agent reads the decision, not the story). A brief is documentation re-shaped for an implementer: links first, prose second.

A spec is not code

A4 produced a spec that is correct by definition: acceptance criteria, Given/When/Then, invariants, and traceability, so “done” is a closure over traced, executed checks. That is the source of truth for what a rung is and how to know it is right. It is not, on its own, a build plan. The spec says nothing about which sources the implementer reads, what runtime shape the code takes, in what order it is assembled, or which commands prove each step.

Hand that spec to a Claude Author with nothing else, and the Author must supply those answers itself. Which library? Which supervision shape? Build the view before the route, or after? Those are decisions — and they are the Operator's decisions, the same ownership A1 drew the whole course around. An agent left to make them is no longer implementing a specified slice; it is improvising an architecture. The brief exists so the agent never has to.

The spec

Defines what and why and done — the single source of truth, edited only by feedback. It answers whether a rung is correct, not how to build it.

The brief

Tells an implementer how to build it — references first, the runtime shape, the build order, the proof gates. Written fresh per rung, it derives from the spec and redefines nothing.

This is the seam A6 inherits: A5 produces a built increment that passes its own acceptance, and A6 is the work that makes it survive production. First the spec must become code — which is this chapter.

What the brief fixes

The brief closes four how-to-build decisions a bare spec leaves open. The sources to read (every reference, links first). The runtime shape — the process tree and how a request flows. The build order — the task DAG that keeps the app compiling at every step. The proof gates — the command that closes each unit of work. Fix all four and the agent implements rather than decides; leave any open and the agent fills it, taking a call the Operator should own.

Toggle the meter below between a bare spec and a spec wrapped in a brief, over the four real decisions the Portal's f6.1.llms.md fixes. With the spec alone, all four are open to the agent; with the brief, none are.

How many decisions are left to the agent · toggle the input

Spec only — how-to-build decisions left open to the agent: 4 of 4. With nothing but the spec, the agent decides the sources, the runtime shape, the build order, and the proof gates — the Operator's calls, taken by the implementer.

A brief fixes the four decisions a spec leaves open — so the agent implements the plan instead of inventing one.

On the Portal

The Portal's web bootstrap ships from a real brief, f6.1.llms.md. Its references list the Phoenix endpoint, router, and controller docs, the upstream Portal facade contract the controller calls, and the design system every page renders in — links first. Its requirements (F6.1-R1 through F6.1-R8) are numbered and testable, each traced to a user story. Its execution topology pins the runtime tree (two supervisors, the endpoint booting after the engine) and the build-order task DAG (T1 through T7). Its agent stories each carry an Acceptance gate. None of that is in the spec; all of it is in the brief.

# f6.1.llms.md — the how-to-build decisions the spec leaves open, fixed for the agent
#
# References (links first):
#   Phoenix endpoint/router/controller hexdocs · the Portal facade contract · f0.md (the design system)
#
# Requirements (numbered, testable):
  F6.1-R1  the Endpoint plug stack + the LiveView socket
  F6.1-R4  the controller calls only Portal.courses_of/1; a domain error renders 422
  F6.1-R7  no module under apps/portal_web/lib/ names Portal.Engine, Repo, or GenServer.call
#
# Execution topology — the task DAG (each step leaves the app compiling):
  T1 deps + entrypoint → T2 endpoint → T3 supervision → T4 router → T5 controller → T6 view → T7 verify
#
# Each agent story closes on a gate — e.g. AS1: GET /health returns 200; the tree boots store → engine → endpoint.

The principle

An unbriefed agent fills the spec's how-to-build gaps with its own choices — and those choices are the Operator's to make. The brief fills them first, so none are left.

On the Portal

f6.1.llms.md front-loads the references, pins the two-supervisor topology and the T1–T7 task order, and names each agent story's gate — so the Author implements the fixed plan, not an architecture of its own.

A4 wrote what to build and how to know it is right; the brief writes how the Author builds it, leaving the agent no decision the Operator must own.

Recap — the brief is the bridge from spec to code

A spec is correct by definition but is not runnable on its own; an agent handed only a spec would decide the sources, the runtime shape, the build order, and the proof gates — the Operator's decisions. The brief is the layer that fixes all four, so the agent implements a specified slice rather than improvising an architecture. The next dive walks what the chapter covers — the five parts of an .llms.md and the eight modules ahead.

Next in A5: What the chapter covers — the five parts of an .llms.md brief and the eight modules that teach them.

References

Primary sources for writing machine-readable briefs and the value of a fixed contract, and where the spec this dive builds on and the loop it runs within are defined in the course.

Sources

llmstxt.org — The /llms.txt convention — a links-first, machine-readable document an agent reads before prose; the form the brief takes.
Anthropic — Building effective agents — why a coding agent needs an explicit, well-structured task rather than an open-ended goal.
Hunt, A. & Thomas, D. — The Pragmatic Programmer — design by contract: pinning every decision the builder must not have to invent.

Related in this course

A4 · The spec layer — the spec a brief wraps.
A5 · The agent brief — the chapter landing.
A1.03 · The Author/Operator loop — the ownership line the brief preserves.
A0.2.2 · The four artifacts — the per-rung documents the brief assembles.
Companion · Phoenix (F6) — the real chapter whose f6.1.llms.md this dive grounds on.