BMAD methodology skills - configurable pipeline for story delivery

GitHub stars
41

Install

/plugin install bmad-skills@bmad-skills

Run it inside Claude Code after adding the marketplace with /plugin marketplace add terryso/claude-bmad-skills.

Contents

Discovered from source

Skills 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):

  1. Read _bmad-output/implementation-artifacts/sprint-status.yaml (or docs/sprint/sprint-status.yaml)
  2. Find all stories with status not done (format: X-Y-story-name)
  3. Extract Epic numbers X from these stories
  4. Select the smallest Epic number as {ARGUMENT}
  5. 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

Featurebmad-epic-worktreebmad-epic-pipeline-worktree
Story deliverybmad-story-worktreebmad-story-pipeline-worktree
Workflow configFixed 8-step flowConfigurable via workflow-steps.md
CustomizationLimitedFull pipeline customization
Safety levelHighHigh

Execution Strategy

  1. Read all incomplete stories under the Epic
  2. Sort by Story number ascending
  3. Execute /bmad-story-pipeline-worktree for each story sequentially
  4. Only start next story after previous one completes
  5. 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:

  1. Stop subsequent story delivery
  2. Preserve failed story's worktree (if any)
  3. Output failure information and completed progress
  4. 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:

  1. Read _bmad-output/implementation-artifacts/sprint-status.yaml (or docs/sprint/sprint-status.yaml) to find stories
  2. Find the first story with status "todo" or "in-progress"
  3. Use that story number as {STORY_ID}
  4. 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

Featurebmad-story-pipelinebmad-story-pipeline-worktree
Working methodDevelop on current branchDevelop in isolated worktree
Code isolationNoneComplete isolation
Merge conditionNone enforcedTests pass + fixes complete
Workflow configworkflow-steps.mdworkflow-steps.md
Safety levelMediumHigh

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 path
  • STORY_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:

  1. Replace {STORY_ID} with the actual story number in the prompt
  2. Call Task tool with the step's description and prompt
  3. Wait for completion and capture result
  4. Output progress: [X/N] Step Name - Status
  5. 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:

  1. Update sprint-status.yaml:

    • Find the story entry
    • Change status from in-progress to done
  2. Update story document (if exists):

    • Change Status: to done
    • Mark all tasks with ✅

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:

  1. All pipeline steps completed successfully
  2. No HIGH/MEDIUM issues (or all fixed)
  3. 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:

  1. Stop executing subsequent steps
  2. Preserve worktree (don't delete)
  3. Output error information and current state
  4. Prompt user how to manually fix
  5. 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:

  1. Read _bmad-output/implementation-artifacts/sprint-status.yaml (or docs/sprint/sprint-status.yaml) to find stories
  2. Find the first story with status "todo" or "in-progress"
  3. Use that story number as {STORY_ID}
  4. 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

  1. Read workflow steps from references/workflow-steps.md
  2. Execute each step sequentially using Task tool (general-purpose agent)
  3. Output progress after each step
  4. 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:

  1. Replace {STORY_ID} with the actual story number in the prompt
  2. Call Task tool with the step's description and prompt
  3. Wait for completion and capture result
  4. Output progress: [X/5] Step Name - Status
  5. 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:

  1. Stop executing subsequent steps
  2. 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
    
  3. Do NOT proceed to next steps

Post-Pipeline: Update Status

After ALL steps complete successfully:

  1. Update sprint-status.yaml:

    • Find the story entry
    • Change status from in-progress to done
  2. Update story document (if exists):

    • Change Status: to done
    • Mark all tasks with ✅

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