Skip to content

Plan

Plan an Epic's Stories

Use Sofia, the Product Owner (bmad-agent-po), to turn one epic into stories an agent can build one session at a time. Plan only the epic you will build next; later epics stay thin until their turn, so what the first one teaches can still change them.

  • The initiative is cut into epics and you are about to start one
  • An epic’s stories were never planned, or a change made them stale
  • You want some stories built with nobody watching

Name the epic:

/bmad-agent-po refine the door check-in epic

Sofia reads the epic and the initiative lines it covers, then answers in one message sized to the initiative. On a small initiative, the message is a single question: does this epic need anything before its stories? On a larger one, she says what is already settled for its stories and names each open point with her pick: settle it with you now, plan a spike when only code can answer it, or leave it to the stories.

She also reminds you that you can flesh the epic out first: your own notes, a PRD from John on the epic, a bmad-ux or bmad-architecture run on the epic, or research with bmad-deep-recon. A run you choose lands in the epic’s folder and becomes its companion.

If the epic still has open screen or flow questions, Sally runs bmad-ux on it first; if it has open technical questions, Winston runs bmad-architecture after her. Ask each to cover only what is new or different, before Sofia plans the stories.

Sofia then writes the epic’s Requirements, each citing the initiative line it comes from, such as R1 (parent R3), and marks the epic refined: true.

Ask for its stories:

/bmad-agent-po plan the door check-in epic's stories

Sofia drafts the whole epic, brings you every unknown that must be settled first, and presents each story with what it delivers, how it will be verified, the requirement ids it covers, and what it waits on. Before you approve, fresh agents check that every requirement is covered, that what the stories wait on has no loops, and that no prerequisite is missing, such as collisions, shared setup, and handoffs. Adjust size, order, and prerequisites until you approve; the check runs again when you add, remove, or reorder stories.

Each story is one step toward the epic’s Done when, sized for one build session; it need not be something a user sees. Sofia merges a story whose setup outweighs its work, and splits rather than shrinks: a story that would leave something for now, as a placeholder, or wired later becomes two. Stories that touch the same code form one ordered lane, and an interface two lanes share gets a stub as its own early story. Tests go in every story; the only test story is a closing end-to-end suite.

The first story is the tracer bullet: the thinnest path through every layer the epic touches, with its setup as a hitl step. The story you are least sure of comes next. An epic of more than three stories closes with a “Refactor sweep” story that waits on the others and only cleans up what the epic deferred; decline it and Sofia records why.

Eight to twelve stories is a typical epic, not a limit. Past that, Sofia offers to split the epic first, and you decide. A team that sizes epics differently can change the guideline with tickets_story_count under [workflow] in _bmad/custom/bmad-agent-po.toml.

The stories become entries in the epic’s tickets/tickets.toml, in build order. No story file is written: a build plans each story’s acceptance criteria when it starts, so detail is not written months before it is used. A story can wait on a story in another epic, or on a whole epic.

Build the risky and foundational stories yourself, with bmad-build: they settle the patterns later stories follow. Stories the plan fully settles can go to bmad-build-auto, whose questions nobody answers during a run.

  • Mark an entry hitl = true when a person does part of its work, and name that part.
  • When the epic will run unattended, Sofia asks for plan_checkpoint and done_checkpoint per entry and proposes one on risky stories. Build and Verify shows how to honor them.

Before any unattended run, have Sofia check each story with you:

/bmad-agent-po review the stories

A story needs no refining before an attended build; the build questions you itself. Refine it when you want to review a story first or it will run unattended:

/bmad-agent-po refine story 2.3

Sofia writes a file for it from its entry; from then on, the file is the source of truth. A bug, a ticket with no epic, and an entry marked refine = true always get full acceptance criteria first.

Ask what is ready, about the epic or the whole initiative:

/bmad-agent-po what's next?

Sofia lists what is ready to refine, ready to start, in progress, and blocked, and why. Then go to Build and Verify.

The planning leaves:

  • The epic file with its Requirements, marked refined: true
  • epic-<slug>/tickets/tickets.toml: every story in build order, each with a permanent id, a description, a verify check, covers, and after
  • A file only for the stories you refined

Entry fields, ids, and statuses are listed in The Ticket Tree.