Epics & Stories

If BMAD Board is the visual cockpit for your hybrid team, then the Epics and Stories views are its main instrument panel. This is where the plan you made during solutioning becomes something you can see, touch, and move — one story at a time, all the way to Done.

This page explains what those two views show, how a story travels through its lifecycle, and how a single click hands work to an AI agent.

Where the board gets its data

You never hand-type epics and stories into BMAD Board. It reads them.

When you open a project, the board scans the project's _bmad/ directory — the installed BMAD tooling and configuration — and discovers your epics and stories from there. The board is a reader and launcher, not a separate source of truth: your epics live in your planning artifacts, your story specs live under _bmad-output/, and the board reflects them. Change a story on disk and the board keeps up.

That's the key mental model: the board mirrors your project's real state. It doesn't invent structure; it visualises the structure the method already created.

The Epics view

An epic is a bucket of related value — a meaningful chunk of the product that groups a set of stories. The Epics view shows those buckets at altitude, so you can think about what a release delivers before you drop into the details.

Use this view when you want the big picture: which epics exist, roughly how far along each one is, and where to focus next. When you're ready to work, you move down into the stories inside an epic.

The Stories view

A story is a single unit of work — the granular, buildable piece that an AI agent can take from spec to shipped code. The Stories view lays these out as cards, each showing the one thing you most need to know: which phase of its lifecycle the story is in right now.

Note: BMAD Board does not render a kanban board with lane columns. There are no "columns" to drag cards between. Story flow is expressed as phases a story advances through — a lifecycle, not a set of buckets. If you've seen older screenshots with lane columns, that view was removed.

The story lifecycle

Every story moves through the same five phases, in order:

Backlog → Ready → In Progress → Review → Done

Each phase has an icon on the card and a BMAD slash command behind it. When you click a phase, BMAD Board opens the embedded terminal and launches that command with your chosen LLM provider — so advancing the story is putting an agent to work.

Phase	Icon	Meaning	Command launched
Backlog	○	Create the story specification	`/bmad-create-story`
Ready	◐	Start developing the story	`/bmad-dev-story`
In Progress	◑	Continue development	`/bmad-dev-story`
Review	◕	Run code review	`/bmad-code-review`
Done	●	Story completed	—

Here's the same lifecycle as a picture, including the loop that makes it work:

Reading each phase

Backlog (○) — The story is an idea with a title. Clicking it launches /bmad-create-story, which writes the full story spec file: the requirement, acceptance criteria, and the context an agent will need to build it well. This is the foundation everything else stands on.
Ready (◐) — The spec is written and the story is ready to build. Clicking it launches /bmad-dev-story, and your engineer agent starts implementing against the spec.
In Progress (◑) — Development is underway. Clicking it launches /bmad-dev-story again as a fresh pass to continue the work. Real development takes more than one breath, so you'll return here as needed.
Review (◕) — Time to check the work. Clicking it launches /bmad-code-review, which reviews the change adversarially — bugs, edge cases, and whether the acceptance criteria are actually met. Edge-case hunting is handled inside the review, so there's no separate step for it.
Done (●) — The story is finished and reviewed. There's no command here; Done is the terminal state.

Advancing a story

Advancing a story is simply clicking its phase. There's no drag, no separate "move" gesture — the phase is the action. Each click:

Opens a terminal tab (or reuses the story's tab).
Launches the phase's BMAD command with your selected LLM provider.
Records the session so you can revisit or resume it later.

The In Progress ↔ Review loop

The single most important thing to internalise about the lifecycle is that In Progress and Review are two halves of one loop. Development and review aren't a one-way street:

You develop in In Progress, then click Review to have the change scrutinised.
If the review surfaces problems, you go back to In Progress, let the dev agent fix them, and click Review again.
You loop between the two until the story is genuinely right — then it flows to Done.

This loop is where quality gets built in. A story reaches Done not because time ran out, but because the review came back clean. Read more about the mechanics in the implementation phase.

Tip: Clicking In Progress starts a fresh development session rather than resuming the previous one — a clean pass after a review, so the agent isn't anchored to an earlier state. Your prior sessions are never lost; they're all in Session History.

Around the edges of the lifecycle

The story lifecycle is the centre of gravity, but a few neighbouring features complete the picture.

Capturing ideas: the Intake view

Not every good idea arrives as a fully formed story. The Intake view is where you capture raw ideas and inbound requests before they're shaped into epics and stories. It's the front door — a place for "we should probably do X" to land so it isn't lost, ready to be turned into real work when its time comes.

Closing out an epic: retrospective and quality gate

Stories reach Done individually, but epics get a proper close-out. When an epic's stories are complete, two things happen at the epic level:

Retrospective (/bmad-retrospective) — a structured post-epic review that extracts lessons and assesses how the epic went, so the next one goes better.
TEA quality gate — the Master Test Architect (Murat, 🧪) applies a quality gate at epic close, tracing coverage and rendering a gate decision (/bmad-testarch-trace).

Both operate on the epic, not on any single story, which is why they don't appear as phases on a story card. Learn how they work in quality and testing.