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

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: If tests pass: continue to Step 2. Step 2: Detect Environment 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: Detached HEAD — present exactly these 2 options: 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 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: Option 2: Push and Create PR 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: Wait for that exact confirmation. When it arrives: Then clean up the worktree (Step 6) and force delete the 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: 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: 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.

finishing-a-development-branch