finishing-a-development-branch

Complete Development Branch

Overview

Guide the completion of development work by providing clear options and handling the chosen workflow.

Core principle: Verify tests → Detect environment → Provide options → Execute choice → Clean up.

Declare at the start: "I'm using the finishing-a-development-branch skill to complete this work."

Process

Step 1: Verify tests

Before providing options, verify that tests pass:

# 运行项目的测试套件
npm test / cargo test / pytest / go test ./...

If tests fail:

测试失败（<N> 个失败）。完成前必须修复：

[显示失败]

测试通过前，不能继续 merge/PR。

Stop. Do not continue to Step 2.

If tests pass: Continue to Step 2.

Step 2: Detect environment

Before providing options, determine the workspace state:

GIT_DIR=$(cd "$(git rev-parse --git-dir)" 2>/dev/null && pwd -P)
GIT_COMMON=$(cd "$(git rev-parse --git-common-dir)" 2>/dev/null && pwd -P)

This determines which menu is displayed and how cleanup works:

State	Menu	Cleanup
GIT_DIR == GIT_COMMON(normal repo)	Standard 4 options	No worktree to clean up
GIT_DIR != GIT_COMMON, named branch	Standard 4 options	Based on origin (see Step 6)
GIT_DIR != GIT_COMMON，detached HEAD	Condensed 3 options (no merge)	No cleanup (externally managed)

Step 3: Determine base branch

# 尝试常见基础分支
git merge-base HEAD main 2>/dev/null || git merge-base HEAD master 2>/dev/null

Or ask: "This branch split from main - is that correct?"

Step 4: Provide options

Normal repo and named branch worktree—provide exactly the following 4 options:

实现完成。你想怎么处理？

1. 在本地 merge 回 <base-branch>
2. Push 并创建 Pull Request
3. 保持分支原样（我稍后处理）
4. 丢弃这项工作

选择哪一项？

Detached HEAD—provide exactly the following 3 options:

实现完成。你位于 detached HEAD（外部管理的 workspace）。

1. 作为新分支 push 并创建 Pull Request
2. 保持原样（我稍后处理）
3. 丢弃这项工作

选择哪一项？

Do not add explanations - keep options concise.

Step 5: Execute choice

Option 1: Local Merge

# 获取 main repo root，保证 CWD 安全
MAIN_ROOT=$(git -C "$(git rev-parse --git-common-dir)/.." rev-parse --show-toplevel)
cd "$MAIN_ROOT"

# 先 merge——删除任何东西前验证成功
git checkout <base-branch>
git pull
git merge <feature-branch>

# 验证 merge 后结果上的测试
<test command>

# 仅在 merge 成功后：清理 worktree（Step 6），然后删除分支

Then: clean up worktree (Step 6), then delete branch:

git branch -d <feature-branch>

Option 2: Push and create PR

# Push 分支
git push -u origin <feature-branch>

# 创建 PR
gh pr create --title "<title>" --body "$(cat <<'EOF'
## 总结
<2-3 条更改内容>

## 测试计划
- [ ] <验证步骤>
EOF
)"

Do not clean up worktree—the user needs it preserved so they can iterate based on PR feedback.

Option 3: Keep as is

Report: "Keeping branch . Worktree preserved at ."

Do not clean up worktree.

Option 4: Discard

Confirm first:

这将永久删除：
- Branch <name>
- 所有 commits：<commit-list>
- 位于 <path> 的 worktree

输入 'discard' 确认。

Wait for exact confirmation.

If confirmed:

MAIN_ROOT=$(git -C "$(git rev-parse --git-common-dir)/.." rev-parse --show-toplevel)
cd "$MAIN_ROOT"

Then: clean up worktree (Step 6), then force delete branch:

git branch -D <feature-branch>

Step 6: Clean up Workspace

Run only for Options 1 and 4. Options 2 and 3 always preserve the worktree.

GIT_DIR=$(cd "$(git rev-parse --git-dir)" 2>/dev/null && pwd -P)
GIT_COMMON=$(cd "$(git rev-parse --git-common-dir)" 2>/dev/null && pwd -P)
WORKTREE_PATH=$(git rev-parse --show-toplevel)

If GIT_DIR == GIT_COMMON： normal repo, no worktree to clean up. Done.

If the worktree path is under .worktrees/、worktrees/ or ~/.config/superpowers/worktrees/ : Superpowers created this worktree—we are responsible for cleaning it up.

MAIN_ROOT=$(git -C "$(git rev-parse --git-common-dir)/.." rev-parse --show-toplevel)
cd "$MAIN_ROOT"
git worktree remove "$WORKTREE_PATH"
git worktree prune  # 自愈：清理任何陈旧注册

Otherwise: The host environment (harness) owns this workspace. Do not remove it. If your platform provides a workspace-exit tool, use it. Otherwise, leave the workspace in place.

Quick reference

Option	Merge	Push	Preserve Worktree	Clean up branch
1. Local merge	yes	-	-	yes
2. Create PR	-	yes	yes	-
3. Keep as is	-	-	yes	-
4. Discard	-	-	-	yes（force）

Common Mistakes

Skipping test verification

• Problem: Merging broken code, creating a failing PR
• Fix: Always verify tests before offering options

Open-ended questions

• Problem: "What should I do next?" is ambiguous
• Fix: Provide exactly 4 structured options (or 3 for detached HEAD)

Cleaning up the worktree for Option 2

• Problem: Removed the worktree the user needs to iterate on the PR
• Fix: Only clean up for Options 1 and 4

Deleting the branch before removing the worktree

• Problem: git branch -d Fails because the worktree still references the branch
• Fix: Merge first, remove the worktree, then delete the branch

Running git worktree remove from inside the worktree

• Problem: The command silently fails when the CWD is inside the worktree being removed
• Fix: Always git worktree remove before cd to the main repo root

Cleaning up a harness-owned worktree

• Problem: Removing a worktree created by the harness causes ghost state
• Fix: Only clean up worktrees under .worktrees/、worktrees/ or ~/.config/superpowers/worktrees/ worktree under

Discarding without confirmation

• Problem: Accidentally deletes work
• Fix: Require typing "discard" to confirm

Red Flags

Never:

• Continue when tests fail
• Merge without verifying tests on the result
• Delete work without confirmation
• Force-push without an explicit request
• Remove the worktree before confirming the merge succeeded
• Clean up worktrees you didn't create (source check)
• Run from inside the worktree git worktree remove

Always:

• Verify tests before offering options
• Detect the environment before showing the menu
• Provide exactly 4 options (or 3 for detached HEAD)
• Get input confirmation for Option 4
• Only clean up the worktree for Options 1 and 4
• Before removing the worktree cd to the main repo root
• Run after removal git worktree prune