
bmad-skills
BMAD methodology skills - configurable pipeline for story delivery
- GitHub stars
- 41
Install
/plugin install bmad-skills@bmad-skillsRun it inside Claude Code after adding the marketplace with /plugin marketplace add terryso/claude-bmad-skills.
Contents
Discovered from sourceSkills 3
BMAD Epic Pipeline (Worktree Edition)
Deliver all incomplete user stories in Epic {ARGUMENT} using configurable pipeline, each story developed in isolated worktree and merged only after tests pass.
Pre-step: Determine Epic Number
If no epic number is provided ({ARGUMENT} is empty):
- Read
_bmad-output/implementation-artifacts/sprint-status.yaml(ordocs/sprint/sprint-status.yaml) - Find all stories with status not
done(format:X-Y-story-name) - Extract Epic numbers X from these stories
- Select the smallest Epic number as
{ARGUMENT} - Output:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
📌 Auto-selected Epic: {ARGUMENT} (has incomplete stories)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Example:
- Status file has
3-2-llm-prompt-template: backlog,3-3-xxx: in-progress,4-1-xxx: done - Incomplete Epics: 3
- Auto-select Epic: 3
Difference from bmad-epic-worktree
| Feature | bmad-epic-worktree | bmad-epic-pipeline-worktree |
|---|---|---|
| Story delivery | bmad-story-worktree | bmad-story-pipeline-worktree |
| Workflow config | Fixed 8-step flow | Configurable via workflow-steps.md |
| Customization | Limited | Full pipeline customization |
| Safety level | High | High |
Execution Strategy
- Read all incomplete stories under the Epic
- Sort by Story number ascending
- Execute
/bmad-story-pipeline-worktreefor each story sequentially - Only start next story after previous one completes
- If any story fails, stop and preserve current state
Execution Flow
Step 1: Collect Epic Story List
Read sprint-status.yaml, collect all incomplete stories under specified Epic:
Task(
subagent_type: general-purpose,
description: "Collect Epic {ARGUMENT} story list",
prompt: "Read _bmad-output/implementation-artifacts/sprint-status.yaml (or docs/sprint/sprint-status.yaml), collect all stories for Epic {ARGUMENT}:
1. Filter entries with key format '{ARGUMENT}-Y-story-name'
2. Keep only stories with status not 'done'
3. Sort by Story number Y ascending
4. Return story list with format:
- Story number: 'X.Y', Story name, Current status
- Number of incomplete stories
If no incomplete stories found, return 'Epic {ARGUMENT} has no incomplete stories'"
)
Progress output:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
📋 Epic {ARGUMENT} - Story List
Story | Name | Status
-------|-------------------------|--------
{ARGUMENT}.1 | {story-name-1} | backlog
{ARGUMENT}.3 | {story-name-3} | in-progress
...
📊 Total: {N} incomplete stories
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Step 2~N: Deliver Stories Sequentially
For each incomplete story, execute in order:
For story {STORY_NUM} (i-th of N total):
Execute /bmad-story-pipeline-worktree {STORY_NUM}
Wait for completion before continuing to next story
Each story delivery progress:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
🔄 Story [{i}/{N}]: {STORY_NUM}
📝 Name: {story-name}
⏳ Executing configurable pipeline...
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
[... Execute bmad-story-pipeline-worktree phases ...]
Phase 1: Create Worktree
Phase 2: Configurable Pipeline (from workflow-steps.md)
Phase 3: Merge Branch
Phase 4: Update Status
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
✅ Story [{i}/{N}]: {STORY_NUM} Complete
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
If any story fails:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
❌ Story [{i}/{N}]: {STORY_NUM} Failed
⚠️ Stopping subsequent story delivery
📁 Please handle manually before continuing
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Final Delivery Report
All complete:
╔════════════════════════════════════════════════════════╗
║ 🎉 BMAD Epic Pipeline Complete! ║
╠════════════════════════════════════════════════════════╣
║ Epic: {ARGUMENT} ║
║ ║
║ ✅ Story 1: {story-1} - done ║
║ ✅ Story 2: {story-2} - done ║
║ ... ║
║ ✅ Story N: {story-N} - done ║
║ ║
║ 📊 Total: {N}/{N} stories completed ║
║ 🎯 Epic status: done ║
╚════════════════════════════════════════════════════════╝
Partial completion (has failures):
╔════════════════════════════════════════════════════════╗
║ ⚠️ BMAD Epic Pipeline - Partial Completion ║
╠════════════════════════════════════════════════════════╣
║ Epic: {ARGUMENT} ║
║ ║
║ ✅ Story 1: {story-1} - done ║
║ ✅ Story 2: {story-2} - done ║
║ ❌ Story 3: {story-3} - failed ║
║ ⏸️ Story 4: {story-4} - not started ║
║ ... ║
║ ║
║ 📊 Progress: {completed}/{total} stories completed ║
║ 📁 Failed story: {failed-story} ║
║ 💡 Handle failed story then re-run to continue ║
╚════════════════════════════════════════════════════════╝
Error Handling
If any story delivery fails:
- Stop subsequent story delivery
- Preserve failed story's worktree (if any)
- Output failure information and completed progress
- Prompt user to handle manually
Resume delivery:
# 1. Manually fix failed story
cd {WORKTREE_PATH}
# Fix issues...
git add . && git commit -m "fix: resolve issues"
cd {ORIGINAL_REPO_PATH}
git merge feature/story-{STORY_NUM}
git worktree remove {WORKTREE_PATH}
# 2. Re-run epic delivery, will auto-skip completed stories
/bmad-epic-pipeline-worktree {ARGUMENT}
Configuration
Pipeline workflow uses bmad-story-pipeline-worktree's configuration.
To customize the pipeline, edit: bmad-story-pipeline-worktree/references/workflow-steps.md
Changes supported:
- Add/remove steps
- Modify step commands
- Reorder steps
- Change descriptions
Relationship with bmad-story-pipeline-worktree
- bmad-epic-pipeline-worktree is the batch version of bmad-story-pipeline-worktree
- Internally loops to call
/bmad-story-pipeline-worktree {story-num} - Each story has independent worktree, independent pipeline, independent merge
- Guarantees sequential execution, next starts only after previous completes
- Each story completion auto-updates: sprint-status.yaml + story design document
- Uses configurable workflow from workflow-steps.md
BMAD Story Pipeline (Worktree Edition)
Complete the delivery pipeline for story {ARGUMENT} using configurable workflow in an isolated git worktree, merge to main branch only after all tests pass.
Pre-step: Determine Story Number
If {ARGUMENT} is empty or not provided:
- Read
_bmad-output/implementation-artifacts/sprint-status.yaml(ordocs/sprint/sprint-status.yaml) to find stories - Find the first story with status "todo" or "in-progress"
- Use that story number as
{STORY_ID} - If no story found, ask user to specify story number
The story number format is typically X-Y (e.g., 1-1, 2-3).
Set STORY_ID = {ARGUMENT} for all subsequent steps.
Difference from bmad-story-pipeline
| Feature | bmad-story-pipeline | bmad-story-pipeline-worktree |
|---|---|---|
| Working method | Develop on current branch | Develop in isolated worktree |
| Code isolation | None | Complete isolation |
| Merge condition | None enforced | Tests pass + fixes complete |
| Workflow config | workflow-steps.md | workflow-steps.md |
| Safety level | Medium | High |
Phase 1: Create Worktree
Do this yourself (not via Task agent):
1. Get current project name, path and branch:
ORIGINAL_REPO_PATH=$(pwd)
PROJECT_NAME=$(basename $(pwd))
CURRENT_BRANCH=$(git branch --show-current)
2. Create new branch name: feature/story-${STORY_ID}
3. Create worktree directory (in sibling directory):
WORKTREE_PATH="../${PROJECT_NAME}-story-${STORY_ID}"
4. Execute git worktree command:
git worktree add -b feature/story-${STORY_ID} "$WORKTREE_PATH" $CURRENT_BRANCH
If branch already exists, use:
git worktree add "$WORKTREE_PATH" feature/story-${STORY_ID}
5. Verify worktree created:
git worktree list
Variables saved for later phases:
ORIGINAL_REPO_PATH- Original repository path (for merge step)WORKTREE_PATH- Worktree pathSTORY_ID- Story number
Progress output:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
✅ Create Worktree
🌿 Branch: feature/story-${STORY_ID}
📁 Path: ${WORKTREE_PATH}
📦 Original: ${ORIGINAL_REPO_PATH}
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Phase 2: Run Configurable Pipeline
Switch to worktree directory first, then run the pipeline.
Read workflow steps from references/workflow-steps.md.
Execute each step sequentially using Task tool (general-purpose agent):
Task(
subagent_type: "general-purpose",
description: "<Step description>",
prompt: "Execute the command: <COMMAND_WITH_STORY_ID>
Return: 1) Step completion status 2) Key outputs 3) Any issues to note"
)
Example Invocations
Step 1 - Create Story:
Task(
subagent_type: "general-purpose",
description: "Create user story {STORY_ID}",
prompt: "Execute /bmad-bmm-create-story {STORY_ID} yolo to create story file. Return: 1) Story ID and Title 2) Created files 3) Any issues"
)
Step 2 - ATDD Tests:
Task(
subagent_type: "general-purpose",
description: "Generate ATDD tests for {STORY_ID}",
prompt: "Execute /bmad-tea-testarch-atdd {STORY_ID} yolo to generate acceptance tests. Return: 1) ATDD checklist 2) Test files created 3) Any issues"
)
Step 3 - Development:
Task(
subagent_type: "general-purpose",
description: "Develop user story {STORY_ID}",
prompt: "Execute /bmad-bmm-dev-story {STORY_ID} yolo to implement story code. Return: 1) Modified files 2) Summary of changes 3) Any issues"
)
Step 4 - Code Review:
Task(
subagent_type: "general-purpose",
description: "Code review for {STORY_ID}",
prompt: "Execute /bmad-bmm-code-review {STORY_ID} yolo for adversarial review. Return: 1) Conclusion (pass/needs-fix) 2) Issues by severity 3) Any blocking issues"
)
Step 5 - Trace Coverage:
Task(
subagent_type: "general-purpose",
description: "Trace test coverage for {STORY_ID}",
prompt: "Execute /bmad-tea-testarch-trace {STORY_ID} yolo for traceability matrix. Return: 1) Coverage percentage 2) Gate decision 3) Any gaps"
)
Execution Flow
For each step:
- Replace
{STORY_ID}with the actual story number in the prompt - Call Task tool with the step's description and prompt
- Wait for completion and capture result
- Output progress:
[X/N] Step Name - Status - If step fails, stop and report error
Progress Display
After each step, output progress:
📊 Pipeline Progress: [X/N] ████████░░░░ 40%
✅ Step X: <Step Name>
Result: <Brief result summary>
Phase 3: Update Status to Done
Before merge, update status in worktree (so changes are included in merge).
After ALL pipeline steps complete successfully:
-
Update sprint-status.yaml:
- Find the story entry
- Change status from
in-progresstodone
-
Update story document (if exists):
- Change
Status:todone - Mark all tasks with ✅
- Change
Progress output:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
✅ Update Status
📝 sprint-status.yaml: ${STORY_ID} → done
📄 Story doc: Status: done, Tasks: ✅
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Phase 4: Merge or Preserve
Critical decision step: Check merge conditions
Merge conditions:
- All pipeline steps completed successfully
- No HIGH/MEDIUM issues (or all fixed)
- Tests pass
If all conditions are met, execute merge yourself:
1. Commit all changes in worktree (including status updates):
cd ${WORKTREE_PATH}
git add .
git commit -m "feat: complete story ${STORY_ID}"
2. Switch back to main repo:
cd ${ORIGINAL_REPO_PATH}
3. Merge feature branch:
git merge feature/story-${STORY_ID} --no-edit
4. Remove worktree:
git worktree remove ${WORKTREE_PATH}
5. Optionally delete feature branch (if not needed):
git branch -d feature/story-${STORY_ID}
6. Verify cleanup:
git worktree list
Progress output:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
✅ Merge Branch
🔀 Merge: feature/story-${STORY_ID} → [current branch]
🗑️ Cleanup: worktree removed
📝 Commit: [hash]
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
If merge conditions not met, preserve worktree for manual handling:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
⚠️ Merge Branch
❌ Merge conditions not met, preserving worktree
📁 Path: ${WORKTREE_PATH}
🔧 Manual handling needed:
- [List unmet conditions]
After handling, manually execute:
cd ${WORKTREE_PATH}
git add . && git commit -m "fix: resolve issues"
cd ${ORIGINAL_REPO_PATH}
git merge feature/story-${STORY_ID}
git worktree remove ${WORKTREE_PATH}
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Final Delivery Report
Successful merge:
╔════════════════════════════════════════════════════════╗
║ 🎉 BMAD Story Pipeline Complete! ║
╠════════════════════════════════════════════════════════╣
║ Story: ${STORY_ID} ║
║ ║
║ ✅ Phase 1 - Create Worktree ║
║ ✅ Phase 2 - Configurable Pipeline ║
║ ✅ Phase 3 - Update Status to Done ║
║ ✅ Phase 4 - Merge Branch ║
║ ║
║ 📊 Status: done ║
╚════════════════════════════════════════════════════════╝
Manual intervention required:
╔════════════════════════════════════════════════════════╗
║ ⚠️ BMAD Story Pipeline - Manual Intervention ║
╠════════════════════════════════════════════════════════╣
║ Story: ${STORY_ID} ║
║ ║
║ ✅ Phase 1 - Create Worktree ║
║ ❌ Phase 2 - Pipeline [failed at Step X] ║
║ ⏸️ Phase 3 - Update Status [not started] ║
║ ⏸️ Phase 4 - Merge Branch [not started] ║
║ ║
║ 📁 Worktree: ${WORKTREE_PATH} ║
║ 💡 Fix the issue and continue manually ║
╚════════════════════════════════════════════════════════╝
Error Handling
If any step fails:
- Stop executing subsequent steps
- Preserve worktree (don't delete)
- Output error information and current state
- Prompt user how to manually fix
- Provide recovery commands
Recovery command examples:
# List all worktrees
git worktree list
# Continue working in worktree
cd ${WORKTREE_PATH}
# Commit after manual completion
git add . && git commit -m "fix: manual fix"
# Switch back to main repo and merge
cd ${ORIGINAL_REPO_PATH}
git merge feature/story-${STORY_ID}
# Cleanup worktree
git worktree remove ${WORKTREE_PATH}
# Optional: delete feature branch
git branch -d feature/story-${STORY_ID}
Configuration
To customize the pipeline workflow, edit: references/workflow-steps.md
Changes supported:
- Add/remove steps
- Modify step commands
- Reorder steps
- Change descriptions
BMAD Story Pipeline
Complete the delivery pipeline for story {ARGUMENT} using configurable workflow.
Pre-step: Determine Story Number
If {ARGUMENT} is empty or not provided:
- Read
_bmad-output/implementation-artifacts/sprint-status.yaml(ordocs/sprint/sprint-status.yaml) to find stories - Find the first story with status "todo" or "in-progress"
- Use that story number as
{STORY_ID} - If no story found, ask user to specify story number
The story number format is typically X-Y (e.g., 1-1, 2-3).
Execution Strategy
- Read workflow steps from references/workflow-steps.md
- Execute each step sequentially using Task tool (general-purpose agent)
- Output progress after each step
- After pipeline, update status to done
Workflow Steps
Read and execute steps from references/workflow-steps.md.
For each step defined there, you MUST use the Task tool to execute in a subagent:
Task(
subagent_type: "general-purpose",
description: "<Step description>",
prompt: "Execute the command: <COMMAND_WITH_STORY_ID>
Return: 1) Step completion status 2) Key outputs 3) Any issues to note"
)
Example Invocations
Step 1 - Create Story:
Task(
subagent_type: "general-purpose",
description: "Create user story {STORY_ID}",
prompt: "Execute /bmad-bmm-create-story {STORY_ID} yolo to create story file. Return: 1) Story ID and Title 2) Created files 3) Any issues"
)
Step 2 - ATDD Tests:
Task(
subagent_type: "general-purpose",
description: "Generate ATDD tests for {STORY_ID}",
prompt: "Execute /bmad-tea-testarch-atdd {STORY_ID} yolo to generate acceptance tests. Return: 1) ATDD checklist 2) Test files created 3) Any issues"
)
Step 3 - Development:
Task(
subagent_type: "general-purpose",
description: "Develop user story {STORY_ID}",
prompt: "Execute /bmad-bmm-dev-story {STORY_ID} yolo to implement story code. Return: 1) Modified files 2) Summary of changes 3) Any issues"
)
Step 4 - Code Review:
Task(
subagent_type: "general-purpose",
description: "Code review for {STORY_ID}",
prompt: "Execute /bmad-bmm-code-review {STORY_ID} yolo for adversarial review. Return: 1) Conclusion (pass/needs-fix) 2) Issues by severity 3) Any blocking issues"
)
Step 5 - Trace Coverage:
Task(
subagent_type: "general-purpose",
description: "Trace test coverage for {STORY_ID}",
prompt: "Execute /bmad-tea-testarch-trace {STORY_ID} yolo for traceability matrix. Return: 1) Coverage percentage 2) Gate decision 3) Any gaps"
)
Execution Flow
For each step:
- Replace
{STORY_ID}with the actual story number in the prompt - Call Task tool with the step's description and prompt
- Wait for completion and capture result
- Output progress:
[X/5] Step Name - Status - If step fails, stop and report error
Progress Display
After each step, output progress:
📊 Pipeline Progress: [X/5] ████████░░░░ 40%
✅ Step X: <Step Name>
Result: <Brief result summary>
Error Handling
If any step fails:
- Stop executing subsequent steps
- Output error information:
❌ Pipeline Failed at Step X: <Step Name> Error: <Error details> 💡 Suggested actions: - Check the story file for issues - Run the failed step manually: <command> - Fix the issue and restart pipeline - Do NOT proceed to next steps
Post-Pipeline: Update Status
After ALL steps complete successfully:
-
Update sprint-status.yaml:
- Find the story entry
- Change status from
in-progresstodone
-
Update story document (if exists):
- Change
Status:todone - Mark all tasks with ✅
- Change
Output final summary:
🎉 Pipeline Complete!
Story: {STORY_ID}
Status: done
📋 Steps completed: 5/5
✅ Create User Story
✅ Generate ATDD Tests
✅ Development
✅ Code Review
✅ Trace Test Coverage
Configuration
To customize the pipeline workflow, edit: references/workflow-steps.md
Changes supported:
- Add/remove steps
- Modify step commands
- Reorder steps
- Change descriptions
Sponsors
Details
- Marketplace
- terryso/claude-bmad-skills
- Category
- Community
- License
- MIT
- Keywords
- bmad, agile, ai-driven, pipeline, skills