Epics and Stories
Stadium 8 organises your application into epics, and each epic into stories. This structure decides what gets built and in what order, so it helps to understand it before you review a plan.
What an epic is
Section titled “What an epic is”An epic is a major feature area: a part of the application users would recognise as a distinct thing. User authentication, a product catalogue, order management, an admin panel and a dashboard are all epics.
A good epic is something you could ship on its own. If two epics are so tangled you can’t imagine one without the other, they’re one epic. If an epic would take weeks to build, it’s two.
How epics are planned
Section titled “How epics are planned”Claude plans every epic up front, during Intake. It breaks your requirements into epics, works out which epics depend on others, and checks that every requirement is assigned to one. You approve the whole plan before any code is written.
The approved plan is saved to generated-docs/epic-plan.md. Each epic waits there as a draft until its stories are planned and it’s built. Claude builds the epics in an order that respects their dependencies.
What a story is
Section titled “What a story is”A story is one thing a user can do, or one thing the system does that a user would notice. It lives inside an epic.
A well-scoped story changes something a user would notice. If finishing a story leaves nothing visibly different, it’s a technical task. If it would take days and touch every part of the feature, it’s an epic.
Stories are always written from the user’s point of view.
Good stories:
- “A user can log in with their email and password.”
- “The product list shows a ‘no results’ message when no items match the filter.”
- “An admin can deactivate a user account from the user management table.”
Not stories:
| Example | Why it doesn’t work |
|---|---|
| ”Set up the authentication middleware” | Technical task. Not user-visible. |
| ”Build the product management system” | Too large. This is an epic. |
| ”Improve the dashboard” | Too vague. What specifically should change? |
How stories are approved
Section titled “How stories are approved”When an epic comes up for building, Claude proposes its stories and how it will check each one. You review them, ask for changes, and approve. This is your main chance to add edge cases, cut scope, or split a story that has grown too large.
Each story also carries a short manual test checklist. You work through it in your browser once the epic is built. See Manual Test Checklists.
For help writing clear stories, see Writing Requirements That Work.