finishing-a-development-branch

Finish development branch

Overview

Guide the conclusion of development work by offering clear options and executing the chosen workflow.

Core principle: Verify tests → detect environment → present options → execute choice → clean up.

At the start, announce: "I am using the finishing-a-development-branch skill to finish this work."

Process

Step 1: Verify tests

Before presenting options, verify that tests pass:

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

If tests fail:

测试失败（<N> 个失败）。必须先修复才能继续：

[显示失败信息]

在测试通过之前无法进行合并/PR。

Stop. Do not proceed to step 2.

If tests pass: Proceed to step 2.

Step 2: Detect environment

Before presenting options, first 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 to present and how to clean up:

State	Menu	Cleanup
`GIT_DIR == GIT_COMMON`(normal repository)	Standard 4 options	No worktree to clean up
`GIT_DIR != GIT_COMMON`, named branch	Standard 4 options	Determine by source (see step 6)
`GIT_DIR != GIT_COMMON`, detached HEAD	Converge to 3 options (no merge)	No cleanup (managed externally)

Step 3: Determine the base branch

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

Or ask: "This branch was branched from main—right?"

Step 4: Present options

Normal repository and named branch worktree — present exactly these 4 options:

实现已完成。你想怎么做？

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

选哪个？

Detached HEAD — present exactly these 3 options:

实现已完成。你在分离 HEAD 上（由外部管理的工作区）。

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

选哪个？

Do not add explanations — keep the options concise.

Step 5: Execute choice

Option 1: Local merge

# 切到主仓库根目录，保证 CWD 安全
MAIN_ROOT=$(git -C "$(git rev-parse --git-common-dir)/.." rev-parse --show-toplevel)
cd "$MAIN_ROOT"

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

# 在合并结果上验证测试
<test command>

# 合并成功之后再：清理 worktree（步骤 6），然后删除分支

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

git branch -d <feature-branch>

Option 2: Push and create PR

# 推送分支
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 still needs it alive while iterating on PR feedback.

Option 3: Keep as is

Report: "Keeping branch . Worktree is kept at ."

Do not clean up worktree.

Option 4: Discard

First confirm:

这将永久删除：
- 分支 <name>
- 所有提交：<commit-list>
- 工作树 <path>

输入 'discard' 确认。

Wait for the exact confirmation.

After confirmation:

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 the branch:

git branch -D <feature-branch>

Step 6: Clean up workspace

Perform 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 repository, no worktree to clean up. End.

If the worktree path is under .worktrees/ or worktrees/ : This is a worktree created by Superpowers — 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: This workspace is managed by the host environment (harness).Do notremove it. If your platform provides a workspace exit tool, use it. Otherwise leave the workspace as is.

Quick reference

Option	Merge	Push	Keep worktree	Clean up branch
1. Local merge	✓	-	-	✓
2. Create PR	-	✓	✓	-
3. Keep as is	-	-	✓	-
4. Discard	-	-	-	✓ (force)

Common mistakes

Skipping test verification

Problem: Merging broken code, creating failed PRs
Fix: Always verify tests before offering options

Open-ended questions

Problem: "What should I do next?" → ambiguous
Fix: Show exactly 4 structured options (3 when detached HEAD)

Cleaning up worktree for option 2

Problem: Deleting a worktree the user still needs for PR iteration
Fix: Only clean up for options 1 and 4

Deleting branch before deleting worktree

Problem: git branch -d fails because the worktree still references the branch
Fix: Merge first, then delete worktree, finally delete branch

Running inside the worktree git worktree remove

Problem: When CWD is inside the deleted worktree, the command fails silently
Fix: Run git worktree remove first cd to the main repository root

Cleaning up harness-owned worktree

Problem: Removing a harness-created worktree causes phantom state
Fix: Only clean up .worktrees/ or worktrees/ worktrees under

No confirmation when discarding

Problem: Accidentally deleting work results
Fix: Require typing 'discard' to confirm

Red lines

Never:

Continue when tests fail
Merge without verifying tests on the merge result
Delete work results without confirmation
Force push without an explicit request
Remove a worktree before confirming the merge succeeded
Clean up worktrees you did not create (judge by origin)
Run inside the worktree git worktree remove

Always:

Verify tests before offering options
Detect the environment before showing the menu
Show exactly 4 options (3 when detached HEAD)
Option 4 requires typed confirmation
Only clean up worktree for options 1 and 4
Before removing the worktree cd to the main repository root
After removal run git worktree prune

Integration

Called by the following skills:

subagent-driven-development(step 7) - after all tasks are complete
executing-plans(step 5) - after all batches are complete

Used with:

using-git-worktrees - cleans up worktrees created by this skill