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

前置步骤：确定故事编号

{ARGUMENT}

is empty or not provided:

Read

_bmad-output/implementation-artifacts/sprint-status.yaml

(or

docs/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.

如果

{ARGUMENT}

为空或未提供：

读取

_bmad-output/implementation-artifacts/sprint-status.yaml

（或

docs/sprint/sprint-status.yaml

）查找用户故事

找到第一个状态为"todo"或"in-progress"的故事
将该故事编号作为
```
{STORY_ID}
```
如果未找到任何故事，要求用户指定故事编号

故事编号的格式通常为

X-Y

（例如

1-1

、

2-3

）。

后续所有步骤都使用

STORY_ID = {ARGUMENT}

。

Difference from bmad-story-pipeline

与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

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

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

对每个步骤：

将prompt中的
```
{STORY_ID}
```
替换为实际的故事编号
传入步骤描述和prompt调用Task工具
等待执行完成并捕获结果
输出进度：
```
[X/N] 步骤名称 - 状态
```
如果步骤失败，停止执行并报错

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:

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:
   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. 在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:

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:

bash

undefined

如果任何步骤失败：

停止执行后续步骤
保留worktree（不要删除）
输出错误信息和当前状态
提示用户如何手动修复
提供恢复命令

恢复命令示例：

bash

undefined

List all worktrees

列出所有worktree

git worktree list

Continue working in worktree

继续在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

清理worktree

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

支持的修改：

新增/删除步骤
修改步骤命令
调整步骤顺序
修改描述