Finishing a Development Branch

Overview

Guide the conclusion of development work by providing clear options and executing the selected workflow.

Core Principles: Validate Tests → Detect Environment → Present Options → Execute Selection → Cleanup.

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

Process

Step 1: Validate Tests

Verify tests pass before presenting options:

bash

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

If tests fail:

Tests failed (<N> failures). Must fix before proceeding:

[Show failure details]

Cannot merge/PR until tests pass.

Stop. Do not proceed to Step 2.

If tests pass: Proceed to Step 2.

Step 2: Detect Environment

Determine workspace state before presenting options:

bash

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:

Status	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	Judge by source (see Step 6)
`GIT_DIR != GIT_COMMON` , detached HEAD	Converged 3 options (no merge)	No cleanup (managed externally)

Step 3: Identify Base Branch

bash

# Try common base branches
git merge-base HEAD main 2>/dev/null || git merge-base HEAD master 2>/dev/null

Or ask: "This branch was branched from main — is that correct?"

Step 4: Present Options

Normal repositories and named branch worktrees — present exactly these 4 options:

Implementation is 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?

Detached HEAD — present exactly these 3 options:

Implementation is complete. You're on detached HEAD (workspace managed externally).

1. Push as a new branch and create a Pull Request
2. Keep as-is (I'll handle it later)
3. Discard this work

Which option?

Do not add explanations — keep options concise.

Step 5: Execute Selection

Option 1: Local Merge

bash

# Switch to main repository root to ensure safe CWD
MAIN_ROOT=$(git -C "$(git rev-parse --git-common-dir)/.." rev-parse --show-toplevel)
cd "$MAIN_ROOT"

# Merge first — verify merge success before deleting anything
git checkout <base-branch>
git pull
git merge <feature-branch>

# Validate tests on merge result
<test command>

# After successful merge: clean up worktree (Step 6), then delete the branch

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

bash

git branch -d <feature-branch>

Option 2: Push and Create PR

bash

# Push the branch
git push -u origin <feature-branch>

# Create PR
gh pr create --title "<title>" --body "$(cat <<'EOF'
## Summary
<2-3 key changes>

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

Do not clean up worktree — user needs it to survive for PR feedback iterations.

Option 3: Keep As-Is

Report: "Branch <name> retained. Worktree kept at <path>."

Do not clean up worktree.

Option 4: Discard

Confirm first:

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

Enter 'discard' to confirm.

Wait for exact confirmation.

After confirmation:

bash

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:

bash

git branch -D <feature-branch>

Step 6: Clean Up Workspace

Execute only for Options 1 and 4. Options 2 and 3 always retain worktree.

bash

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 worktree path is under
.worktrees/
,
worktrees/
or
~/.config/superpowers/worktrees/
: This is a worktree created by Superpowers — we are responsible for cleaning it up.

bash

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  # Self-heal: clean up any stale registration records

Otherwise: This workspace is managed by the harness. Do not remove it. If your platform provides a workspace exit tool, use it. Otherwise leave the workspace as-is.

Quick Reference

Option	Merge	Push	Retain Worktree	Clean Up Branch
1. Local Merge	✓	-	-	✓
2. Create PR	-	✓	✓	-
3. Keep As-Is	-	-	✓	-
4. Discard	-	-	-	✓ (force)

Common Errors

Skipping Test Validation

Problem: Merging broken code, creating failed PRs
Fix: Always validate tests before presenting options

Open-Ended Questions

Problem: "What to do next?" → ambiguous
Fix: Present exactly 4 structured options (3 for detached HEAD)

Cleaning Worktree for Option 2

Problem: Deleting worktree user still needs for PR iterations
Fix: Only clean up for Options 1 and 4

Deleting Branch Before Worktree

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

Running
git worktree remove
Inside Worktree

Problem: Command silently fails when CWD is inside the worktree being deleted
Fix:
```
cd
```
to main repository root before running
```
git worktree remove
```

Cleaning Harness-Owned Worktree

Problem: Removing harness-created worktree causes phantom state

Fix: Only clean up worktrees under

.worktrees/

worktrees/

~/.config/superpowers/worktrees/

Discarding Without Confirmation

Problem: Accidentally deleting work成果
Fix: Require input of 'discard' to confirm

Red Lines

Never:

Proceed when tests fail
Merge without validating tests on merge result
Delete work成果 without confirmation
Force push without explicit request
Remove worktree before confirming merge success
Clean up worktrees not created by you (judge by source)
Run
```
git worktree remove
```
inside worktree

Always:

Validate tests before presenting options
Detect environment before showing menu
Present exactly 4 options (3 for detached HEAD)
Require confirmation for Option 4
Only clean up worktree for Options 1 and 4
```
cd
```
to main repository root before removing worktree
Run
```
git worktree prune
```
after removal

Integration

Called by the following skills:

subagent-driven-development (Step 7) - after all tasks are completed
executing-plans (Step 5) - after all batches are completed

Used with:

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

finishing-a-development-branch

NPX Install

Tags

SKILL.md Content (Chinese)

Finishing a Development Branch

Overview

Process

Step 1: Validate Tests

Step 2: Detect Environment

Step 3: Identify Base Branch

Step 4: Present Options

Step 5: Execute Selection

Option 1: Local Merge

Option 2: Push and Create PR

Option 3: Keep As-Is

Option 4: Discard

Step 6: Clean Up Workspace

Quick Reference

Common Errors

Integration