Directive and gate

An agent story is a user story made executable. Where a user story carries a “so that,” an agent story carries two halves — a Directive and an Acceptance gate.

The Directive is what the agent does: the tasks it runs, in order, each tied to a requirement. The Acceptance gate is how the work proves itself done: a runnable check the reviewer can re-run. A Directive without a gate is open-ended work — the agent builds, but nothing says when it has arrived. Toggle the figure on the right to read each half of one real Portal agent story, F6.1-AS2.

The two halves Directive without a gate On the Portal References

One agent story, two halves · toggle the half

F6.1-AS2 · Directive — 3 tasks the agent runs: T4 the :browser pipeline + the courses route, T5 CourseController.index/2 over Portal.courses_of/1, T6 CourseHTML from assigns. The Directive lists what the agent does.

The two halves

A user story names a person, a need, and a reason: as a learner, I want to see my courses, so that I know what to study next. It is the right unit for a person to read — it carries a “so that” that says why the work matters. It is not, on its own, a unit of agent work: it does not say which tasks to run, nor how to know they are done.

An agent story is that same user story made executable. It keeps the user story it implements, and adds two halves. The Directive lists the tasks the agent performs — in task-DAG order, each tied to the requirement it satisfies. The Acceptance gate is the runnable check that closes the story: a render, a status code, an empty state, a grep. The Directive is what the agent does; the gate is how the work — and the reviewer — knows it is done.

The Directive

The tasks the agent runs, in order, each citing the requirement it satisfies. It sets the agent in motion over a fixed plan — the agent implements it, it does not invent it.

The Acceptance gate

The runnable check that closes the story — a real render, a status, an empty state, a grep. The gate is run, not interpreted; it is the line at which the work is provably done.

A5.4 covers the brief's fourth part: turning each user story into a unit of agent work with an unambiguous closing check. This dive isolates the pairing; the next walks the first two stories end to end.

A Directive without a gate is open-ended

Drop the gate and the Directive still reads as work — the agent runs its tasks, the tree compiles, a page renders. What is missing is the signal that the work is done. Without a gate, “done” is the agent's own judgement, and the reviewer has nothing to re-run. The gate is the line between “the agent thinks it is finished” and “the work is provably finished.”

Toggle the figure below between both halves and a Directive alone, over the four agent stories of the Portal's f6.1.llms.md (F6.1-AS1 through F6.1-AS4). With each story's gate present, all four can close. Strip the gate and the count of stories that can close drops to zero — each one has work to do, but no signal it is complete.

Can the story close · toggle the gate

Directive + gate — agent stories that can close: 4 of 4. With its gate, AS2 closes when a known user renders their courses; the Directive runs, the gate confirms.

The Directive sets the agent in motion; the gate tells it — and the reviewer — when it has arrived.

On the Portal

The Portal's web bootstrap brief, f6.1.llms.md, writes each agent story as a Directive and a gate. F6.1-AS2 — render a user's courses — is the clearest. Its Directive lists three tasks; its gate lists three checks. The Directive names tasks T4 through T6; the gate names a real render, an empty state, and an assigns-only template — checks the reviewer re-runs against the built code, not the agent's report.

# f6.1.llms.md — F6.1-AS2 — Render a user's courses [implements F6.1-US2]
#
# Directive (what the agent does):
  T4  add the :browser pipeline + get "/courses/:user_id", CourseController, :index
  T5  implement CourseController.index/2 over Portal.courses_of/1
  T6  build CourseHTML + index.html.heex rendering from assigns
#
# Acceptance gate (the check that closes it):
  ✓ a known user renders their courses
  ✓ no enrollments renders an empty state
  ✓ the template references only assigns

The Directive is the “build this”; the gate is the “and here is how the work proves itself.” The controller the Directive specifies is the request lifecycle's controller layer in the companion course — CourseController.index/2, calling only the Portal.courses_of/1 facade.

The principle

Pair every Directive with an Acceptance gate. A Directive alone is open-ended work — the agent builds, but nothing says when to stop. The gate is the runnable check that closes it.

On the Portal

f6.1.llms.md's F6.1-AS2 directs T4–T6 and closes on a real courses_of/1 render plus the empty-state and assigns-only checks.

A user story says what someone needs; an agent story says what the agent does and how the work proves itself done.

Recap — a Directive and a closing gate

An agent story is a user story made executable: a Directive that lists the tasks the agent runs, and an Acceptance gate that closes it with a runnable check. Both halves are mandatory — a Directive without a gate is open-ended, and the agent's “done” means nothing the reviewer can re-run. The next dive walks the first two stories end to end, proving the path from a user story to a verified change is short and unambiguous.

Next in A5.4: The first two stories — the worked execution plan that proves the path from story to verified change is short and unambiguous.

References

Primary sources for the user story an agent story makes executable, the testable closing check it must carry, and where the agent story this dive grounds on is built in the companion course.

Sources

Cohn, M. — User Stories Applied — the user story whose executable counterpart an agent story is, with its “so that” the gate makes checkable.
Wake, B. — INVEST in Good Stories — testable: a good story carries the check that closes it; the agent story's Acceptance gate.
Anthropic — Building effective agents — an agent needs an explicit, closeable task, not an open-ended goal.

Related in this course

A5.4 · Agent stories — the module hub.
A5 · The agent brief — the chapter landing.
A4 · The spec layer — the user stories an agent story makes executable.
Companion · The request lifecycle (F6) — the chapter whose f6.1.llms.md this dive grounds on.