| name | bmad-epic-dev |
| description | Orchestrate full epic development end-to-end. Use when the user says 'dev this epic' or 'implement epic [number]'. |
Epic Dev
Overview
This skill drives an entire epic from backlog to done — creating story specs, implementing each story, and running adversarial code review — all with fresh LLM context per step. It parses the epic's dependency tree to optimize execution order and parallelize where safe.
Act as a disciplined build orchestrator. You don't write code or specs yourself — you delegate to specialized skills (bmad-create-story, bmad-dev-story, bmad-code-review) via subagents, track progress, and relay decisions back to the user.
Args:
- Epic number (e.g.,
13) — required
--commit-policy=<auto|ask|skip> — controls git commit behavior (default: auto)
auto: commit automatically at prescribed pointsask: prompt user before each commitskip: never commit (user handles commits manually)
--skip-confirmations — suppress soft-gate pauses between phases (for experienced users resuming a known-good epic)
Model configuration:
Different phases use different LLMs by design — code review must run on a different model than the one that wrote the code to avoid self-review bias.
| Phase | Role | Model | Reasoning |
|---|
| Step 0 (planning) | Design & decisioning | Opus 4.6 | High reasoning for dependency analysis and orchestration |
| Phase A (create-story) | Story spec creation | Opus 4.6 | High reasoning for comprehensive context extraction |
| Phase B (dev-story) | Implementation | Opus 4.6 | High reasoning for code generation and problem solving |
| Phase B (code-review) | Adversarial review | ChatGPT 5.4 | Medium reasoning, different model prevents self-review blind spots |
When spawning subagents, pass the appropriate model. If a specified model isn't available in the environment, warn the user and fall back to whatever model is available — but always log when code review runs on the same model as development.
Core contract:
- Every sub-skill runs in a fresh subagent (clean LLM context)
- Sub-skill subagents run autonomously but relay "decision needed" questions back to you for the user
- Code review subagents MUST use a different LLM model than the development subagents
- On any failure: halt with resume instructions — re-invoking with the same epic number picks up where it left off
sprint-status.yaml is the checkpoint — story statuses determine what's been done and what remains- Phase B finalization is a script, not a doc rule. After review, run
python3 ./scripts/finalize-story.py {story-key}. Never hand-edit sprint-status to done. The script refuses unless the story file has a Code Review Record with a Review Model Used, then sets story Status: and sprint-status together. After each layer run --check-epic {N} and HALT on failure.
- Interactive by default: report progress after each story, soft gates between phases
- Phase A (story specs) parallelizes by dependency layer via concurrent subagents
- Phase B (implementation) parallelizes by dependency layer via git worktrees — each story gets its own branch and working directory, merged back after review
On Activation
Load available config from {project-root}/_bmad/config.yaml and {project-root}/_bmad/config.user.yaml (root level and bmm section). If config is missing, let the user know bmad-bmb-setup can configure the module at any time. Use sensible defaults for anything not configured.
Resolve:
implementation_artifacts — where story files and sprint-status.yaml liveplanning_artifacts — where epic source files liveuser_name, communication_language
Intent guard: Before proceeding, confirm the user intends full epic orchestration. If the input looks like a single story reference (e.g., "13.2" without "epic"), clarify: "Did you mean to implement the full epic, or just story 13.2? For a single story, use bmad-dev-story instead."
Then read fully and follow ./references/phase-logic.md.
