Brief the agent for the Portal

A5.1–A5.7 built the brief part by part and named the practice and the thesis behind it. A5.8 runs the whole sequence on a real engine rung: write the brief, run the Author, verify the increment against the Definition of Done.

The workshop is the chapter's proof — the method, run end to end, produces a verified increment, not a description of one. It briefs the Portal's real engine rung F5.2 — Model the Portal domain in the worked shape of f6.1.llms.md, then runs it and checks the result. Pick a part of the brief on the right to assemble it for the rung; the brief is runnable only when all five parts are present.

The full pass The worked rung The three dives References

Assemble the brief · step through the five parts

1 of 5 parts present: references. Four parts still to assemble before the brief is runnable.

The full pass

A5 has built one brief, part by part, across seven modules. A5.8 runs the whole of it on a real rung, in three stages. Brief the rung assembles the five parts for one engine rung; a brief missing a part is not runnable. Run the agent runs the implementation prompt in task order, the tree compiling after each step, supervising each step's gate. Verify the increment reads the output against the spec's Definition of Done, not the agent's self-report.

Each stage closes on a gate, and the next stage starts only when the prior one's gate passes. Step the control below through the three stages; the readout reports how many gates have passed and what the workshop leaves at its end — a verified increment, gated at each stage. The default state shows the first stage gated; the remaining two are still pending.

The full pass · three gated stages, in order

Brief stage gated — 1 of 3. Two stages remain: run the prompt, then verify against the Definition of Done.

the principle

Run the whole A5 sequence on a real rung — brief, run, verify — a first full pass from spec to running code, each stage gated before the next begins.

on the Portal

The workshop briefs a real engine rung from pragmatic/f5.* (F5.2), runs the implementation prompt, and verifies the increment against its Definition of Done.

The workshop is the chapter's proof — the method, run end to end, produces a verified increment, not a description of one.

The worked rung

The rung the workshop briefs is F5.2 — Model the Portal domain, the engine chapter's second rung. Its brief f5.2.llms.md is a real, complete .llms.md: References (Elixir structs and @enforce_keys, typespecs, the upstream Portal.Store and Portal.ID), requirements F5.2-R1…R6, the T1→T6 task topology and the touched-file list, agent stories F5.2-AS1…AS3, and the comprehensive implementation prompt in six numbered build steps.

Its requirements are the kind the workshop writes. F5.2-R1 names seven entity structs — User, Session, Course, Lesson, Page, Enrollment, Progress — each with @enforce_keys, a defstruct, and a @type t, so a partial record cannot be built. F5.2-R3 documents the public API per context, each function with an @spec, all others private: Accounts.user/1, Catalog.course/1, Learning.enroll/2, Learning.courses_of/1. The worked web rung this all leads to is built in the companion course at the Phoenix request lifecycle.

# f5.2.llms.md — the requirement the workshop writes (R3)
F5.2-R3  Learning.enroll/2 :: {:ok, %Enrollment{}} | {:error, atom}
         Learning.courses_of/1 :: [%Enrollment{}]

# the worked first write — one context function over the store + a minted id
u  = Portal.ID.generate("USR")
crs = Portal.ID.generate("CRS")
Portal.Learning.enroll(u, crs)   # => {:ok, %Enrollment{progress: 0}}
Portal.Learning.courses_of(u)     # => [%Enrollment{}]

The brief fixes the field lists, the id namespaces, and the return shapes, so the Author implements the rung rather than deciding it. Portal.ID.generate/1 mints a branded id; the real F5 surfaces (Portal.Store, Portal.ID.new/1) are cited only as f5.2.llms.md names them.

The three dives

Each dive runs one stage of the pass, in order: brief the rung, run the agent, verify the increment. Read them in order — A5.8.1 assembles the five parts for the rung.

A5.8.1built

Brief the rung

Assemble the five parts of the brief for one real engine rung — references, requirements, topology, agent stories, the prompt. A brief missing a part is not runnable.

A5.8.2built

Run the agent

Run the implementation prompt in task order, the tree compiling after each step, and supervise each step's gate — the build never advances on a broken step.

A5.8.3built

Verify the increment

Review the output against the spec's Definition of Done, not the agent's self-report — the increment is verified, not merely reported done.

A5.8 closes the chapter: the brief, the practice, and the thesis (A5.7 · Pragmatic Programming with Claude Agents) run end to end on a real rung. It hands A6 — Reliability & correctness a built increment to harden. Return to the A5 module navigation to continue.

References

The sources this workshop draws on for turning a fixed brief into a verified increment, and where the engine the rung models and the worked web rung are built in the course.

Sources

Hunt, A. & Thomas, D. — The Pragmatic Programmer — the tracer-bullet discipline of turning a fixed contract into a built, verified increment end to end.
Anthropic — Building effective agents — briefing, running, and reviewing a coding agent over a well-specified task.
llmstxt.org — The /llms.txt convention — the links-first, machine-readable form the engine brief the workshop writes follows.

Related in this course

A5.8.1 · Brief the rung
A5.8.2 · Run the agent
A5.8.3 · Verify the increment
A5 · The agent brief — the parent chapter the workshop runs.
A5.7 · The thesis — the value the workshop demonstrates.
Companion · Functional Programming in Elixir — the course that builds the engine the rung models.
Companion · Phoenix (F6) — the chapter whose f6.1.llms.md is the worked brief shape.