A5.4 · module hub
Agent stories
A user story names a need and a “so that.” An agent story is its executable counterpart: a Directive the agent runs, and an Acceptance gate that closes it. The fourth part of the brief.
A user story tells you who needs what and why. It is not, on its own, a unit an agent can
finish — it has no stop signal. An agent story adds two halves: a
Directive (the tasks the agent runs) and an Acceptance gate (the runnable
check that closes it). The Portal's f6.1.llms.md carries four —
F6.1-AS1 through F6.1-AS4. Pick a user story on the right
to see its executable counterpart, all practised on the Portal.
User story → agent story · pick a user story
The fourth part: a story made executable
A4 wrote the spec and a user story for each slice — who needs what, and why. A user story is a unit of value, but it is not a unit of agent work: it names an outcome, not the steps to reach it, and it has no stop signal. The fourth part of the brief supplies both. An agent story implements exactly one user story and carries two halves — a Directive, the tasks the agent runs, and an Acceptance gate, the runnable check that closes it.
The Portal's f6.1.llms.md carries four, built in task-topology order:
F6.1-AS1 boots the app (T1–T3 + the health route),
F6.1-AS2 renders a user's courses (T4–T6),
F6.1-AS3 holds the boundary, and F6.1-AS4 makes the
endpoint self-heal and fail soft. The request lifecycle these stories assemble is built in the companion
course at Phoenix · the request lifecycle; this module reads
the stories as a unit of agent work, not the code.
The principle
An agent story is a user story made executable: a Directive the agent runs and an Acceptance gate that closes it. The Directive sets the work in motion; the gate says when it has arrived.
On the Portal
f6.1.llms.md's F6.1-AS1 directs T1→T3 and closes on
GET /health 200 plus the boot order; F6.1-AS3 closes on an
empty invariant grep over apps/portal_web/lib/.
A user story says what someone needs; an agent story says what the agent does and how the work proves itself done.
Both halves, or the story cannot close
The two halves are not optional. A Directive with no gate is open-ended work: the agent builds, but nothing
says when to stop or whether it arrived. A gate with no Directive is a check with no work behind it. Each of
the four Portal stories carries both. The figure below splits all four into their Directive and their
Acceptance gate, then drops F6.1-AS3's gate to show what is lost.
F6.1-AS3 — Hold the boundary — directs the agent to keep the
controller calling only Portal, and closes on
grep -rE "Portal\.Engine|Repo|GenServer\.call" apps/portal_web/lib/ returning
nothing. Remove that grep and the agent still has work to do — but no signal the boundary held.
Four agent stories · Directive + gate
The first dive, A5.4.1 · Directive and gate, takes one story
(F6.1-AS2) and reads its two halves up close. Start there, below.
The three dives
Each dive takes one part of the agent story, in the arc pair → prove → close: the Directive-and-gate pairing, the worked first-two-stories execution plan, and the acceptance gates that close each story. Read them in order — A5.4.1 starts.
Directive and gate
Every agent story is a Directive plus a closing Acceptance gate. A Directive alone is open-ended; the gate tells the agent — and the reviewer — when it has arrived.
The first two stories
The worked execution plan — story → agent story → tasks → files → command → gate — that proves the path to a verified change is short and unambiguous.
Acceptance gates
The runnable check that closes a story. A story with no gate is flagged incomplete — it can never close, so the agent's “done” never becomes provably done.
After A5.4, the next module — A5.5 · The comprehensive implementation prompt — assembles references, requirements, topology, and these agent stories into the one prompt an Author runs. Return to the A5 module navigation to continue.
References
The story tradition the agent story extends — a user story made executable — and the agent guidance behind closing each unit on a gate.
Sources
- Cohn, M. — User Stories Applied — the user story as a unit of value with a "so that"; the agent story makes that unit executable.
- Jeffries, R. — INVEST in Good Stories, and SMART Tasks — a good story is independent and testable; the Acceptance gate is what makes "testable" runnable.
- Anthropic — Building effective agents — giving an agent a bounded unit of work with a clear closing check.
Related in this course
- A5.4.1 · Directive and gate
- A5.4.2 · The first two stories
- A5.4.3 · Acceptance gates
- A5.3 · Execution topology — the task DAG these stories map onto.
- A5 · The agent brief
- Companion · Phoenix request lifecycle — where F6.1-AS1–AS4 are built.