| name | finishing-branch |
| description | Decide how to integrate completed branch work via a structured merge / PR / keep / discard menu, with safe worktree cleanup. |
| when_to_use | Use when implementation on a branch is complete and verified and you need to decide what happens to it. Triggers: "wrap this up", "finish this branch", "merge or PR?", "I'm done with this branch", "clean up the worktree", "what do I do with this work now". Skip mid-implementation or when the user already told you exactly how to integrate (just do that).
|
| allowed-tools | Read Bash AskUserQuestion |
Finishing a Branch
Source: adapted from obra/Superpowers skills/finishing-a-development-branch (MIT). Test step
reconciled with our testing-policy.md (no unprompted full-suite runs).
Guide completion of branch work: verify → detect environment → present options → execute → clean up.
Don't ask open-ended "what next?" — present a concrete menu.
Step 1: Verify it's green (per testing-policy.md)
Confirm the work is sound without auto-running the whole test suite:
- Run
verification-loop (build / typecheck / lint) — this is always allowed.
- Tests: only run what
testing-policy.md permits — the tests already covering the changed code
(Case 2), or the suite the user explicitly asked for. Do not kick off the full suite unprompted.
If verification fails, STOP and report — do not proceed to the menu until it's green.
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)
| State | Menu | Cleanup |
|---|
GIT_DIR == GIT_COMMON (normal repo) | 4 options | No worktree to clean |
GIT_DIR != GIT_COMMON, named branch | 4 options | Provenance-based (Step 5) |
GIT_DIR != GIT_COMMON, detached HEAD | 3 options (no local merge) | None (externally managed) |
Determine the base branch: git merge-base HEAD main 2>/dev/null || git merge-base HEAD master 2>/dev/null,
or ask if ambiguous.
Step 3: Present options (exactly these — no extra prose)
Normal repo / named-branch worktree:
1. Merge back to <base> locally
2. Push and create a Pull Request
3. Keep the branch as-is (handle it later)
4. Discard this work
Detached HEAD: drop option 1 (offer push-PR / keep / discard).
Step 4: Execute the choice
- Merge locally —
cd to the main repo root first; git checkout <base> && git pull && git merge <branch>; re-verify (Step 1) on the merged result; then clean up the worktree (Step 5); then
git branch -d <branch>. Merge BEFORE removing anything.
- Push + PR —
git push -u origin <branch>. Do NOT clean up the worktree — the user needs it
to iterate on PR feedback. (Follow git-workflow.md: branch off main, never push to a protected
branch directly; PR body ends with the Claude Code footer.)
- Keep as-is — report the branch + worktree path, change nothing.
- Discard — require a typed
discard confirmation showing exactly what will be deleted (branch,
commits, worktree). Only then: cd to main root, clean up worktree (Step 5), git branch -D <branch>.
Step 5: Worktree cleanup (only for Merge and Discard)
WORKTREE_PATH=$(git rev-parse --show-toplevel)
- If
GIT_DIR == GIT_COMMON: normal repo, nothing to remove.
- If
WORKTREE_PATH is under .worktrees/ or worktrees/: we created it — we clean it up.
cd to the main repo root, then git worktree remove "$WORKTREE_PATH" && git worktree prune
(prune is self-healing for stale registrations).
- Otherwise the harness owns this workspace — do NOT remove it.
Red flags — never
- Proceed with failing verification; merge without re-verifying the merged result.
- Delete work without a typed confirmation; force-push without an explicit request.
- Remove a worktree before confirming the merge succeeded, or from inside the worktree being removed.
- Clean up a worktree you didn't create (always run the provenance check).
Relationship to other skills
verification-loop — the Step 1 green gate./feature-dev, /bug-fix, blueprint — produce the work this skill integrates.
