jonnifyagile agents
jonnify / Agile Agent Workflow / A5 · The agent brief / A5.6 · Running Claude agents well

A5.6 · module hub

Running agents well

A5.1–A5.5 wrote the brief and folded it into one runnable prompt. The brief is complete; what remains is the practice of running it: brief, supervise, review — a loop the human owns around a prompt the agent runs.

The agent runs the prompt; the human owns the gate. Three moves frame the practice: brief the agent with a complete .llms.md so it implements rather than decides, supervise the run against the task gates, and review the output against the spec's Definition of Done — never the agent's self-report. Pick a practice on the right to read its role; the module grounds on the Portal's real F6 ship prompts, all practised on the Portal.

The three practices Self-report vs the gate The three dives References

The practice around the prompt · pick a move

one prompt · a loop the human owns: brief, supervise, review MOVE 1 Brief — hand the agent a complete .llms.md so it implements rather than decides MOVE 2 Supervise — watch the run against the gates let a passing stage run, intervene on a failing one MOVE 3 Review — read against the Definition of Done not the agent's self-report
Practice 1 · Brief — hand the agent a complete, unambiguous .llms.md so it implements rather than decides. The loop around one prompt: set up, watch, check — and the human owns every move but the run.

The practice around the prompt

The five parts of the brief assemble into one prompt an Author can run. Assembling it is the end of A5.1 through A5.5. Running it is a separate craft, and it is the human's. Three moves carry it. Brief the agent with a complete .llms.md, so every decision the spec fixed is restated and none is left for the agent to invent. Supervise the run against the task gates, letting a passing stage proceed and intervening on a failing one. Review the output against the spec's Definition of Done.

The third move carries the rule the whole module turns on. A Claude Author can report that it is done; a report is not a check. Review reads the work against the gates the spec named, not the message the agent sent. The value of the practice is in the gates, not in how many agents run in parallel: the Portal's F6 ship prompts run a lead-team Director-in-loop precisely so a human stands at each gate.

This hub frames the practice; the three dives below go deep on each move — briefing, supervising, and reviewing. The reviewing dive carries the liveness gate the content figure below introduces.

Self-report against the gate

The move that separates a good review from a credulous one is the source it checks against. The Portal's F6.7 ship prompt makes the point exactly. A rung's suite can be fully green and still leave the running server unproven, because the test endpoint runs with the server switched off. The F6.7 brief states it verbatim: “mix test runs server:false (config/test.exs), so a green suite does NOT prove the dev server boots.” The Director's ratify gate restates it: “mix test alone does NOT satisfy the liveness criterion (the endpoint runs server: false under test).”

So the reviewer runs the gate the report cannot. For F6.7 that gate is the liveness check: boot the node and confirm /health returns 200, then run the rung's live two-window update. The same shape recurs across the F6 prompts — the LiveView rung (F6.6) the ship prompt builds is interactive only when a booted server is serving it, which a green suite never demonstrates. Select a review source below: the readout reports what each checks against, and whether it proves the server boots.

The review source · the report or the gate

what does the review check against? SOURCE A The self-report “done — tests green” proves: the suite passes mix test runs server:false server boots? unproven a message, not a check SOURCE B The Definition of Done boot node · curl /health runs: the liveness check /health → 200, live update server boots? proven a check the report cannot give
Run the gate — mix test is green but runs server: false; the liveness check (the node boots, /health is 200) is the one the review must run, not the report. Self-report proves: tests green. Liveness proven: yes — the node was booted.
the principle

Brief, supervise, review — and review against the Definition of Done, never the agent's self-report.

on the Portal

The F6.7 ship prompt requires the liveness check at review: a green mix test proves nothing about a running server (server: false under test), so the reviewer boots the node and curls /health.

Running an agent well is a loop the human owns — the agent runs the prompt; the human owns the gate.

The three dives

Each dive takes one move of the practice, in the order of a run: brief → supervise → review. Hand the agent a complete brief, watch the run against the gates, then review the output against the Definition of Done. Read them in order — A5.6.1 starts.

A5.6.1built

Briefing

Hand the agent a complete, unambiguous brief so it implements rather than decides — the spawn carries only the rung delta; the discipline is durable.
A5.6.2built

Supervising

Watch the run against the task gates: let a passing stage run, intervene on a failing one, and bound the retries before the human takes over.
A5.6.3built

Reviewing

Read the output against the spec's Definition of Done, not the agent's self-report — trying to refute, with the liveness check the green suite never runs.

After A5.6, A5.7 · Pragmatic Programming with Claude Agents names the thesis behind the practice: the agent's value is real on a well-specified slice, and the human owns the judgement. Return to the A5 module navigation to continue.

References

The agent-engineering sources this practice draws on, and where the brief it runs and the loop it runs within are defined in the course.

Sources

Related in this course