blitz

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

The Blitz: Parallel Worktree + Agent Workflow

闪电式处理:并行Worktree + Agent工作流

Parallelizes multi-issue sprints by running independent Claude agents in isolated git worktrees. Each agent creates a PR, self-reviews to 10/10 with 100% issue coverage, then PRs are sequentially merged to avoid conflicts. Herding 🐲.
通过在独立的git worktree中运行独立的Claude Agent,实现多需求迭代的并行处理。每个Agent会创建PR,进行自我评审直至达到10/10的评分且100%覆盖Issue需求,之后PR会按序合并以避免冲突。驯服🐲。

⚠️ MANDATORY: 100% Issue Coverage Per Agent

⚠️ 强制要求:每个Agent需100%覆盖Issue需求

Every agent MUST implement 100% of their assigned issue's requirements before their PR can be merged.
  • Each agent receives COMPLETE issue requirements (extracted from GitHub issue)
  • Review must verify ALL requirements are implemented
  • Coverage < 100% = agent sent back to complete the work
  • No PR merges until all requirements from the issue are addressed
每个Agent在其PR可合并前,必须实现分配给自己的Issue的100%需求。
  • 每个Agent会收到完整的Issue需求(从GitHub Issue中提取)
  • 评审必须验证所有需求均已实现
  • 覆盖率<100% → 需将Agent召回以完成剩余工作
  • 只有当Issue的所有需求都得到解决后,才能合并PR

Prerequisites

前置条件

Required Tools:
  • gh
    CLI (authenticated)
  • Git with worktree support (2.5+)
  • teams
    tool for parallel worker delegation
Required Skills:
  • 4-step-program
    - Guides agents through fix-review-iterate-present loop
  • code-reviewer
    - Self-review to 10/10 quality gate
  • delphi
    - Parallel oracles for triage decisions (optional, for ambiguous triage)
必备工具:
  • gh
    CLI(已完成认证)
  • 支持worktree的Git(版本2.5+)
  • 用于并行任务分配的
    teams
    工具
必备技能:
  • 4-step-program
    - 引导Agent完成修复-评审-迭代-提交的循环
  • code-reviewer
    - 自我评审以达到10/10的质量标准
  • delphi
    - 用于分类决策的并行预言工具(可选,用于模糊的分类场景)

Workflow Phases

工作流阶段

Phase 1: Issue Triage

阶段1:Issue分类

For ambiguous decisions on which issues to tackle, use the
delphi
skill:
Invoke Delphi: "Audit these open issues. For each, recommend: close (complete), fix (actionable), or defer (blocked)."
Interpreting Delphi Results:
  • Unanimous agreement → Act on recommendation
  • 2/3 agreement → Lean toward majority, investigate minority view
  • Full divergence → Need more context; investigate manually
Close complete issues immediately:
bash
gh issue close 1 2 3 --comment "Complete per Delphi audit"
For clear-cut issue lists, skip Delphi and proceed directly to Phase 2.
对于需要决策处理哪些Issue的模糊场景,使用
delphi
技能:
Invoke Delphi: "Audit these open issues. For each, recommend: close (complete), fix (actionable), or defer (blocked)."
解读Delphi结果:
  • 全票一致 → 按照建议执行
  • 2/3同意 → 倾向多数意见,同时调查少数意见
  • 完全分歧 → 需要更多上下文,手动调查
立即关闭已完成的Issue:
bash
gh issue close 1 2 3 --comment "Complete per Delphi audit"
对于明确的Issue列表,可跳过Delphi直接进入阶段2。

Phase 2: Worktree Setup

阶段2:Worktree设置

Create one worktree per fixable issue from main:
bash
git worktree add .worktrees/<slug> -b fix/<slug> main
Branch Naming:
fix/<descriptive-slug>
or
feat/<descriptive-slug>
Example setup for 4 issues:
bash
git worktree add .worktrees/test-isolation -b fix/test-isolation main
git worktree add .worktrees/config-theater -b fix/config-theater main
git worktree add .worktrees/wire-salience -b fix/wire-salience main
git worktree add .worktrees/testing-quality -b fix/testing-quality main
Why Worktrees:
  • Complete filesystem isolation per agent
  • No stash/checkout conflicts
  • Agents work truly in parallel
  • Each has independent node_modules, build artifacts
从main分支为每个需要修复的Issue创建一个worktree:
bash
git worktree add .worktrees/<slug> -b fix/<slug> main
分支命名规则:
fix/<描述性别名>
feat/<描述性别名>
4个Issue的设置示例:
bash
git worktree add .worktrees/test-isolation -b fix/test-isolation main
git worktree add .worktrees/config-theater -b fix/config-theater main
git worktree add .worktrees/wire-salience -b fix/wire-salience main
git worktree add .worktrees/testing-quality -b fix/testing-quality main
使用Worktree的原因:
  • 每个Agent拥有完全独立的文件系统
  • 无需暂存/切换分支,避免冲突
  • Agent可真正并行工作
  • 每个Agent拥有独立的node_modules和构建产物

Phase 3: Delegate to Parallel Agents

阶段3:分配任务给并行Agent

Delegate to workers using
teams
. Each worker needs:
  1. Working directory (absolute path to worktree)
  2. Issue context (number, description, acceptance criteria)
  3. COMPLETE list of ALL requirements from the issue (extracted via
    gh issue view
    )
  4. Explicit instruction to use 4-step-program skill
CRITICAL: Before delegating, extract ALL requirements from each issue:
bash
gh issue view <number>
List EVERY requirement, acceptance criterion, and edge case in the agent prompt.
Agent Prompt Template:
Working directory: /absolute/path/to/.worktrees/<slug>
Issue: #<number> - <title>

**ALL REQUIREMENTS FROM ISSUE (100% must be implemented):**
1. [Requirement 1 from issue]
2. [Requirement 2 from issue]
3. [Requirement 3 from issue]
... (list ALL of them)

Use the 4-step-program skill to:
1. Implement ALL the above requirements (100% coverage required)
2. Run tests, verify passing
3. Create PR with `gh pr create` - **MUST include `Closes #<issue-number>` in body**
4. Self-review using code-reviewer skill (which will verify 100% coverage)
5. POST review to GitHub with `gh api`

**PR MUST include:**
- `Closes #<issue-number>` to auto-close the issue on merge
- "Related Issues" section in PR body
- Verify with `gh pr view --json closingIssuesReferences`

Do not return until you achieve 10/10 review score WITH 100% of issue requirements implemented AND issue properly linked.
CRITICAL: Agents must POST reviews to GitHub, not just print them:
bash
gh api repos/OWNER/REPO/pulls/NUMBER/reviews \
  -f body="..." -f event="COMMENT"
Launch workers in parallel using
teams
:
teams(action: 'delegate', tasks: [
  {text: '<agent prompt for issue 1>', assignee: 'fix-issue-1'},
  {text: '<agent prompt for issue 2>', assignee: 'fix-issue-2'},
  {text: '<agent prompt for issue 3>', assignee: 'fix-issue-3'}
])
使用
teams
工具将任务分配给工作者。每个工作者需要:
  1. 工作目录(worktree的绝对路径)
  2. Issue上下文(编号、描述、验收标准)
  3. Issue的完整需求列表(通过
    gh issue view
    提取)
  4. 明确要求使用4-step-program技能
关键:分配任务前,提取每个Issue的所有需求:
bash
gh issue view <number>
在Agent的提示词中列出所有需求、验收标准和边缘情况。
Agent提示词模板:
Working directory: /absolute/path/to/.worktrees/<slug>
Issue: #<number> - <title>

**ALL REQUIREMENTS FROM ISSUE (100% must be implemented):**
1. [Requirement 1 from issue]
2. [Requirement 2 from issue]
3. [Requirement 3 from issue]
... (list ALL of them)

Use the 4-step-program skill to:
1. Implement ALL the above requirements (100% coverage required)
2. Run tests, verify passing
3. Create PR with `gh pr create` - **MUST include `Closes #<issue-number>` in body**
4. Self-review using code-reviewer skill (which will verify 100% coverage)
5. POST review to GitHub with `gh api`

**PR MUST include:**
- `Closes #<issue-number>` to auto-close the issue on merge
- "Related Issues" section in PR body
- Verify with `gh pr view --json closingIssuesReferences`

Do not return until you achieve 10/10 review score WITH 100% of issue requirements implemented AND issue properly linked.
关键:Agent必须将评审结果发布到GitHub,而不仅仅是打印出来:
bash
gh api repos/OWNER/REPO/pulls/NUMBER/reviews \
  -f body="..." -f event="COMMENT"
使用
teams
并行启动工作者:
teams(action: 'delegate', tasks: [
  {text: '<agent prompt for issue 1>', assignee: 'fix-issue-1'},
  {text: '<agent prompt for issue 2>', assignee: 'fix-issue-2'},
  {text: '<agent prompt for issue 3>', assignee: 'fix-issue-3'}
])

Phase 4: Review Iteration Loop

阶段4:评审迭代循环

Monitor each PR's review status:
bash
gh pr view <NUMBER> --json reviews --jq '.reviews[-1].body'
TWO gates must pass for each PR:
GATE 1: 100% Issue Coverage
  • Verify ALL requirements from original issue are implemented
  • If ANY requirement is missing → Resume agent with missing requirements
GATE 2: 10/10 Review Quality
  • Zero suggestions in review
  • All verification commands pass
If coverage < 100%: Resume the agent with specific missing requirements:
PR #<NUMBER> coverage: 80% (4 of 5 requirements).
Missing requirement: [Requirement 5 from issue - specific text]
Implement this requirement and re-review.
If score < 10/10 (but coverage 100%): Resume the agent with specific feedback:
PR #<NUMBER> has 100% coverage but scored 8/10. Issues:
- <specific issue 1>
- <specific issue 2>

Fix these issues and re-review.
10/10 + 100% Coverage Criteria:
  • ALL requirements from original issue implemented
  • All functionality working
  • Tests pass
  • No obvious bugs or security issues
  • Code follows project conventions
  • Documentation updated if needed
监控每个PR的评审状态:
bash
gh pr view <NUMBER> --json reviews --jq '.reviews[-1].body'
每个PR必须通过两个关卡:
关卡1:100% Issue覆盖率
  • 验证原始Issue的所有需求均已实现
  • 若有任何需求缺失 → 让Agent继续完成缺失的需求
关卡2:10/10评审质量
  • 评审中无任何建议
  • 所有验证命令执行通过
若覆盖率<100%: 让Agent继续完成特定的缺失需求:
PR #<NUMBER> coverage: 80% (4 of 5 requirements).
Missing requirement: [Requirement 5 from issue - specific text]
Implement this requirement and re-review.
若评分<10/10(但覆盖率为100%): 让Agent根据具体反馈继续处理:
PR #<NUMBER> has 100% coverage but scored 8/10. Issues:
- <specific issue 1>
- <specific issue 2>

Fix these issues and re-review.
10/10评分 + 100%覆盖率的标准:
  • 原始Issue的所有需求均已实现
  • 所有功能正常运行
  • 测试通过
  • 无明显bug或安全问题
  • 代码遵循项目规范
  • 必要时更新文档

Phase 4.5: FINAL COVERAGE GATE (Before Merge)

阶段4.5:最终覆盖关卡(合并前)

MANDATORY: Before merging ANY PR, perform LINE-BY-LINE requirement verification.
For EACH PR ready to merge:
强制要求: 在合并任何PR之前,逐行验证需求覆盖情况。
对于每个准备合并的PR:

Step 1: Extract ALL Requirements

步骤1:提取所有需求

bash
undefined
bash
undefined

Get ALL checklist items from issue

Get ALL checklist items from issue

gh issue view <issue-number> --json body --jq '.body' | grep -E "^- ["
gh issue view <issue-number> --json body --jq '.body' | grep -E "^- ["

Also get full issue for prose requirements

Also get full issue for prose requirements

gh issue view <issue-number>
undefined
gh issue view <issue-number>
undefined

Step 2: Create Line-by-Line Table

步骤2:创建逐行检查表

MANDATORY for each PR:
markdown
undefined
每个PR必须包含:
markdown
undefined

Issue #X - Full Requirements Check

Issue #X - Full Requirements Check

RequirementPR StatusEvidence
[exact text from issue]
file.cs:line
- [implementation]
[exact text from issue]❌ MISSINGNot found in PR
[exact text from issue]⚠️ PARTIAL
file.cs:line
- [what's missing]
[exact text from issue]⚠️ MANUALRequires Unity Editor
undefined
RequirementPR StatusEvidence
[exact text from issue]
file.cs:line
- [implementation]
[exact text from issue]❌ MISSINGNot found in PR
[exact text from issue]⚠️ PARTIAL
file.cs:line
- [what's missing]
[exact text from issue]⚠️ MANUALRequires Unity Editor
undefined

Step 3: Honest Assessment

步骤3:真实评估

markdown
**Honest Assessment**:
- Coverage: X% (Y of Z requirements fully implemented)
- Missing: [list specific items]
- Partial: [list items and what's missing]
- Manual: [list items needing editor/runtime]
FINAL GATE DECISION:
CoverageAction
100%✅ Proceed to Phase 5 (Merge)
< 100%DO NOT MERGE - Resume agent
If Final Coverage < 100%:
Resume agent: "FINAL COVERAGE GATE FAILED for PR #<NUMBER>.

Issue #X - Full Requirements Check:

| Requirement | Status | Evidence |
|-------------|--------|----------|
| MeshDeformer component created | ✅ | MeshDeformer.cs |
| Create scene GameObject | ❌ MISSING | No scene modification |
| Cache hit rate >90% | ⚠️ MANUAL | Requires runtime profiler |

Honest Assessment:
- Coverage: 85% (11 of 13 requirements)
- Missing: scene GameObject creation
- Partial: none
- Manual: cache hit rate verification

Implement ALL items marked ❌. Items marked ⚠️ MANUAL that CAN be automated via mcp-unity MUST be automated.

Do not return until 100% coverage."
→ Loop back to Phase 4 (Review Iteration)
markdown
**Honest Assessment**:
- Coverage: X% (Y of Z requirements fully implemented)
- Missing: [list specific items]
- Partial: [list items and what's missing]
- Manual: [list items needing editor/runtime]
最终关卡决策:
CoverageAction
100%✅ 进入阶段5(合并)
< 100%禁止合并 - 让Agent继续处理
若最终覆盖率<100%:
Resume agent: "FINAL COVERAGE GATE FAILED for PR #<NUMBER>.

Issue #X - Full Requirements Check:

| Requirement | Status | Evidence |
|-------------|--------|----------|
| MeshDeformer component created | ✅ | MeshDeformer.cs |
| Create scene GameObject | ❌ MISSING | No scene modification |
| Cache hit rate >90% | ⚠️ MANUAL | Requires runtime profiler |

Honest Assessment:
- Coverage: 85% (11 of 13 requirements)
- Missing: scene GameObject creation
- Partial: none
- Manual: cache hit rate verification

Implement ALL items marked ❌. Items marked ⚠️ MANUAL that CAN be automated via mcp-unity MUST be automated.

Do not return until 100% coverage."
→ 回到阶段4(评审迭代)

Phase 5: Sequential Squash-Merge + Rebase

阶段5:按序压缩合并 + 变基

Merge PRs one at a time. Order by dependency (infrastructure first).
Before merging, verify issue linking:
bash
undefined
逐个合并PR。按依赖顺序合并(基础设施相关的优先)。
合并前,验证Issue关联情况:
bash
undefined

Verify PR will close the issue

Verify PR will close the issue

gh pr view <NUMBER> --json closingIssuesReferences --jq '.closingIssuesReferences[].number'
gh pr view <NUMBER> --json closingIssuesReferences --jq '.closingIssuesReferences[].number'

If empty, PR is missing issue link - send agent back to fix!

If empty, PR is missing issue link - send agent back to fix!


**For each PR:**

```bash

**每个PR的操作步骤:**

```bash

1. Squash merge (keeps history clean) - issues auto-close on merge

1. Squash merge (keeps history clean) - issues auto-close on merge

gh pr merge <NUMBER> --squash --delete-branch
gh pr merge <NUMBER> --squash --delete-branch

2. Update local main

2. Update local main

git checkout main && git pull
git checkout main && git pull

3. Rebase next PR onto updated main

3. Rebase next PR onto updated main

cd .worktrees/<next-slug> git fetch origin main git rebase origin/main git push --force-with-lease
cd .worktrees/<next-slug> git fetch origin main git rebase origin/main git push --force-with-lease

4. Repeat merge for next PR

4. Repeat merge for next PR


**Why This Order:**
- Squash merge keeps main history linear
- Rebasing before merge prevents conflicts
- Sequential merging catches integration issues early
- `--force-with-lease` prevents overwriting others' work

**Handling Conflicts:**
```bash
git rebase origin/main

**为何按此顺序:**
- 压缩合并保持main分支历史整洁
- 合并前变基避免冲突
- 按序合并可尽早发现集成问题
- `--force-with-lease` 避免覆盖他人的工作

**冲突处理:**
```bash
git rebase origin/main

If conflicts:

If conflicts:

1. Fix conflicts in affected files

1. Fix conflicts in affected files

2. git add <fixed-files>

2. git add <fixed-files>

3. git rebase --continue

3. git rebase --continue

4. git push --force-with-lease

4. git push --force-with-lease

undefined
undefined

Phase 6: Cleanup

阶段6:清理

After all PRs merge:
bash
undefined
所有PR合并完成后:
bash
undefined

Remove worktrees

Remove worktrees

git worktree remove .worktrees/<slug> # Repeat for each
git worktree remove .worktrees/<slug> # Repeat for each

Delete local branches (remote already deleted by --delete-branch)

Delete local branches (remote already deleted by --delete-branch)

git branch -D fix/<slug> # Repeat for each
git branch -D fix/<slug> # Repeat for each

Sync main

Sync main

git checkout main && git pull
git checkout main && git pull

Verify clean state

Verify clean state

git worktree list # Should show only main git branch # Should show only main
undefined
git worktree list # Should show only main git branch # Should show only main
undefined

Quick Reference

快速参考

See
references/commands.md
for complete command reference. See
references/pitfalls.md
for common issues and solutions.
完整命令参考请见
references/commands.md
。 常见问题及解决方案请见
references/pitfalls.md

Mermaid Diagrams in Blitz PRs

Blitz PR中的Mermaid图

Each agent's PR SHOULD include Mermaid diagrams when the change warrants visualization.
当变更需要可视化时,每个Agent的PR应包含Mermaid图。

When Agents Should Add Diagrams

Agent应添加图的场景

Change TypeDiagram
Flow change
flowchart
before/after
API modification
sequenceDiagram
State handling
stateDiagram-v2
Architecture change
flowchart
with subgraphs
Change TypeDiagram
Flow change
flowchart
before/after
API modification
sequenceDiagram
State handling
stateDiagram-v2
Architecture change
flowchart
with subgraphs

Agent Delegation Should Include

分配Agent任务时应包含

When delegating to agents, add to the prompt:
If your changes involve flow modifications, state changes, or API interactions,
include a Mermaid diagram in the PR body showing the new behavior.
分配任务给Agent时,在提示词中添加:
If your changes involve flow modifications, state changes, or API interactions,
include a Mermaid diagram in the PR body showing the new behavior.

Example PR with Diagram

带图的PR示例

markdown
undefined
markdown
undefined

Summary

Summary

Fixed race condition in WebSocket reconnection.
Fixed race condition in WebSocket reconnection.

Before/After

Before/After

mermaid
flowchart LR
    subgraph Before
        A1[Disconnect] --> B1[Reconnect]
        B1 --> C1[Duplicate handlers]
    end
    subgraph After
        A2[Disconnect] --> B2[Cleanup handlers]
        B2 --> C2[Reconnect]
        C2 --> D2[Single handler]
    end
mermaid
flowchart LR
    subgraph Before
        A1[Disconnect] --> B1[Reconnect]
        B1 --> C1[Duplicate handlers]
    end
    subgraph After
        A2[Disconnect] --> B2[Cleanup handlers]
        B2 --> C2[Reconnect]
        C2 --> D2[Single handler]
    end

Related Issues

Related Issues

  • Closes #45 - WebSocket reconnection bug

---
  • Closes #45 - WebSocket reconnection bug

---

Checklist Summary

检查清单总结

  1. Triage issues (use
    delphi
    if ambiguous)
  2. Extract ALL requirements from each issue (
    gh issue view
    )
  3. Create worktrees for each fixable issue
  4. Launch parallel agents with 4-step-program including complete requirement lists
  5. Monitor and iterate until all PRs hit 100% issue coverage AND 10/10
  6. FINAL COVERAGE GATE: Re-verify 100% coverage before each merge
  7. Sequential squash-merge with rebase between (only after gate passes)
  8. Cleanup worktrees and branches
  9. PRs include Mermaid diagrams where helpful
  1. 分类Issue(若场景模糊则使用
    delphi
  2. 提取每个Issue的所有需求
    gh issue view
  3. 为每个需要修复的Issue创建worktree
  4. 启动并行Agent,使用4-step-program并包含完整需求列表
  5. 监控并迭代,直到所有PR达到100% Issue覆盖率且评分10/10
  6. 最终覆盖关卡:每个PR合并前重新验证100%覆盖率
  7. 按序压缩合并,合并间进行变基(仅在通过关卡后)
  8. 清理worktree和分支
  9. 必要时PR中包含Mermaid图