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

> Safely finish your development branch in Superpowers. Learn the complete workflow, from test verification to automatic cleanup, ensuring a seamless integration.

- Repository: [Jesse Vincent/superpowers](https://github.com/obra/superpowers)
- Tags: how-to-guide
- Published: 2026-02-16

---

**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`](https://github.com/obra/superpowers/blob/main/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`](https://github.com/obra/superpowers/blob/main/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`](https://github.com/obra/superpowers/blob/main/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:

```bash

# 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`](https://github.com/obra/superpowers/blob/main/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`:

```bash
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`](https://github.com/obra/superpowers/blob/main/skills/finishing-a-development-branch/SKILL.md):

**Option 1 (Local Merge) commands:**

```bash
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:**

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

```

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

```bash
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:

```bash
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`](https://github.com/obra/superpowers/blob/main/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`](https://github.com/obra/superpowers/blob/main/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`](https://github.com/obra/superpowers/blob/main/package.json) for `npm test`, [`Cargo.toml`](https://github.com/obra/superpowers/blob/main/Cargo.toml) for `cargo test`). While the skill definition in [`skills/finishing-a-development-branch/SKILL.md`](https://github.com/obra/superpowers/blob/main/skills/finishing-a-development-branch/SKILL.md) specifies these standard commands, the underlying execution through [`lib/skills-core.js`](https://github.com/obra/superpowers/blob/main/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.