Skip to main content
skill CX Codex

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

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add aj-geddes/claude-code-bmad-skills --skill bmad-epics-and-stories -a claude-code
Open on GitHub

What 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-code

2Manually: put the files in place

~/.claude/skills/bmad-epics-and-stories/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/bmad-epics-and-stories/

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

Similar skills

All skills for Agent setup: memory, context, orchestration →

From the same set11

The whole set →
bmad-research bmad-research — a skill that conducts structured market, competitor, technology and domain research from live sources, producing a cited research report. Run it before product planning or architecture decisions. CX Codex +1 138installs bmad-brainstorm bmad-brainstorm runs structured ideation sessions using SCAMPER, SWOT, and 5 Whys. Delivers an organized markdown report ready for project planning. CX Codex +1 130installs bmad-tech-spec bmad-tech-spec generates a focused tech spec for small-scope work instead of a full PRD and architecture pair. Use it when requirements are clear, scope fits 1-15 stories, and you need one planning artifact before writing stories. CX Codex +1 114installs bmad-spec The bmad-spec Claude Code skill turns rough notes, a PRD, or a transcript into a compact SPEC.md with five sections. It activates when a project needs a clear problem statement and scope. CX Codex +1 108installs bmad-readiness-check The bmad-readiness-check Claude Code skill checks whether planning documents agree before implementation starts. Ask for it to validate requirements, architecture, and epics for build readiness. CX Codex +1 107installs bmad-document-project The bmad-document-project Claude Code skill scans an existing codebase in read-only mode to generate project-documentation.md. It maps runtime dependencies and entry points before downstream planning. CX Codex +1 104installs bmad-sprint-planning The bmad-sprint-planning Claude Code skill sorts stories by dependency and prepares a development handoff plan. Ask it to arrange stories, map parallel waves, or create sprint-status.yaml. CX Codex +1 104installs bmad-investigate The bmad-investigate Claude Code skill investigates bugs and turns findings into a case file. Invoke it to trace a reported failure, update an open investigation, or check a draft before handoff. CX Codex +1 102installs

Project sponsors

Companies that keep this analytics open