bmad-epics-and-stories — Claude Code skill
bmad-epics-and-stories is a Claude Code skill that turns PRDs and architecture into epics and self-contained stories for development handoff.
MIT 138 installs ★ 493 updated 2026-06-20
npx skills add aj-geddes/claude-code-bmad-skills --skill bmad-epics-and-stories -a claude-codeWhat bmad-epics-and-stories does
The skill shards requirements into epics—each a shippable slice of value—then compiles each story into a standalone context object (~8K tokens). Every story includes a user story statement, numbered acceptance criteria, subtasks mapped to criteria, Dev Notes with citations to source docs, a testing strategy (no execution), cross-story dependency map, and an explicit list of files and modules this story may touch. That owned scope list is the lever for parallel, conflict-free development.
Three modes: create new epics and stories, update an existing story, or validate a draft against the contract. A story must fit one dev-day (2–8 hours); split if larger. No story points. The skill never writes application code, runs tests, or builds. The final artifact is a story file marked ready-for-dev.
What it helps with
- transform PRD into an ordered epic map with dependencies
- split an epic into day-sized stories
- write a story with acceptance criteria tied to source requirements
- declare owned file scope so parallel teams work conflict-free
- validate a story draft for completeness and contract compliance
Example prompts for the agent
- Shard the PRD into epics and generate stories for Claude Code
- Break this epic into stories sized for one dev-day
- Validate the story: are all acceptance criteria and dependencies declared
How to install bmad-epics-and-stories
1Skills CLI (Vercel)
npx skills add aj-geddes/claude-code-bmad-skills --skill bmad-epics-and-stories -a claude-code2Manually: put the files in place
~/.claude/skills/bmad-epics-and-stories/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/bmad-epics-and-stories/
1Skills CLI (Vercel)
npx skills add aj-geddes/claude-code-bmad-skills --skill bmad-epics-and-stories -a codex2Manually: put the files in place
.agents/skills/bmad-epics-and-stories/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add aj-geddes/claude-code-bmad-skills --skill bmad-epics-and-stories -a cursor2Manually: put the files in place
.cursor/skills/bmad-epics-and-stories/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install aj-geddes/claude-code-bmad-skills bmad-planning-orchestrator/skills/bmad-epics-and-stories2Manually: put the files in place
.github/skills/bmad-epics-and-stories/SKILL.md1Skills CLI (Vercel)
npx skills add aj-geddes/claude-code-bmad-skills --skill bmad-epics-and-stories -a gemini-cli2Platform CLI
gemini skills install https://github.com/aj-geddes/claude-code-bmad-skills --path bmad-planning-orchestrator/skills/bmad-epics-and-storiesManually: put the files in place
.devin/skills/bmad-epics-and-stories/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add aj-geddes/claude-code-bmad-skills --skill bmad-epics-and-stories -a opencodeClaude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
Step by step, with commands for each platform: How to install skills in Claude Code: five ways
Questions about bmad-epics-and-stories
How do I install bmad-epics-and-stories in Claude Code?
Run npx skills add aj-geddes/claude-code-bmad-skills --skill bmad-epics-and-stories -a claude-code, then open ~/.claude/skills/bmad-epics-and-stories/SKILL.md.
What does bmad-epics-and-stories do?
It shards a PRD and architecture into epics, then each epic into stories. A story is a complete context object with acceptance criteria, dev notes (sourced from input docs), testing strategy, and dependency map. The skill does not write code or run tests—it's the final planning step before code handoff.
What is Owned File/Module Scope and why does it matter?
It's an explicit list of files and modules that a story may modify. This list lets parallel teams avoid merge conflicts: if two stories declare disjoint scope, they can run in parallel safely.
Source text
SKILL.md · MIT
---
name: bmad-epics-and-stories
description: |
Solutioning flagship — shards a PRD + architecture into epics.md and individual
{epic}.{story}.{slug}.story.md context objects, the LAST planning artifact before
external dev handoff. Each story is a self-contained ~8K-token compiled context object:
Dev Notes with SOURCE CITATIONS back to prd.md/architecture.md, Acceptance Criteria,
Tasks/Subtasks mapped to ACs, Testing strategy, Dependency Maps, an explicit Owned
File/Module Scope list (the lever for parallel-conflict-free scheduling), and Learnings
from Previous Stories. Sized to one dev-day; split if larger; NO story points.
Use when the user says "shard the PRD", "create epics", "break the PRD into epics",
"break this epic into stories", "create stories", "create a story", "draft story files",
"generate the story for X", "prepare stories for dev", "mark the story ready for dev",
"validate this story", or "what stories are in this epic". Three intents: Create new
epics/stories, Update an existing story, or Validate a draft against the contract.
allowed-tools: Read, Write, Edit, Bash, Glob, Grep, TodoWrite
---
# BMAD Epics & Stories
**Track-adaptive sharding.** Turn approved planning docs into the executable backlog: one
`epics.md` map plus per-story context objects. This is the final planning step — the next
thing that touches a story is an **external dev tool**, not this plugin.
**Persona flavor:** the Architect (Winston) shards; the PM (John) confirms scope. Lightweight
flavor only — this is a workflow.
## Scope Law (read first)
This skill PLANS. It NEVER writes application code, runs tests, lints, checks coverage, or
builds. The last artifact it emits is a story file marked `status: ready-for-dev`. Acceptance
Criteria, a Testing **strategy**, and Dev Notes are planning outputs you author. Executing
tests or writing implementation is out of scope — plan it and hand it off. If tempted to
"implement" or "run the suite", STOP.
## Inputs (load these first)
| File | Why |
|------|-----|
| `bmad-output/project-context.md` | Project constitution — load every run |
| `bmad-output/prd.md` | Functional requirements, epic intent |
| `bmad-output/architecture.md` | Tech stack, components, module boundaries |
| `bmad-output/ux-design.md` (if present) | UI acceptance details |
| `bmad-output/decision-log.md` | Threaded decisions to honor |
| existing `bmad-output/stories/*.story.md` | Learnings + ID continuity |
Output folder default: `bmad-output/` (honor user override). Stories go in
`bmad-output/stories/`, the map in `bmad-output/epics.md`.
## Three Intents
- **Create** — shard PRD+architecture into `epics.md`, then compile story files.
- **Update** — revise an existing story (scope, ACs, learnings). Respect LOCKED sections.
- **Validate** — check a draft story against the Context Object contract; report gaps.
Ask which intent if ambiguous. Do not silently regenerate existing stories.
## Tracks (never numbered levels)
Pick interactively; the heuristic suggests, the user confirms.
- **Quick Flow** (1-15 stories) — tech-spec only; shard straight to stories, thin `epics.md`.
- **BMad Method** (10-50+) — PRD + Architecture (+ optional UX); full epic map then stories.
- **Enterprise** (30+) — adds Security + DevOps story streams.
## Sizing Rule (count-based, no points)
A story must be **small enough for one agent session — roughly 2-8h, one dev-day max.**
If a story is larger, **split it**; never inflate scope to fill a sprint. There are NO
Fibonacci points, NO velocity, NO burndown. Delivery is tracked by COUNT: stories remaining
vs. completion rate. See [REFERENCE.md](REFERENCE.md) for the split heuristics.
## Workflow — Create
1. **Load context** — read the inputs above; note the chosen track.
2. **Derive epics** — group PRD requirements into epics (each a shippable slice of value).
Write `bmad-output/epics.md` from [templates/epic.template.md](templates/epic.template.md):
epic goal, in-scope requirements (cited), ordered story list, cross-epic dependencies.
3. **Confirm** the epic map with the user before compiling stories.
4. **Generate IDs** — `bash ${CLAUDE_PLUGIN_ROOT}/skills/bmad-epics-and-stories/scripts/generate-story-id.sh <epic-number>`
gives the next `{epic}.{story}` and a slug stub. Filename: `{epic}.{story}.{slug}.story.md`.
5. **Compile each story** as a CONTEXT OBJECT from
[templates/story.template.md](templates/story.template.md). It MUST be self-contained
(~8K tokens) so a dev agent needs no other file. Fill every section:
- **Story** — as-a / I-want / so-that.
- **Acceptance Criteria** — numbered, testable. **LOCKED.**
- **Tasks/Subtasks** — checkboxes, each mapped to an AC via `(AC: #N)`.
- **Dev Notes** — concrete guidance WITH SOURCE CITATIONS (e.g.
`[Source: architecture.md#auth-service]`, `[Source: prd.md#FR-12]`). **LOCKED.**
- **Testing** — strategy only (what to verify, test types, fixtures). No execution. **LOCKED.**
- **Dependency Maps** — Blocked-by / Blocks other story IDs.
- **Owned File/Module Scope** — explicit list of paths this story may touch. This is the
lever for conflict-free parallel scheduling; declare it precisely. See REFERENCE.md.
- **Learnings from Previous Stories** — carried forward from completed siblings.
- **Dev Agent Record** — leave EMPTY for the external dev tool.
6. **Scope-conflict check** — run the shared checker over the new/edited stories:
`bash ${CLAUDE_PLUGIN_ROOT}/scripts/scope-conflict-check.sh bmad-output/stories/`
Resolve any overlapping Owned Scope before marking stories parallel-safe.
7. **Set status** — `backlog` while drafting; flip to `ready-for-dev` only when every section
is complete, ACs are testable, scope is declared, and the conflict check is clean.
8. **Log + hand off** — append decisions to `decision-log.md`; tell the user which stories are
`ready-for-dev` and hand off to the external dev tool. Do NOT implement.
## Workflow — Update / Validate
- **Update:** locate the file by ID, edit non-locked sections freely. Changing a LOCKED
section (AC/Dev Notes/Testing) requires explicit user confirmation and a decision-log entry.
Re-run the scope-conflict check if Owned Scope changed.
- **Validate:** for each story confirm all required sections exist, every Task cites an AC,
Dev Notes carry source citations, Owned Scope is non-empty and conflict-free, and status is
legal. Report a checklist of pass/fail — do not edit unless asked.
## Status Lifecycle
`backlog → ready-for-dev → in-progress → review → done`. This skill only owns
`backlog` and `ready-for-dev`. Everything past handoff belongs to external dev tooling.
## LOCKED Sections — contract
Acceptance Criteria, Dev Notes, and Testing are LOCKED. The story template states that
external dev tools MUST NOT edit them. They are the compiled, cited source of truth.
## Subagent Strategy
**Pattern:** parallel section/story generation — one agent per epic or per independent story.
| Agent | Task | Output |
|-------|------|--------|
| Agent N | Compile stories for Epic N as full context objects | `bmad-output/stories/N.*.story.md` |
Coordination: write shared context (PRD/architecture/track/sizing rule) to
`bmad-output/context/sharding-context.md`; fan out one agent per epic; on return, the main
context runs the scope-conflict check across ALL stories and resolves overlaps before any
story is marked `ready-for-dev`.
Example prompt:
```
Task: Compile stories for Epic 2 (Payments) as context objects.
Context: read bmad-output/context/sharding-context.md.
For each story: number AC, map every Task to an AC (AC: #N), cite Dev Notes to
prd.md/architecture.md sections, declare an explicit Owned File/Module Scope, leave
Dev Agent Record empty. Size to one dev-day; split anything larger. NO story points.
Output: bmad-output/stories/2.*.story.md, status: backlog.
```
## Reference
- [REFERENCE.md](REFERENCE.md) — sharding method, sizing/split rule, scope-declaration discipline.
- [templates/epic.template.md](templates/epic.template.md)
- [templates/story.template.md](templates/story.template.md)
- `${CLAUDE_PLUGIN_ROOT}/skills/bmad-epics-and-stories/scripts/generate-story-id.sh` — next `{epic}.{story}` ID + slug.
- `${CLAUDE_PLUGIN_ROOT}/scripts/scope-conflict-check.sh` — shared Owned-Scope overlap checker.
> ---
> Part of the **BMAD Planning & Orchestrator** plugin — a Claude Code harness for the **BMAD Method** by the **BMAD Code Organization** (https://github.com/bmad-code-org/BMAD-METHOD). Implements the spirit of `bmad-create-epics-and-stories`. All methodology credit belongs to the BMAD Code Organization.
© aj-geddes · MIT · aj-geddes/claude-code-bmad-skills