finishing-a-development-branch

完成开发分支

流程

步骤 1：验证测试

根据项目结构确定测试运行器：

• package.json → npm test 或 yarn test
• Cargo.toml → cargo test
• pyproject.toml / setup.py → pytest
• go.mod → go test ./...
• 包含 test 目标的 Makefile → make test

运行测试。如果有任何测试失败，报告 ⊘ BLOCKED:TESTS，并注明失败数量，然后停止。不要继续步骤 2。

步骤 2：确定基础分支

查找此功能从哪个分支分离出来：

# Check which branch has the closest merge-base
for candidate in main master develop; do
  if git rev-parse --verify "$candidate" >/dev/null 2>&1; then
    MERGE_BASE=$(git merge-base HEAD "$candidate" 2>/dev/null)
    if [ -n "$MERGE_BASE" ]; then
      echo "Candidate: $candidate (merge-base: $MERGE_BASE)"
    fi
  fi
done

选择具有最新合并基点（最近祖先）的候选分支。如果多个分支共享同一个合并基点，或无法明确判断，则询问：“此分支可能以 main 或 develop 为目标。应该合并到哪个分支？”

保存结果——后续步骤中的 <base-branch> 指已确定的分支。

步骤 3：提供选项

准确提供以下 4 个选项：

Implementation complete. What would you like to do?

1. Merge back to <base-branch> locally
2. Push and create a Pull Request
3. Keep the branch as-is (I'll handle it later)
4. Discard this work

Which option?

步骤 4：执行选择

选项 1：在本地合并

git checkout <base-branch>
git pull
git merge <feature-branch>

如果发生合并冲突：

⊘ BLOCKED:CONFLICTS

Merge conflicts in:
- <conflicted files>

Cannot auto-resolve. User must:
1. Resolve conflicts manually
2. Run tests
3. Re-run this workflow

停止。不要继续。

如果合并成功：

# Verify tests on merged result
<test command>

# If tests pass, delete feature branch
git branch -d <feature-branch>

然后：清理工作树（步骤 5）。报告 ✓ MERGED。

选项 2：推送并创建 PR

确认 gh CLI 可用：

if ! command -v gh &>/dev/null; then
  echo "gh CLI not installed. Install from https://cli.github.com/ or push manually and create PR via web."
  exit 1
fi
gh auth status || echo "gh not authenticated. Run: gh auth login"

从分支上的首个提交提取标题（原始意图）：

MERGE_BASE=$(git merge-base HEAD <base-branch>)
TITLE=$(git log --reverse --format=%s "$MERGE_BASE"..HEAD | head -1)
git push -u origin <feature-branch>
gh pr create --title "$TITLE" --body "$(cat <<'EOF'
## Summary
<2-3 bullets of what changed>

## Test Plan
- [ ] <verification steps>
EOF
)"

报告 ✓ PR_CREATED 并附上 PR URL。保留工作树以便在审核期间继续工作。

选项 3：保持原样

报告 ✓ PRESERVED，并注明分支名称和工作树路径。

不要清理工作树。

选项 4：丢弃

先确认：

This will permanently delete:
- Branch <name>
- All commits: <commit-list>
- Worktree at <path>

Type 'discard' to confirm.

等待准确的确认内容。如果未收到，则中止。

确认后：

git checkout <base-branch>
git branch -D <feature-branch>

然后：清理工作树（步骤 5）。报告 ✓ DISCARDED。

步骤 5：清理工作树

仅适用于选项 1 和 4：

# Check if currently in a worktree (not main repo)
if [ "$(git rev-parse --git-common-dir)" != "$(git rev-parse --git-dir)" ]; then
  # Get worktree root (handles invocation from subdirectory)
  WORKTREE_ROOT=$(git rev-parse --show-toplevel)
  cd "$(git rev-parse --git-common-dir)/.."
  git worktree remove "$WORKTREE_ROOT"
fi

**对于选项 2 和 3：**保留工作树。

快速参考

选项	合并	推送	保留工作树	清理分支
1. 在本地合并	✓	-	-	✓
2. 创建 PR	-	✓	✓	-
3. 保持原样	-	-	✓	-
4. 丢弃	-	-	-	✓（强制）

终态

完成后，准确报告以下一项：

状态	输出	含义
✓ MERGED	分支已合并到 <base>，工作树已清理	选项 1 成功
✓ PR_CREATED	PR #N，位于 URL	选项 2 成功
✓ PRESERVED	分支保留在指定路径	选项 3 成功
✓ DISCARDED	分支已删除，工作树已清理	选项 4 成功
⊘ BLOCKED:TESTS	N 个测试失败	无法继续
⊘ BLOCKED:CONFLICTS	文件中存在合并冲突	无法继续

防护措施

阻止条件（立即停止）：

• 测试失败 → ⊘ BLOCKED:TESTS
• 合并冲突 → ⊘ BLOCKED:CONFLICTS

必须确认的操作：

• 选项 4（丢弃）：必须输入“discard”进行确认

清理规则：

• 选项 1、4：清理工作树和分支
• 选项 2、3：保留工作树

绝不：

• 在测试失败时继续
• 未验证合并结果上的测试就进行合并
• 未经输入确认就删除工作
• 未经明确请求就强制推送

集成

由以下流程调用：

• subagent-driven-development（步骤 7）——所有任务完成后
• executing-plans（步骤 5）——所有批次完成后

配合使用：

• using-git-worktrees——清理由该技能创建的工作树