Branch Finishing Workflow Skill

A Claude Code skill for completing development branches — verifying tests pass, presenting merge/squash/rebase options, executing the chosen workflow, and cleaning up branches after merging.

When to Use This Skill

Choose this skill when:

• Finishing work on a feature branch and preparing to merge
• Choosing between merge, squash, or rebase strategies
• Verifying all tests pass before merging a branch
• Cleaning up local and remote branches after merging
• Resolving merge conflicts during branch completion
• Creating a PR from a finished branch

Consider alternatives when:

• You're still actively developing on the branch
• You need to set up CI/CD pipelines (use a CI skill)
• You need code review before finishing (use a review skill first)

Quick Start

Copy
# Add to your Claude Code project
claude mcp add branch-finishing

# Finish current branch
claude "finish this branch and merge to main"

# Finish with specific strategy
claude "squash merge this branch into main"

Copy
# .claude/skills/branch-finishing.yml
name: branch-finishing
description: Complete development branches with verification and merge
triggers:
  - "finish branch"
  - "merge branch"
  - "done with branch"
config:
  verify_tests: true
  default_strategy: squash
  cleanup_branch: true

Core Concepts

Finishing Workflow

Step	Action	Gate
1. Verify	Run test suite, linter, type checks	All must pass
2. Status	Show uncommitted changes, unpushed commits	Resolve before proceeding
3. Strategy	Choose merge, squash, or rebase	User decision
4. Execute	Perform the chosen merge operation	No conflicts
5. Push	Push merged result to remote	Push succeeds
6. Cleanup	Delete local and remote feature branch	Optional

Merge Strategies

Strategy	Commit History	Best For
Merge	Preserves all commits + merge commit	Long-lived branches, shared branches
Squash	Combines all into single commit	Feature branches, clean history
Rebase	Replays commits on top of base	Linear history, small branches

Execution Commands

Copy
# Squash merge (most common for feature branches)
git checkout main
git pull origin main
git merge --squash feature/my-feature
git commit -m "Add user notification system (#123)"
git push origin main
git branch -d feature/my-feature
git push origin --delete feature/my-feature

# Rebase merge (for linear history)
git checkout feature/my-feature
git rebase main
git checkout main
git merge --ff-only feature/my-feature
git push origin main

# Standard merge (preserves history)
git checkout main
git merge feature/my-feature
git push origin main

Configuration

Parameter	Type	Default	Description
verify_tests	boolean	true	Run tests before allowing merge
verify_lint	boolean	true	Run linter before allowing merge
verify_types	boolean	true	Run type checker before merge
default_strategy	string	"squash"	Default merge strategy: merge, squash, rebase
cleanup_branch	boolean	true	Delete branch after merge
cleanup_remote	boolean	true	Delete remote branch after merge
base_branch	string	"main"	Target branch for merging
create_pr	boolean	false	Create PR instead of direct merge

Best Practices

1. Always run tests before merging — a broken main branch blocks the entire team; the few minutes spent verifying tests prevents hours of debugging and hotfixing.

2. Squash feature branch commits into one — commit history like "wip", "fix typo", "try again" adds noise; squash into a single descriptive commit that explains what the feature does.

3. Pull the latest base branch before merging — always git pull origin main before merging to catch conflicts early rather than after pushing a broken merge.

4. Delete branches after merging — stale branches clutter the repository; clean up both local and remote copies after a successful merge.

5. Write a meaningful squash commit message — the squash commit represents the entire feature; write it as a clear summary with context, not just the branch name.

Common Issues

Merge conflicts during squash — The feature branch has diverged significantly from main. Rebase onto main first (git rebase main) to resolve conflicts incrementally, then squash merge.

Tests fail on merge but passed on branch — The branch is missing recent changes from main. Pull main into the feature branch, fix any issues, and re-run tests before attempting the merge again.

Accidentally deleted a branch before merging — Check git reflog to find the branch's last commit hash, then recreate the branch with git branch feature-name <commit-hash>. Remote branches can be recovered from the remote if not yet garbage collected.