Help us improve
Share bugs, ideas, or general feedback.
From playbooks-virtuoso
Runs verification checks, reviews the diff, picks the integration path (merge, PR, squash, stacked PR), writes the PR/merge message, pushes, and cleans up branches and worktrees.
npx claudepluginhub krzysztofsurdy/code-virtuoso --plugin agents-virtuosoHow this skill is triggered — by the user, by Claude, or both
Slash command
/playbooks-virtuoso:finishing-branch [optional: branch name or PR target][optional: branch name or PR target]The summary Claude sees in its skill listing — used to decide when to auto-load this skill
The code is written. Tests are green locally. Now what? The gap between "done coding" and "merged to main" is where branches rot, conflicts accumulate, and mistakes happen. This playbook is the systematic bridge: verify, review, integrate, clean up. Every time, in order, nothing skipped.
Runs tests, reviews the diff via multi-provider review, bumps version, updates changelog, creates a PR, and cleans up the branch. Invoke when implementation is complete and ready to ship.
Verifies tests pass on completed feature branch, presents options to merge locally, create GitHub PR, keep as-is or discard; executes choice and cleans up worktree.
Verifies implementation then offers options to merge locally, create PR with verification steps, keep, or discard Git branches at development completion.
Share bugs, ideas, or general feedback.
The code is written. Tests are green locally. Now what? The gap between "done coding" and "merged to main" is where branches rot, conflicts accumulate, and mistakes happen. This playbook is the systematic bridge: verify, review, integrate, clean up. Every time, in order, nothing skipped.
Never push without green. Never merge without review evidence.
# Verify everything passes
git diff --stat main...HEAD
make test && make lint && make typecheck
# Push and open a PR (adjust target as needed)
git push -u origin HEAD
gh pr create --fill
If you need more control, follow the phases below.
Before anything else, ensure the working tree is in a known-good state.
# Check for uncommitted changes
git status
# Check for forgotten stashes
git stash list
# Ensure you are on the right branch
git branch --show-current
# Verify upstream tracking is set
git rev-parse --abbrev-ref --symbolic-full-name @{u}
| Check | Pass Condition | Fix |
|---|---|---|
| No uncommitted changes | git status shows clean tree | Commit or stash intentionally |
| No orphaned stashes | git stash list is empty or all stashes are accounted for | Apply or drop stale stashes |
| Correct branch | Branch name matches your work | git checkout <branch> |
| Upstream set | Tracking branch exists | git push -u origin HEAD on first push |
| No untracked noise | No generated files, build artifacts, or editor files | Add to .gitignore or remove |
Run the full verification suite before pushing. Order matters - fail fast on the cheapest checks first.
# 1. Lint (fastest, catches formatting/style issues)
make lint # or: npm run lint, cargo clippy, flake8, etc.
# 2. Type checking (catches type errors without running code)
make typecheck # or: npx tsc --noEmit, mypy, phpstan, etc.
# 3. Unit tests (fast feedback on logic correctness)
make test # or: npm test, pytest, phpunit, cargo test, etc.
# 4. Integration / end-to-end tests (slower, catches wiring issues)
make test-integration
# 5. Build (ensures the artifact compiles / bundles cleanly)
make build # or: npm run build, cargo build --release, etc.
If any step fails, stop and fix before proceeding. Do not push broken code.
See Pre-Push Checks Reference for the full verification order, CI parity tips, and conflict detection.
Self-review the full diff before handing it to others. You will catch things automated tools miss.
# Full diff against the target branch
git diff main...HEAD
# Commit-by-commit review (more granular)
git log --oneline main..HEAD
git show <commit-hash>
# Stat summary (spot unexpectedly large changes)
git diff --stat main...HEAD
# Check for secrets or sensitive data
git diff main...HEAD | grep -iE '(password|secret|token|api.key|private.key)' || true
console.log, dd(), print_r, var_dump, TODO)Choose how to integrate based on your team's workflow, the branch's history, and the target branch.
| Strategy | When to Use | Command |
|---|---|---|
| Pull Request | Team requires review, CI gates, or audit trail | Push + open PR (see Phase 6) |
| Direct merge | Trunk-based, solo project, or pre-approved change | git checkout main && git merge --no-ff <branch> |
| Squash and merge | Branch has messy intermediate commits | Via PR settings, or: git merge --squash <branch> |
| Rebase and merge | Linear history desired, clean commit discipline | git rebase main && git checkout main && git merge --ff-only <branch> |
| Stacked PR | Branch builds on another unmerged branch | Push + open PR targeting parent branch |
See Integration Strategies Reference for the full decision matrix, rebase vs merge trade-offs, and stacked PR workflow.
Write a clear, structured message whether you are creating a PR or a merge commit.
## Summary
What changed and why (1-3 sentences).
## Changes
- Bullet list of specific changes
## Test Plan
- How to verify the changes work
## Risks
- What could go wrong, migration notes, rollback considerations
## Linked Tickets
- PROJ-123
For comprehensive PR messages, use the pr-message-writer skill which provides templates, structured sections, and verification queries.
See PR Message Template Reference for the full template and guidance on writing effective messages.
# First push (sets upstream tracking)
git push -u origin HEAD
# Subsequent pushes
git push
# After rebase (use --force-with-lease, never --force)
git push --force-with-lease
GitHub:
# Basic PR
gh pr create --title "feat: add user email verification" --body-file pr-description.md
# PR targeting a specific branch (for stacked PRs)
gh pr create --base feat/parent-branch --title "feat: add verification UI"
# Draft PR (not ready for review yet)
gh pr create --draft --fill
GitLab:
glab mr create --title "feat: add user email verification" --description-file pr-description.md
# Target a specific branch
glab mr create --target-branch feat/parent-branch
# Draft MR
glab mr create --draft
Bitbucket:
# Using Bitbucket's REST API via curl
curl -X POST -H "Content-Type: application/json" \
"https://api.bitbucket.org/2.0/repositories/{workspace}/{repo}/pullrequests" \
-d '{"title": "feat: add email verification", "source": {"branch": {"name": "feat/email-verification"}}, "destination": {"branch": {"name": "main"}}}'
# Fetch latest and merge with a merge commit
git checkout main
git pull
git merge --no-ff feat/my-branch -m "Merge feat/my-branch: add user email verification"
# Push main
git push
After the branch is merged, clean up local and remote references.
# Delete the local branch
git branch -d feat/my-branch
# Delete the remote branch (if not auto-deleted by PR merge)
git push origin --delete feat/my-branch
# Prune remote tracking references
git fetch --prune
# If working in a worktree, remove it
git worktree remove /path/to/worktree
See Cleanup Commands Reference for pruning stale branches, worktree cleanup, and upstream maintenance.
Common mistakes and how to fix them.
| Mistake | Recovery |
|---|---|
| Force-pushed the wrong branch | git reflog to find the pre-push commit, then git push --force-with-lease origin <sha>:<branch> |
| Deleted an unmerged branch | git reflog to find the tip, then git checkout -b <branch> <sha> |
| Pushed secrets to remote | Rotate the secret immediately, then git filter-repo to purge from history |
| Merged to wrong target branch | git revert -m 1 <merge-commit> on the wrong target, then merge to the correct one |
| Rebase went wrong mid-way | git rebase --abort to return to pre-rebase state |
| Lost work after worktree removal | git reflog - commits survive worktree deletion if they were committed |
| PR targets wrong base branch | Update the PR's base branch in the hosting platform UI or CLI |
See Recovery Reference for detailed walkthroughs of each recovery scenario.
Run through this before considering the branch done.
--force-with-lease on feature branches only.git reflog if it happens accidentally.--force-with-lease instead of --force. It prevents overwriting someone else's work on a shared branch.| Reference | Contents |
|---|---|
| Pre-Push Checks | Verification command order, CI parity, conflict detection, pre-push hook setup |
| Integration Strategies | Merge vs rebase vs squash decision matrix, stacked PRs, when each strategy fits |
| PR Message Template | Structured PR template, writing guidance, cross-reference to pr-message-writer skill |
| Cleanup Commands | Branch pruning, worktree removal, upstream cleanup, batch operations |
| Recovery | Detailed recovery walkthroughs for force-push, deleted branch, lost stash, bad merge |
| Situation | Recommended Skill |
|---|---|
| Writing a comprehensive PR message | pr-message-writer |
| Reviewing code before merging | code-review-excellence |
| Managing git worktrees | worktree-start, worktree-list, worktree-switch, worktree-clean |
| Choosing a branching strategy | git-workflow |
| Running verification before declaring done | verification-before-completion |
| Requesting a structured code review | requesting-code-review |