| name | finishing-a-development-branch |
| source | https://raw.githubusercontent.com/obra/superpowers/main/skills/finishing-a-development-branch/SKILL.md |
| description | Finish a development branch — commit, verify, push, open PR. PR is the only path. Load when implementation is complete and tests pass. Triggers: "finish this branch", "wrap up", "open a PR". |
Finishing a Development Branch
Pick the variant that matches your role:
| Role | Variant |
|---|
| Subagent in an assigned worktree | Subagent Variant — commit, verify, report |
| Coordinator after swarm completes | Coordinator Variant — push + open PR |
| Solo work, no swarm | Coordinator Variant, single branch |
Leading word: done when. Every step ends on a checkable criterion.
Hard rule: NEVER merge to main/master. Main receives changes only via pull request.
Subagent Variant
You run inside a worktree the coordinator assigned. You do not merge, push, or present options.
- Commit all work. Stage everything; use
caveman-commit + conventional-commits.
- Verify a clean tree.
git status must show nothing to commit, working tree clean.
- Run the test suite.
npm test / cargo test / pytest / go test ./.... If tests fail, fix or report verbatim — do not claim completion on a red suite.
- Report these four items:
- Branch name
- Commit list (SHA + subject, one per line)
- Test status (command run, pass/fail)
- One-paragraph summary of what changed and why
Done when: the four-item report is delivered. Commits already live in the shared object store — the coordinator handles the rest.
Coordinator Variant
1. Verify tests
Run the full suite. If tests fail, report failures and stop — everything below comes after a green suite. Load verification-before-completion — "tests passed earlier" is not evidence.
Done when: suite is green on the tree you're about to integrate.
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)
WORKTREE_PATH=$(git rev-parse --show-toplevel)
| State | Meaning |
|---|
GIT_DIR == GIT_COMMON | Normal repo, no worktree cleanup needed |
GIT_DIR != GIT_COMMON, named branch | Worktree — cleanup is provenance-based (Step 5) |
GIT_DIR != GIT_COMMON, detached HEAD | Externally managed — leave in place |
3. Confirm base branch
The base is whatever the forked work split from — integration branch for swarm work. If unknown, ask: "This branch split from <best guess> — correct?" Confirm before merging.
4. Merge each subagent branch
For each branch a subagent reported (cross-reference subagent-driven-development):
MAIN_ROOT=$(git -C "$(git rev-parse --git-common-dir)/.." rev-parse --show-toplevel)
cd "$MAIN_ROOT"
git checkout <integration-branch>
git merge --squash <task-branch>
git commit -m "<conventional-commit>"
After all branches merged, run full suite on the merged result. Red: stop, leave everything in place, investigate (nothing pushed, local + recoverable).
If merge conflicts occur during merge, load resolving-merge-conflicts — it handles steps 1–3, and for multi-branch conflicts delegates to subagent-driven-development to unblock in parallel.
5. Push and create PR
git push -u origin <integration-branch> (detached: git push origin HEAD:refs/heads/<new>), follow creating-pull-requests. Keep worktrees for PR feedback.
Done when: PR URL returned, AI disclosure in place, worktrees preserved for PR feedback.
6. Cleanup workspaces
Runs only if work is discarded (explicit request). All other paths preserve worktrees.
GIT_DIR == GIT_COMMON: nothing to clean..worktrees/ or worktrees/: git worktree remove "$path" && git worktree prune.- Otherwise: host environment owns it — leave in place.
Done when: .worktrees/ holds only in-flight work.
