How to Finish a Development Branch in Superpowers: Complete Workflow Guide

To finish a development branch in Superpowers, you run the finishing-a-development-branch skill, which enforces a test-first workflow that verifies all tests pass, determines the base branch, presents four integration options, and automatically cleans up worktrees.

The obra/superpowers repository provides an AI-assisted development framework where skills automate complex Git workflows. When you need to finish a development branch in Superpowers, the system guides you through a safe, automated shutdown process defined in skills/finishing-a-development-branch/SKILL.md.

The Finishing Workflow Overview

The finishing process follows a strict, automated sequence designed to prevent data loss and ensure code quality. According to the source code in skills/finishing-a-development-branch/SKILL.md, the skill orchestrates five critical phases: test verification, base branch detection, option presentation, execution, and worktree cleanup.

This workflow is typically invoked by higher-level skills such as subagent-driven-development (defined in skills/subagent-driven-development/SKILL.md) after all planned tasks are complete, or manually when you need to integrate or discard a feature branch.

Step-by-Step Process to Finish a Development Branch

Verify All Tests Pass

The first step in the finishing workflow is mandatory test verification. The skill automatically runs the project's test suite using the appropriate command for the detected language:

# Examples of test commands executed by the skill

npm test            # Node.js projects

cargo test          # Rust projects

pytest              # Python projects

go test ./...       # Go projects

If any test fails, the workflow immediately stops. You must fix the failures before proceeding. This enforcement appears in the "Verify Tests" section of skills/finishing-a-development-branch/SKILL.md (lines 18-34).

Determine the Base Branch

Once tests pass, the skill attempts to auto-detect the base branch by finding the common ancestor with main or master:

git merge-base HEAD main || git merge-base HEAD master

If the skill cannot automatically determine the correct base branch, it prompts you to confirm the target branch before proceeding. This step ensures that merge operations target the correct integration point.

Choose Your Integration Strategy

The skill presents exactly four options for finishing the branch. It never adds extra prose or suggestions beyond these numbered choices:

1. Merge back to <base-branch> locally – Switch to the base branch, pull latest changes, merge the feature branch, re-run tests, then delete the feature branch.
2. Push and create a Pull Request – Push the feature branch to the remote and open a PR using gh pr create.
3. Keep the branch as-is – Leave the branch and its worktree untouched for later work.
4. Discard this work – After requiring a typed "discard" confirmation, delete the branch and its worktree.

These options are defined in the "Present Options" section of the skill file (lines 49-60).

Execute the Selected Option

Each option maps to a concrete set of Git commands implemented in the "Execute Choice" sections of skills/finishing-a-development-branch/SKILL.md:

Option 1 (Local Merge) commands:

git checkout <base-branch>
git pull
git merge <feature-branch>
npm test  # or appropriate test command

git branch -d <feature-branch>

Option 2 (Pull Request) commands:

git push -u origin <feature-branch>
gh pr create

Option 4 (Discard) commands: Requires explicit "discard" confirmation, then:

git branch -D <feature-branch>

# plus worktree removal if applicable

Cleanup the Worktree

For Options 1, 2, and 4, the skill automatically checks whether the current branch lives in a separate Git worktree and removes it:

git worktree list | grep $(git branch --show-current) && \
  git worktree remove <worktree-path>

Option 3 deliberately preserves the worktree since the branch remains active. This cleanup logic appears in the "Cleanup Worktree" step (lines 36-49).

Safety Mechanisms and Red Flags

The finishing-a-development-branch skill enforces several non-negotiable safety rules:

• No merging without passing tests – The workflow halts immediately if the test suite reports failures.
• No accidental discards – Option 4 requires typing the word "discard" explicitly to prevent data loss.
• Automatic worktree cleanup – Destructive operations (merge, discard) always clean up associated worktrees to prevent orphaned directories.
• Base branch verification – The skill confirms the target branch before executing merge operations.

These constraints are implemented in lib/skills-core.js (lines 151-160), which provides the runtime execution environment for skill-defined shell snippets.

Summary

To finish a development branch in Superpowers:

• Run the finishing-a-development-branch skill to initiate the automated workflow defined in skills/finishing-a-development-branch/SKILL.md.
• Ensure all tests pass before proceeding, as the skill enforces test verification as a blocking step.
• Select from four specific options: merge locally, create a pull request, keep the branch, or discard the work.
• Allow automatic cleanup of worktrees for all destructive operations to maintain a clean repository state.

Frequently Asked Questions

What happens if my tests fail when trying to finish a branch?

If any test fails during the verification step, the skill immediately stops the workflow. You must fix the failing tests and re-run the finishing skill before you can proceed with merging, creating a pull request, or discarding the branch. This ensures that only verified code moves forward in the integration process.

Can I customize the test command that runs when finishing a branch?

The skill automatically detects the appropriate test command based on project files (e.g., package.json for npm test, Cargo.toml for cargo test). While the skill definition in skills/finishing-a-development-branch/SKILL.md specifies these standard commands, the underlying execution through lib/skills-core.js runs the detected command as a shell snippet. Custom test commands would require modifying the skill definition or ensuring your project uses standard tooling conventions.

What is the difference between Option 1 (merge locally) and Option 2 (create PR)?

Option 1 performs a local merge workflow: it switches to the base branch, pulls latest changes, merges your feature branch, re-runs tests on the merged code, and deletes the feature branch. This is ideal for solo work or when you have merge privileges and want immediate integration.

Option 2 pushes your branch to the remote repository and opens a Pull Request using the GitHub CLI (gh pr create). This is the correct choice when you need code review, CI checks on the remote, or when repository policies prohibit direct pushes to the base branch.

Does the skill handle worktrees automatically?

Yes, the skill automatically manages Git worktrees for all destructive operations. When you select Option 1 (merge), Option 2 (push/PR), or Option 4 (discard), the skill checks if the current branch exists in a separate worktree using git worktree list, and if so, removes it with git worktree remove. If you select Option 3 (keep branch), the worktree is deliberately preserved so you can continue working.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}