Finishing a Development Branch

tl;dr: this is the end-of-branch skill in Superpowers. The core principle is verify tests → detect environment → present options → execute choice → clean up. The integration decision is always the human’s; the skill’s job is to make sure no work lands, gets force-pushed, or gets force-deleted by an agent reading the room.

What it actually does

SKILL.md (obra/superpowers, fetched 2026-09-10) defines a fixed six-step pipeline the agent announces into the session at the start: “I’m using the finishing-a-development-branch skill to complete this work.”

1. Verify tests. Run the project’s full suite (npm test / cargo test / pytest / go test ./...). Failures stop the pipeline — the menu only appears after green.
2. Detect environment. Three git introspections determine the menu shape and the cleanup path: GIT_DIR, GIT_COMMON, and WORKTREE_PATH. The skill classifies into normal repo, named-branch worktree, or detached HEAD.
3. Determine the base branch. Usually named in the plan or conversation. If unknown, the skill requires you to confirm before merging — “merging into the wrong base is expensive to undo.”
4. Present the menu. Three options exactly as written for a normal repo and named-branch worktree: merge locally, push and create a PR, or keep the branch as-is. Detached HEAD gets a reduced two-option menu — no merge.
5. Execute the choice. Local merge runs git pull, git merge, then the test command on the merged tree. If the merged result is red, the worktree and branch stay put while you investigate. PR option pushes and creates the MR/PR through the forge’s CLI.
6. Clean up the workspace. Runs only on local-merge (and explicit discard). Captures WORKTREE_PATH from Step 2 before the directory change happens. .worktrees/ and worktrees/ paths are Superpowers-owned and removed normally; everything else belongs to the host and stays put.

Discard is a separate path that requires the literal typed word discard — “yeah get rid of it” doesn’t count. The full common-rationalizations table in SKILL.md (lines 99+) reads like a list of every excuse the upstream team wanted to head off: “tests passed earlier this session”, “they obviously want it merged”, “I’ll offer to discard”, “the push was rejected — force-push will fix it”. All eight rebuttals are kept in the skill body verbatim.

When to load it

The description field is the trigger list:

Use when implementation is complete, all tests pass, and you need to decide how to integrate the work

Pair with Executing Plans — that skill chains here at task-complete. If the user says “tests are green, what next?” or “merge or PR?”, load this.

Install

The upstream README does not document npx skills add obra/superpowers. Install is per-harness and the README enumerates thirteen of them. The most common paths:

# Claude Code — official Anthropic marketplace
/plugin install superpowers@claude-plugins-official

# Claude Code — Superpowers marketplace
/plugin marketplace add obra/superpowers-marketplace
/plugin install superpowers@superpowers-marketplace

# Codex CLI — official Codex marketplace
/plugins
# search: superpowers → Install Plugin

# Cursor
/add-plugin superpowers

# Gemini CLI
gemini extensions install https://github.com/obra/superpowers

# OpenCode — host fetches install doc itself
# Say: "Fetch and follow instructions from
#       https://raw.githubusercontent.com/obra/superpowers/main/.opencode/INSTALL.md"

# Antigravity
agy plugin install https://github.com/obra/superpowers

If your host only watches a local SKILL.md, clone the repo and drop this one file:

git clone https://github.com/obra/superpowers
# place at any path your host's skill loader watches:
#   ~/.claude/skills/finishing-a-development-branch/SKILL.md
#   .claude/skills/finishing-a-development-branch/SKILL.md

The executing-plans skill in the same repo calls this one as a required sub-skill. Install the whole skills/ tree, not just one file.

Gotchas

• Base branch is required, not assumed. The skill says “confirm before merging: merging into the wrong base is expensive to undo.” Asking is the right move.
• Test the merged tree, not the pre-merge tree. Step 5 reruns the suite on the merged result. A green pre-merge doesn’t license skipping that.
• Worktree cleanup runs from outside the worktree. The skill captures WORKTREE_PATH in Step 2 before the Step 5 directory change. Agents that skip this capture break removal.
• --force on worktree removal is forbidden. The refusal flag (contains modified or untracked files) means files exist only in that worktree. --force would destroy them permanently. The skill spells out the three-option recovery menu; do not improvise.
• Detached HEAD gets a reduced menu. No local merge option, because there’s no branch to merge into. The two remaining options are PR or keep.
• Force-push requires explicit ask. Rejected push means the remote moved. Investigate before any --force-with-lease or --force.
• sandbox_test.verdict: untested — we read SKILL.md and the README; we did not drive an agent through the menu.

Related: Executing Plans — ends by calling this skill as a required sub-skill; Using Git Worktrees — sets up the workspace this skill later cleans up; Requesting Code Review — runs before this skill, between tasks, not after.