Back to Details

bmad-story-pipeline-worktree

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

BMAD Story Pipeline (Worktree Edition)

BMAD故事交付流水线（Worktree版本）

Complete the delivery pipeline for story 
{ARGUMENT}
using configurable workflow in an isolated git worktree, merge to main branch only after all tests pass.
在隔离的git worktree中通过可配置工作流完成故事
{ARGUMENT}
的交付流水线，仅当所有测试通过后才合并到主分支。

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.
如果
{ARGUMENT}
为空或未提供：
  1. 读取
    _bmad-output/implementation-artifacts/sprint-status.yaml
    （或
    docs/sprint/sprint-status.yaml
    ）查找用户故事
  2. 找到第一个状态为"todo"或"in-progress"的故事
  3. 将该故事编号作为
    {STORY_ID}
  4. 如果未找到任何故事，要求用户指定故事编号
故事编号的格式通常为
X-Y
（例如
1-1
、
2-3
）。
后续所有步骤都使用
STORY_ID = {ARGUMENT}
。

Difference from bmad-story-pipeline

与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
功能bmad-story-pipelinebmad-story-pipeline-worktree
工作方式在当前分支开发在隔离worktree中开发
代码隔离性无完全隔离
合并条件无强制要求测试通过+修复完成
工作流配置workflow-steps.mdworkflow-steps.md
安全等级中等高

Phase 1: Create Worktree

阶段1：创建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}
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
请手动执行以下操作（不要通过Task agent执行）：
1. 获取当前项目名称、路径和分支：
   ORIGINAL_REPO_PATH=$(pwd)
   PROJECT_NAME=$(basename $(pwd))
   CURRENT_BRANCH=$(git branch --show-current)

2. 创建新分支名：feature/story-${STORY_ID}

3. 创建worktree目录（存放在同级目录）：
   WORKTREE_PATH="../${PROJECT_NAME}-story-${STORY_ID}"

4. 执行git worktree命令：
   git worktree add -b feature/story-${STORY_ID} "$WORKTREE_PATH" $CURRENT_BRANCH

   如果分支已存在，使用：
   git worktree add "$WORKTREE_PATH" feature/story-${STORY_ID}

5. 验证worktree创建成功：
   git worktree list
为后续阶段保存的变量：
  • ORIGINAL_REPO_PATH
    - 原始仓库路径（用于合并步骤）
  • WORKTREE_PATH
    - Worktree路径
  • STORY_ID
    - 故事编号
进度输出：
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
✅ 创建Worktree
   🌿 分支: feature/story-${STORY_ID}
   📁 路径: ${WORKTREE_PATH}
   📦 原始仓库: ${ORIGINAL_REPO_PATH}
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Phase 2: Run Configurable Pipeline

阶段2：运行可配置流水线

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"
)
首先切换到worktree目录，再运行流水线。
从references/workflow-steps.md读取工作流步骤。
使用Task工具（通用agent）按顺序执行每个步骤：
Task(
  subagent_type: "general-purpose",
  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"
)
步骤1 - 创建故事：
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"
)
步骤2 - ATDD测试：
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"
)
步骤3 - 开发：
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"
)
步骤4 - 代码评审：
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"
)
步骤5 - 覆盖率追踪：
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
对每个步骤：
  1. 将prompt中的
    {STORY_ID}
    替换为实际的故事编号
  2. 传入步骤描述和prompt调用Task工具
  3. 等待执行完成并捕获结果
  4. 输出进度：
    [X/N] 步骤名称 - 状态
  5. 如果步骤失败，停止执行并报错

Progress Display

进度展示

After each step, output progress:
📊 Pipeline Progress: [X/N] ████████░░░░ 40%

✅ Step X: <Step Name>
   Result: <Brief result summary>
每个步骤执行完成后，输出进度：
📊 流水线进度: [X/N] ████████░░░░ 40%

✅ 步骤X: <步骤名称>
   结果: <简要结果摘要>

Phase 3: Merge or Preserve

阶段3：合并或保留

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:
   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}
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
关键决策步骤：检查合并条件
合并条件：
  1. 所有流水线步骤执行成功
  2. 无高/中优先级问题（或所有问题已修复）
  3. 测试通过
如果所有条件都满足，请手动执行合并：
1. 在worktree中提交所有更改：
   cd ${WORKTREE_PATH}
   git add .
   git commit -m "feat: complete story ${STORY_ID}"

2. 切回原仓库：
   cd ${ORIGINAL_REPO_PATH}

3. 合并功能分支：
   git merge feature/story-${STORY_ID} --no-edit

4. 删除worktree：
   git worktree remove ${WORKTREE_PATH}

5. 可选：删除功能分支（如果不需要保留）：
   git branch -d feature/story-${STORY_ID}

6. 验证清理完成：
   git worktree list
进度输出：
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
✅ 合并分支
   🔀 合并: feature/story-${STORY_ID} → [当前分支]
   🗑️ 清理: worktree已移除
   📝 提交哈希: [hash]
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
如果未满足合并条件，保留worktree供手动处理：
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
⚠️ 合并分支
   ❌ 未满足合并条件，已保留worktree
   📁 路径: ${WORKTREE_PATH}
   🔧 需要手动处理：
   - [列出未满足的条件]

   处理完成后，手动执行：
   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}
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Phase 4: Update Status to Done

阶段4：更新状态为已完成

After successful merge, update status files.
合并成功后，更新状态文件。

4.1 Update sprint-status.yaml

4.1 更新sprint-status.yaml

Use Edit tool to update status file:
File path: _bmad-output/implementation-artifacts/sprint-status.yaml (or docs/sprint/sprint-status.yaml)

Change story status from in-progress to done:
  {epic-num}-{story-num}-{story-name}: done
使用编辑工具更新状态文件：
文件路径: _bmad-output/implementation-artifacts/sprint-status.yaml (或 docs/sprint/sprint-status.yaml)

将故事状态从in-progress改为done：
  {epic-num}-{story-num}-{story-name}: done

4.2 Update Story Document (if exists)

4.2 更新故事文档（如果存在）

Use Edit tool to update story document status:
File path: _bmad-output/implementation-artifacts/{epic-num}-{story-num}-{story-name}.md

Update two places:

1. Top status line:
   Change "Status: in-progress" to "Status: done"

2. Tasks checklist (if any):
   Change all "- [ ]" to "- [x]" to mark tasks complete
Progress output:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
✅ Update Status
   📝 sprint-status.yaml: ${STORY_ID} → done
   📄 Story doc: Status: done, Tasks: ✅
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
使用编辑工具更新故事文档状态：
文件路径: _bmad-output/implementation-artifacts/{epic-num}-{story-num}-{story-name}.md

更新两处内容：

1. 顶部状态行：
   将"Status: in-progress"改为"Status: done"

2. 任务清单（如果有）：
   将所有"- [ ]"改为"- [x]"标记任务完成
进度输出：
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
✅ 更新状态
   📝 sprint-status.yaml: ${STORY_ID} → done
   📄 故事文档: 状态: done, 任务: ✅
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Final Delivery Report

最终交付报告

Successful merge:
╔════════════════════════════════════════════════════════╗
║         🎉 BMAD Story Pipeline Complete!               ║
╠════════════════════════════════════════════════════════╣
║  Story: ${STORY_ID}                                    ║
║                                                        ║
║  ✅ Phase 1 - Create Worktree                          ║
║  ✅ Phase 2 - Configurable Pipeline                    ║
║  ✅ Phase 3 - Merge Branch                             ║
║  ✅ Phase 4 - Update Status to Done                    ║
║                                                        ║
║  📊 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 - Merge Branch [not started]               ║
║  ⏸️ Phase 4 - Update Status [not started]              ║
║                                                        ║
║  📁 Worktree: ${WORKTREE_PATH}                         ║
║  💡 Fix the issue and continue manually                ║
╚════════════════════════════════════════════════════════╝
合并成功：
╔════════════════════════════════════════════════════════╗
║         🎉 BMAD故事流水线执行完成！               ║
╠════════════════════════════════════════════════════════╣
║  故事: ${STORY_ID}                                    ║
║                                                        ║
║  ✅ 阶段1 - 创建Worktree                          ║
║  ✅ 阶段2 - 可配置流水线                    ║
║  ✅ 阶段3 - 合并分支                             ║
║  ✅ 阶段4 - 更新状态为已完成                    ║
║                                                        ║
║  📊 状态: done                                       ║
╚════════════════════════════════════════════════════════╝
需要手动介入：
╔════════════════════════════════════════════════════════╗
║     ⚠️ BMAD故事流水线 - 需要手动干预       ║
╠════════════════════════════════════════════════════════╣
║  故事: ${STORY_ID}                                    ║
║                                                        ║
║  ✅ 阶段1 - 创建Worktree                          ║
║  ❌ 阶段2 - 流水线 [步骤X执行失败]              ║
║  ⏸️ 阶段3 - 合并分支 [未启动]               ║
║  ⏸️ 阶段4 - 更新状态 [未启动]              ║
║                                                        ║
║  📁 Worktree路径: ${WORKTREE_PATH}                         ║
║  💡 修复问题后手动继续执行即可                ║
╚════════════════════════════════════════════════════════╝

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:
bash
undefined
如果任何步骤失败：
  1. 停止执行后续步骤
  2. 保留worktree（不要删除）
  3. 输出错误信息和当前状态
  4. 提示用户如何手动修复
  5. 提供恢复命令
恢复命令示例：
bash
undefined

List all worktrees

列出所有worktree

git worktree list
git worktree list

Continue working in worktree

继续在worktree中工作

cd ${WORKTREE_PATH}
cd ${WORKTREE_PATH}

Commit after manual completion

手动完成后提交更改

git add . && git commit -m "fix: manual fix"
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}
cd ${ORIGINAL_REPO_PATH} git merge feature/story-${STORY_ID}

Cleanup worktree

清理worktree

git worktree remove ${WORKTREE_PATH}
git worktree remove ${WORKTREE_PATH}

Optional: delete feature branch

可选：删除功能分支

git branch -d feature/story-${STORY_ID}

---
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
要自定义流水线工作流，请编辑： references/workflow-steps.md
支持的修改：
  • 新增/删除步骤
  • 修改步骤命令
  • 调整步骤顺序
  • 修改描述