How to Finish Development Branches with Superpowers

Mar 18, 2026

The Problem

I’ve finished implementing a feature. Tests pass locally. I’m ready to merge. But wait—did I push my changes? Should I create a PR or merge directly? Did I forget to pull the latest from main? And what about cleaning up the worktree?

These questions pop up every time I complete a feature. The mental overhead of deciding the right next step, combined with the risk of forgetting something, makes branch completion error-prone.

What I needed was a systematic approach that:

Verifies everything is ready before proceeding
Presents clear options for what to do next
Executes the chosen workflow correctly
Cleans up afterward

That’s exactly what Superpowers’ finishing-a-development-branch skill provides.

What Is the Finishing-a-Development-Branch Skill?

This skill guides branch completion through a strict workflow:

Core principle: Verify tests pass first, present options, execute choice, clean up.

The key insight is that tests are a gate. Nothing proceeds without passing tests. This prevents broken code from ever reaching the main branch.

The Four-Step Process

Step 1: Verify Tests Pass

Before presenting any options, the skill runs tests:

# JavaScript/TypeScript
npm test

# Rust
cargo test

# Python
pytest

# Go
go test ./...

If tests fail, the skill stops immediately:

Tests failing (3 failures). Must fix before completing:

FAIL src/auth.test.js
  - should reject invalid tokens
  - should refresh expired tokens

FAIL src/api.test.js
  - should handle rate limiting

Cannot proceed with merge/PR until tests pass.

No options. No workarounds. Fix the tests first.

When tests pass:

All tests passing. Proceeding to branch options...

Step 2: Determine Base Branch

The skill identifies where to merge:

git merge-base HEAD main 2>/dev/null || git merge-base HEAD master 2>/dev/null

If unclear, it asks:

This branch appears to split from 'main'. Is that correct?

1. Yes, merge to main
2. No, merge to a different branch

Step 3: Present Four Options

Once tests pass and the base branch is known, the skill presents exactly four options:

Implementation complete. What would you like to do?

1. Merge back to main 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?

No explanations. No recommendations. Just the options.

Step 4: Execute the Chosen Option

Each option triggers a specific workflow:

Option 1: Merge Locally

git checkout main
git pull origin main
git merge feature/user-auth
npm test  # Verify tests still pass on main

Option 2: Push and Create PR

git push -u origin feature/user-auth
gh pr create --title "Add user authentication" --body "$(cat <<'EOF'
## Summary
- Implement JWT-based authentication
- Add login/logout endpoints
- Add token refresh logic

## Test plan
- [ ] Unit tests pass
- [ ] Integration tests pass
- [ ] Manual login flow test
EOF
)"

Option 3: Keep Branch

Branch preserved. No changes made.

Current state:
  Branch: feature/user-auth
  Status: Ready for manual merge/PR

Option 4: Discard Work

git checkout main
git branch -D feature/user-auth
# If worktree was created by Superpowers:
rm -rf .worktrees/feature-user-auth

When Tests Fail

I once tried to skip the test gate. I had “just one failing test” that was “probably flaky”:

Me: Can we just skip the failing test? It's probably flaky.

Skill: Tests failing (1 failure). Cannot proceed with merge/PR until tests pass.

Me: But I need to ship this today.

Skill: Fix the failing test, then I'll present options.

I grumbled, investigated, and found a real bug. The test wasn’t flaky—it was catching a race condition I’d introduced. The skill saved me from shipping broken code.

"Probably flaky" = "Definitely a bug I haven't found yet"

Integration with the Superpowers Workflow

The finishing-a-development-branch skill is the final step in the Superpowers pipeline:

+-----------------+     +---------------------+     +-----------------+
|   Brainstorming | --> | using-git-worktrees | --> | writing-plans   |
|   (Design)      |     | (Isolate workspace) |     | (Plan tasks)    |
+-----------------+     +---------------------+     +-----------------+
                                                            |
                                                            v
+-----------------+     +---------------------+     +-----------------+
|   Finishing     | <-- |    Code Review      | <-- | Subagent-driven |
|   Branch        |     |    (Quality check)  |     | development     |
+-----------------+     +---------------------+     +-----------------+

Each skill builds on the previous one:

Brainstorming: Design the feature
using-git-worktrees: Create isolated workspace
writing-plans: Create implementation plan
subagent-driven-development: Execute the plan
finishing-a-development-branch: Complete and clean up

Worktree Cleanup

If I used the using-git-worktrees skill to create my workspace, the finishing skill handles cleanup automatically:

Option 1 (Merge): Remove worktree after successful merge
Option 2 (PR): Keep worktree until PR is merged
Option 3 (Keep): Keep worktree, you'll handle it
Option 4 (Discard): Remove worktree immediately

For Option 2, I manually clean up after the PR merges:

gh pr merge --delete-branch
git worktree remove .worktrees/feature-user-auth

Practical Example: Complete Feature Flow

Let me walk through a complete scenario:

[After implementing user authentication feature]

Me: Use finishing-a-development-branch

Skill: Running tests...
       npm test
       ✓ 42 tests passing

       Determining base branch...
       Branch splits from 'main'

       Implementation complete. What would you like to do?

       1. Merge back to main locally
       2. Push and create a Pull Request
       3. Keep the branch as-is
       4. Discard this work

Me: 2

Skill: Pushing branch...
       git push -u origin feature/user-auth

       Creating pull request...
       gh pr create --title "Add user authentication" --body "..."

       PR created: https://github.com/myorg/myrepo/pull/42

       Worktree preserved until PR is merged.
       After merge, run: git worktree remove .worktrees/feature-user-auth

Common Mistakes

DO

Fix failing tests before proceeding

Tests failing (2 failures)

[Investigate and fix]

Tests passing. Proceeding...

Choose the right option for your situation

Personal project, confident in code -> Option 1 (local merge)
Team project, needs review -> Option 2 (PR)
Need to pause work -> Option 3 (keep branch)
Went down wrong path -> Option 4 (discard)

Clean up worktrees after PR merge

# After PR is merged
gh pr merge 42 --delete-branch
git worktree remove .worktrees/feature-user-auth
git worktree prune  # Clean up stale references

DON’T

Try to skip the test gate

Me: The tests are flaky, can we proceed anyway?

Skill: Tests failing (3 failures). Cannot proceed.

# The skill enforces this strictly

Merge without understanding the base branch

# Blindly merging without checking base
git checkout main
git merge feature/something  # Might be wrong base!

# CORRECT: Let skill determine base
# Skill finds merge-base and confirms

Forget to clean up worktrees

# Leaving worktrees around
git worktree list
# .worktrees/feature-old-1
# .worktrees/feature-old-2
# .worktrees/feature-old-3
# Disk space wasted, confusion builds

# CORRECT: Clean up after each completion
git worktree remove .worktrees/feature-completed

Create PR without a proper description

gh pr create --title "Fix" --body "fixes stuff"
# Vague, unhelpful for reviewers

# CORRECT: Skill generates proper description
# - Summary section
# - Test plan with checkboxes
# - Co-authored-by attribution

Decision Flowchart

When I’m unsure which option to choose:

                    +------------------+
                    | Tests passing?   |
                    +--------+---------+
                             |
                    +--------v---------+
                    |      YES         |
                    +--------+---------+
                             |
                    +--------v---------+
                    | Team project?    |
                    +--------+---------+
                             |
              +--------------+--------------+
              |                             |
      +-------v-------+             +-------v-------+
      |     YES       |             |      NO       |
      +-------+-------+             +-------+-------+
              |                             |
      +-------v-------+             +-------v-------+
      | Create PR     |             | Want review?  |
      | (Option 2)    |             +-------+-------+
      +---------------+                     |
                                +----------+-----------+
                                |                      |
                        +-------v-------+      +-------v-------+
                        |     YES       |      |      NO       |
                        +-------+-------+      +-------+-------+
                                |                      |
                        +-------v-------+      +-------v-------+
                        | Create PR     |      | Merge locally |
                        | (Option 2)    |      | (Option 1)    |
                        +---------------+      +---------------+

Summary

In this post, I showed how Superpowers’ finishing-a-development-branch skill completes feature branches systematically. The key points are:

Tests MUST pass before any merge or PR—no exceptions
Four clear options after tests pass: merge locally, create PR, keep branch, or discard
Each option triggers a specific, correct workflow
Worktree cleanup is handled based on the chosen option

The skill eliminates the mental overhead of branch completion. Instead of remembering all the steps and edge cases, I trust the process: fix tests, pick an option, let the skill handle the rest.

This skill pairs naturally with using-git-worktrees for workspace isolation and subagent-driven-development for implementation. Together, they form a complete pipeline from design to merged code.

Final Words + More Resources

My intention with this article was to help others share my knowledge and experience. If you want to contact me, you can contact by email: Email me

Here are also the most important links from this article along with some further resources that will help you in this scope:

Oh, and if you found these resources useful, don’t forget to support me by starring the repo on GitHub!