jonnifyagile agents
jonnify / Agile Agent Workflow / A5 · The agent brief / How you learn and build it

A5 · orientation dive 3

How you learn and build it

Write the brief part by part, run the Author, then review the output against the spec's Definition of Done — never the agent's self-report. A critical review reads the code against the gates; a self-report reads the agent's word for it.

The hardest discipline in running an agent well is review. An agent reports its own success, and that report is not evidence. The course's own practice — adversarial verification, the gate-invisible checks — reads the built tree against the spec's gates. Toggle the figure on the right: each acceptance gate a critical review actually runs closes; a gate taken on the agent's word stays open.

Review the output · toggle how you read it

the four acceptance gates of F6.1-AS4 + the verification gate unknown id → empty state (200), never a 500 closed injected %Portal.Error{} → renders 422 closed kill the endpoint → it restarts; a later request succeeds closed grep for Portal.Engine / Repo / GenServer.call is empty closed acceptance gates closed by this review: 4 of 4
Critical review — acceptance gates closed: 4 of 4. Each gate is run against the built tree (the 422 path, the empty state, the supervisor restart, the invariant grep). Review against the spec, never the self-report.

The four moves

Building a rung with an agent here is four moves. Write the brief part by part — references, requirements, topology, agent stories, the prompt. Run the Author by pasting the implementation prompt; it builds in task order to the gates. Review the built tree against the spec's Definition of Done, gate by gate. Intervene when the review finds a gap: feedback edits the spec, not the code, and the Author re-runs — the same adapt move A1.03 named.

Three of the four moves are the Operator's: writing the brief, reviewing the output, and deciding when to intervene. Only the run belongs to the Author. The ownership line A1 drew holds through the whole build: the agent implements; the human keeps the judgement and the acceptance.

The four moves · pick one

write run review intervene Move 1 · write — Operator assemble the brief part by part, references to prompt
Move 1 of 4 · write — the Operator assembles the brief part by part: references, requirements, topology, agent stories, the prompt. The judgement stays with the Operator; the agent implements.

Four moves — write, run, review, intervene — and three of them are the Operator's; only the run belongs to the agent.

Review against the spec, never the self-report

The review move carries the weight. A Claude Author finishes a build and reports that it passed; that report is a claim, not evidence. A critical review does not read the claim — it reads the built tree against the spec's Definition of Done, running each acceptance gate the brief named. Does an unknown id render the empty state rather than crashing? Does an injected error render a 422, never a 500? Does the endpoint restart when killed? Is the master-invariant grep empty? Each gate the review runs closes; each gate it takes on the agent's word stays open.

This is why the course's own fan-out practice verifies adversarially: a different reader than the one that built it tries to refute the result, defaulting to fail when uncertain. The gate-invisible checks — clamp spacing, the intended parent of a breadcrumb, a real link under every source — are exactly the gaps a self-report would miss and a critical review catches.

A6 takes this further: where this dive reviews that a built increment passes its own acceptance, A6 hardens that increment against failure it has not yet seen — a malformed input, a crashed process, an invariant proven across generated inputs rather than asserted on a chosen few.

On the Portal

The method lands in the A5.8 workshop: brief the Portal's engine chapter and run a first full pass from spec to running code. The Author builds; the review then runs each acceptance gate the brief named against the built tree before the increment is accepted. For the web bootstrap, those gates are concrete and in the brief: a known user renders their courses, an unknown or malformed id renders the empty state, an injected %Portal.Error{} renders a 422, killing PortalWeb.Endpoint restarts it, and the master-invariant grep over apps/portal_web/lib/ is empty.

# f6.1.llms.md — the verification step (T7): the review runs each gate against the built tree
  ✓ mix compile is clean; the app boots; GET /health is 200
  ✓ a known user renders their courses; an unknown/malformed id renders the empty state
  ✓ an injected %Portal.Error{} renders a 422 — never a 500
  ✓ killing PortalWeb.Endpoint restarts it under :one_for_one; a later request succeeds
  ✓ grep -rE "Portal.Engine|Repo|GenServer.call" apps/portal_web/lib/ is empty
#
# the review reports each result against the Definition of Done — not the agent's word that it passed.

The principle

An agent reports its own success; that report is not evidence. Review the built work against the spec's gates, gate by gate — not the agent's word.

On the Portal

The A5.8 workshop briefs the engine chapter and runs the Author; the review then runs each f6.1 acceptance gate — the 422 path, the supervisor restart, the master-invariant grep — against the built tree before the increment is accepted.

Run the agent, then review against the spec's Definition of Done — the acceptance stays with the Operator, gate by gate.

Recap — write, run, review, intervene

The method is four moves — write the brief part by part, run the Author, review the built tree against the spec's Definition of Done, and intervene by editing the spec when the review finds a gap. The review is the discipline that carries the weight: an agent's self-report is a claim, and a critical review reads the code against the gates instead. The A5.8 workshop runs the whole method on the Portal's engine chapter to produce a first verified increment. The next chapter, A6, hardens that increment to production quality.

Next: A6 · Reliability and correctness — taking the built increment and making it survive a malformed input, a crashed process, and an invariant proven across generated inputs rather than asserted on a chosen few.

References

Primary sources for running and reviewing a coding agent, and where the loop the review runs within and the next chapter that hardens the increment sit in the course.

Sources

Related in this course