/bmad-epics-and-stories

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.

Wo