agent-skills/skills/finishing-development-branches/SKILL.md

name, description, license, source

name	description	license	source
finishing-development-branches	Use after implementation is complete and before merging, pushing, opening a Gitea pull request, or cleaning up a feature branch or worktree.	MIT	https://github.com/obra/superpowers/blob/main/skills/finishing-a-development-branch/SKILL.md

Finishing Development Branches

Completion and integration are different decisions. A green feature branch does not authorise merging, pushing, deleting branches, or removing worktrees. Verify the exact tree, identify its provenance, then let the user choose the integration action.

1. Establish the state

From the feature workspace, record:

git status --short
git branch --show-current
git rev-parse HEAD
git rev-parse --show-toplevel
git rev-parse --git-dir
git rev-parse --git-common-dir
git remote -v

Determine the intended base branch from the brief, branch upstream, merge base, or conversation. If it is not confirmed, ask. Do not assume main.

Stop if the tree contains unexplained changes. They may belong to the user or another delegate; do not stage, discard, or fold them into the integration.

2. Verify the branch tip

Run the project’s required targeted and full regression checks on the current HEAD. Read their actual output. For higher-risk changes, run the relevant end-to-end path as required by verification-before-completion.

Also inspect what will integrate:

git log --oneline <base>..HEAD
git diff --check <base>...HEAD
git diff --stat <base>...HEAD

If a check fails, report the failure and stop. Do not offer integration of a known-red branch.

3. Present the integration choices

Report the confirmed base, branch/commit, test evidence, and whether this is a linked worktree. Then offer only applicable choices:

1. Merge locally into the confirmed base.
2. Push the feature branch and open a Gitea pull request.
3. Keep the branch and workspace unchanged for later review.

Wait for the user’s choice. Do not infer permission to push or merge from a request to implement or commit. Never offer deletion as routine cleanup.

4. Execute only the chosen action

Merge locally

Before pulling or contacting a remote, confirm that updating the base from the remote is wanted. From the primary checkout:

git switch <base>
git merge <feature-branch>

Do not use a strategy flag merely to avoid conflicts. If conflicts occur, follow resolving-merge-conflicts; never abort the merge/rebase. Re-run the full verification suite on the merged tree because the result is a different tree from the tested feature tip.

Push and create a Gitea pull request

Confirm the remote and branch names before pushing. Never force-push to solve a rejection; inspect the remote divergence and ask if rewriting remote history would be required. Follow repository/Gitea templates and report the pull request URL. Keep the feature workspace for review fixes.

Keep as-is

Report the branch name, commit, and full workspace path. Make no cleanup changes.

5. Cleanup is separately authorised

Remove a linked worktree or delete a branch only after its work is safely integrated, or after the user explicitly asks to discard it. Before a discard, show the exact branch, worktree path, and commits that would become unreferenced; require an explicit confirmation naming those targets.

Never clean unrelated or merely “stale-looking” worktrees. Never use force-deletion for normal cleanup. After any authorised cleanup, verify with git worktree list and git branch --list and report what was removed.

Stop conditions

Stop and preserve all state when:

• tests or merged-result verification fail;
• the base branch is uncertain;
• the remote has diverged;
• conflicts are unresolved;
• the tree contains unexplained changes;
• the requested action would delete or rewrite work without explicit consent.