Finishing a development branch

Finishes a branch: runs the tests, offers to merge locally, open a pull request or keep it as is, reruns the tests after a merge and removes its own worktree, and discards work only after you type "discard". Use when the implementation is done.

Git & PRsPack: Superpowers225 linesfinishing-a-development-branch
Author
Source
obra/superpowers/skills/finishing-a-development-branch @ 22f0b46
License
MIT · Copyright (c) 2025 Jesse Vincent

About this skill

What it does

The skill handles the moment the code is written and the branch has to go somewhere. The agent runs the full test suite and stops if anything fails. Then it works out where it is — an ordinary checkout, a worktree on a named branch, or a detached HEAD the host manages — confirms the base branch if it is not known, and shows a fixed menu: merge locally, push and open a pull request, or keep the branch as it is. A detached HEAD gets no merge option. The choice is yours; the agent waits.

A local merge reruns the tests on the merged result and only then removes the worktree and deletes the branch with git branch -d. A pull request is opened with the forge's CLI or the link printed on push, following the repository's PR template, and the worktree stays for review fixes. Discarding work is not on the menu: it happens only if you ask and then type discard. Cleanup touches only worktrees under .worktrees/ or worktrees/, which Superpowers created; if one still holds uncommitted files, the agent lists them and asks instead of using --force. A rejected push is never force-pushed unless you say so.

The folder holds only SKILL.md and the licence.

When to use it, and when not

Use it when the implementation is done and integration should go the same way every time, especially with agents working in worktrees.

It will not help while tests are red: it reports the failures and stops. It does not review the code, judge production readiness or say what the PR description should contain.

How to run it

The install command below puts the folder in place. The agent picks the skill up by its description; to call it yourself:

  • Claude Code: /finishing-a-development-branch, or ask for the skill by name.
  • Codex: $finishing-a-development-branch.
  • Cursor: type / in the Agent chat and pick finishing-a-development-branch.

Example: /finishing-a-development-branch The rate-limit work is done. Run the tests and give me the options for this branch.

executing-plans and subagent-driven-development call this skill as their last step, and its cleanup expects the layout that using-git-worktrees creates. Install them together.

How it differs from similar skills

Self-review before PR from our catalog reads the diff for debug output, secrets, scope creep and missing tests. This skill does not read the code at all, so run self-review first. PR description writer writes the body of the pull request that option 2 opens; PR title and description writer from Sentry writes it too and opens the PR itself as a draft. Iterate a PR until CI is green takes over once the PR is open: it fixes failing checks and high- and medium-priority review comments, pushes and repeats until CI passes. Release checklist comes later: a go/no-go review before shipping, with migrations, config and rollback.

Install

Run one command — it saves SKILL.md and the files it uses into your agent's skills folder. Claude Code and Codex pick up a new skill without a restart; if it does not show up, restart the agent.

Claude Code — macOS, Linux
curl -fsSL --create-dirs -o ~/.claude/skills/finishing-a-development-branch/SKILL.md https://anymodel.org/en/skills/superpowers/finishing-a-development-branch/SKILL.md -o ~/.claude/skills/finishing-a-development-branch/LICENSE https://anymodel.org/en/skills/superpowers/finishing-a-development-branch/LICENSE
Codex, Cursor — macOS, Linux
curl -fsSL --create-dirs -o ~/.agents/skills/finishing-a-development-branch/SKILL.md https://anymodel.org/en/skills/superpowers/finishing-a-development-branch/SKILL.md -o ~/.agents/skills/finishing-a-development-branch/LICENSE https://anymodel.org/en/skills/superpowers/finishing-a-development-branch/LICENSE
Claude Code — Windows PowerShell
foreach ($f in 'SKILL.md','LICENSE') { $p = Join-Path "$HOME\.claude\skills\finishing-a-development-branch" $f; New-Item -ItemType Directory -Force (Split-Path $p) | Out-Null; Invoke-WebRequest "https://anymodel.org/en/skills/superpowers/finishing-a-development-branch/$f" -UseBasicParsing -OutFile $p }
Codex, Cursor — Windows PowerShell
foreach ($f in 'SKILL.md','LICENSE') { $p = Join-Path "$HOME\.agents\skills\finishing-a-development-branch" $f; New-Item -ItemType Directory -Force (Split-Path $p) | Out-Null; Invoke-WebRequest "https://anymodel.org/en/skills/superpowers/finishing-a-development-branch/$f" -UseBasicParsing -OutFile $p }

Any other agent: save the file into its skills folder, or give it the link to the file: https://anymodel.org/en/skills/superpowers/finishing-a-development-branch/SKILL.md

SKILL.md

Raw

Finishing a Development Branch

Overview

Core principle: Verify tests → Detect environment → Present options → Execute choice → Clean up.

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

Step 1: Verify Tests

Run the project's full test suite (npm test / cargo test / pytest / go test ./...).

If tests fail, report the failures and stop — the menu comes after a green suite:

Tests failing (<N> failures). Must fix before completing:

[Show failures]

If tests pass: continue to Step 2.

Step 2: Detect Environment

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)
# Capture now, while still inside the workspace — Step 5 changes directory
# before cleanup (Step 6) needs this value
WORKTREE_PATH=$(git rev-parse --show-toplevel)

This determines which menu to show and how cleanup works:

State Menu Cleanup
GIT_DIR == GIT_COMMON (normal repo) Standard 3 options No worktree to clean up
GIT_DIR != GIT_COMMON, named branch Standard 3 options Provenance-based (see Step 6)
GIT_DIR != GIT_COMMON, detached HEAD Reduced 2 options (no merge) Externally managed — leave in place

Step 3: Determine Base Branch

The base branch is whatever this work forked from — usually named in the plan, the conversation, or the branch's upstream. If it is not already known, ask: "This branch split from <your best guess> - is that correct?" Confirm before merging: merging into the wrong base is expensive to undo.

Step 4: Present Options

Normal repo and named-branch worktree — present exactly these 3 options:

Implementation 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)

Which option?

Detached HEAD — present exactly these 2 options:

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

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

Which option?

Present the menu exactly as written — concise, with every option coming from the list above. Discarding the work happens only in response to your human partner explicitly asking for it (see "If your human partner asks to discard the work" below). Wait for their answer; the integration decision is theirs.

Step 5: Execute Choice

Option 1: Merge Locally

# Get main repo root for CWD safety
MAIN_ROOT=$(git -C "$(git rev-parse --git-common-dir)/.." rev-parse --show-toplevel)
cd "$MAIN_ROOT"

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

# Verify tests on merged result
<test command>

If tests fail on the merged result: stop, leave the worktree and branch in place, and investigate — nothing has been pushed, so the merge is local and recoverable.

Once the merged result is green: clean up the worktree (Step 6), then delete the branch:

git branch -d <feature-branch>

Option 2: Push and Create PR

git push -u origin <feature-branch>
# From a detached HEAD, name the new branch on the remote:
# git push origin HEAD:refs/heads/<new-branch>

Then create the pull/merge request against <base-branch> with the forge's tooling — its CLI if one is available, or the creation URL most forges print when you push — following the repo's PR template and conventions if present, and report the URL to your human partner.

Keep the worktree — your human partner iterates on PR feedback there.

Option 3: Keep As-Is

Report: "Keeping branch <name>. Worktree preserved at <path>."

If your human partner asks to discard the work

This path exists only as a response to an explicit request to throw the work away. Confirm first:

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

Type 'discard' to confirm.

Wait for that exact confirmation. When it arrives:

MAIN_ROOT=$(git -C "$(git rev-parse --git-common-dir)/.." rev-parse --show-toplevel)
cd "$MAIN_ROOT"

Then clean up the worktree (Step 6) and force-delete the branch:

git branch -D <feature-branch>

Step 6: Cleanup Workspace

Runs for Option 1 and confirmed discards. Options 2 and 3 always preserve the worktree. Both callers have already changed directory to the main repo root — worktree removal must run from outside the worktree — and use the GIT_DIR/GIT_COMMON/WORKTREE_PATH values captured in Step 2, from before that directory change.

If GIT_DIR == GIT_COMMON: Normal repo, no worktree to clean up. Done.

If WORKTREE_PATH is under .worktrees/ or worktrees/: Superpowers created this worktree — we own cleanup:

git worktree remove "$WORKTREE_PATH"
git worktree prune  # Self-healing: clean up any stale registrations

If removal is refused (contains modified or untracked files): the worktree holds files that exist nowhere else — uncommitted plans, notes, or scratch work. Never --force on your own initiative. Show your human partner what is at stake and ask:

git -C "$WORKTREE_PATH" status --porcelain -uall
Worktree removal refused — these files were never committed:

<file list>

1. Commit them to <branch> before cleanup
2. Move them into <main repo root>
3. Delete them (unrecoverable)

Which?

Carry out the choice, then remove the worktree.

Otherwise: The host environment owns this workspace — leave it in place. If your platform provides a workspace-exit tool, use it.

Quick Reference

Option Merge Push Keep Worktree Cleanup Branch
1. Merge locally yes - - yes
2. Create PR - yes yes -
3. Keep as-is - - yes -
Discard (explicit request only) - - - yes (force)

Common Rationalizations

Excuse Reality
"Tests passed earlier this session" Run the suite on the tree you are about to integrate. A green run only proves the tree it ran on.
"They obviously want it merged" Integration is your human partner's decision. Present the menu and wait.
"They seem done with this feature — I'll offer to discard it" The menu is complete as written. Discard happens only when your human partner asks for it in so many words.
"'Yeah, get rid of it' counts as confirmation" Only the typed word discard authorizes deletion.
"The PR is up, so the worktree is clutter now" PR feedback gets fixed in that worktree. It stays until the work lands.
"This other worktree looks stale — I'll clean it too" Clean up only worktrees under .worktrees/ or worktrees/. Everything else belongs to the host.
"Removal refused — --force is just finishing the cleanup" The refusal means files exist only in that worktree. --force destroys them permanently. Show your human partner and ask.
"The merged-result failure is probably flaky" A failing merged result stops everything. Branch and worktree stay put while you investigate.
"The base branch is obviously main" Confirm the fork point or ask. Merging into the wrong base is expensive to undo.
"The push was rejected — force-push will fix it" A rejected push means the remote moved. Investigate; force-push only on your human partner's explicit request.

Connect through AnyModel API

This skill runs on whatever model your agent uses. Point Claude Code, Codex or Cursor at AnyModel to run it on Claude, GPT, Gemini and more with one key — pay per token, no subscription.

More from the pack Superpowers

Brainstorming before you build

Finds out what you want to build and why: one question at a time, its understanding played back part by part, two or three approaches to pick from and a design doc, with no code until you approve it. Use for a new feature or change when the request leaves the essentials open.

Dispatching parallel agents

Splits independent problems between parallel subagents, each with one domain and a self-contained brief with scope, constraints and the report expected back, then checks their edits for conflicts and runs the full suite. Use when several unrelated things fail at once.

Executing plans

Runs a plan from writing-plans in the current session with no subagent per task: tasks in order through TDD, a ledger of progress and rulings that survives context compaction, and one fresh review of the whole branch at the end. Use when per-task review is not needed or there are no subagents.

Receiving code review

Checks each review comment against the code before changing anything, clears up every unclear item first, pushes back with technical reasons and never performs agreement. Use when working through review feedback without blind fixes.

Requesting code review

Hands finished work to a fresh reviewer subagent through a template: the commit range, the plan or requirements, findings by severity and a verdict on merging. Use when a task or feature is done and a merge to main is next.

Subagent-driven development

Executes a plan through subagents: a fresh implementer and reviewer for every task, checking spec compliance and code quality, up to five fix rounds and a final review of the whole branch. Use for a plan of independent tasks when each one needs a review.

Systematic debugging

Keeps the agent from guessing at fixes: reproduce the bug and find the root cause first, test one hypothesis at a time, fix with a failing test, and question the design after three failed fixes. Use for any bug, test failure or unexpected behavior.

Test-driven development, Superpowers style

Drives work test-first: a test seen failing, then the least code that passes and a run of the whole suite; code written before its test is deleted. Use for features and bug fixes when the agent tends to add tests after the code.

Using git worktrees

Moves feature work into an isolated git worktree: checks whether the agent is already isolated, prefers the harness's own worktree tool, keeps the folder git-ignored, installs dependencies and runs a baseline test. Use when the work must not land on the branch you have open.

Verification before completion

Stops the agent from saying "done" or "tests pass" until it has rerun the check and read the whole output. Use whenever the agent reports success, commits or opens a pull request.

Writing implementation plans

Turns a spec into a plan for an implementer new to the codebase: files, signatures, interfaces between tasks, tests with exact values and TDD steps with each command's expected output. Use for a multi-step task when the spec is ready and no code exists yet.

Writing skills

Writes and edits skills the TDD way: a subagent first does the task without the skill and its mistakes are written down, then the smallest text that answers them goes in and the loopholes get closed. Use for a skill that other agents will load.