From playbooks-virtuoso
Finishes Git development branches end-to-end: verifies working tree/tests/lint, reviews diffs, picks merge/PR/squash/stacked strategy, writes messages, pushes, cleans up. Use when ready to ship.
npx claudepluginhub krzysztofsurdy/code-virtuoso --plugin playbooks-virtuosoThis skill uses the workspace's default tool permissions.
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.
Guides finishing development branches by verifying tests pass, running code reviews with git diffs, auditing test alignment, and presenting merge/PR/cleanup options.
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.
Finalizes development branches: verifies tests pass, presents merge/PR/keep/discard options, executes git workflows including GitHub PR creation, and cleans up worktrees.
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 |