Finishing a Development Branch
Adapted from obra/superpowers — MIT. Structured end-of-feature workflow for the NodeJS-Starter-V1 monorepo.
Overview
Before merging or creating a PR, every development branch must pass a structured completion protocol:
- Verify all tests pass
- Determine the base branch and merge strategy
- Generate a meaningful PR description
- Execute the chosen action
- Clean up worktrees and stale branches
Step 1: Verify Tests Pass
MANDATORY. Never skip this step.
# Full monorepo test suite — must be green
pnpm turbo run test
# Type check — must be 0 errors
pnpm turbo run type-check
# Lint — must be clean
pnpm turbo run lint
# Optional: coverage check
cd apps/backend && uv run pytest --cov=src --cov-fail-under=40
If ANY check fails → stop. Fix the failures before offering merge options. Do not create a PR with failing tests.
Step 2: Review Commits and Determine Base Branch
# What's on this branch vs main?
git log --oneline main..HEAD
# What files changed?
git diff main...HEAD --name-only
# Full diff for PR description generation
git diff main...HEAD
Determine base branch:
main— standard for all feature branches (NodeJS-Starter-V1 uses trunk-based development)release/*— if releasing to a specific version branch
Step 3: Generate PR Description
Based on the commit log and diff, generate:
## Summary
- <bullet: what was implemented/changed>
- <bullet: why this change was made>
- <bullet: key technical decisions>
## Test Plan
- [ ] `pnpm turbo run test` — all N tests passing
- [ ] `pnpm turbo run type-check` — 0 TypeScript errors
- [ ] `pnpm turbo run lint` — clean
- [ ] <manual smoke test step if applicable>
- [ ] <specific feature test step>
## Related
<!-- Link any Linear issues, PRs, or docs -->
PR title format (Conventional Commits):
feat(web): add contractor availability calendar component
fix(backend): resolve JWT token expiry race condition
refactor(db): migrate contractor model to SQLAlchemy 2.0 style
docs(claude): update CLAUDE.md with new auth endpoints
Step 4: Present Options
Present exactly these 4 options:
Branch: feature/<name>
Base: main
Tests: ✅ N passing
What would you like to do?
1. Merge to main locally (fast-forward or squash)
2. Push and create a Pull Request
3. Keep branch as-is for later
4. Discard the work (type "discard" to confirm)
Option 1: Merge Locally
# Switch to main
git checkout main
# Fast-forward merge (clean history)
git merge --ff-only feature/<name>
# OR squash merge (single clean commit)
git merge --squash feature/<name>
git commit -m "feat(<scope>): <description>"
# Push
git push origin main
Option 2: Push and Create PR
# Push the feature branch
git push -u origin feature/<name>
# Create PR via GitHub CLI
gh pr create \
--title "feat(<scope>): <description>" \
--body "$(cat <<'EOF'
## Summary
- <bullet points>
## Test Plan
- [ ] pnpm turbo run test — N tests passing
- [ ] pnpm turbo run type-check — 0 errors
- [ ] pnpm turbo run lint — clean
🤖 Generated with [Claude Code](https://claude.com/claude-code)
EOF
)" \
--base main
The PR is labelled review-required. Never merge without human review.
Option 3: Keep Branch As-Is
# Push to remote for safekeeping
git push -u origin feature/<name>
# Note the branch for future reference
echo "Preserved: feature/<name> — <reason>"
Worktree is kept intact.
Option 4: Discard (Requires Typed Confirmation)
Require the user to type discard before proceeding:
⚠️ This will permanently delete all work on feature/<name>.
Type "discard" to confirm: _
# After confirmation
git checkout main
git branch -D feature/<name>
git push origin --delete feature/<name> 2>/dev/null || true
Step 5: Clean Up Worktree
For Options 1, 4: Remove worktree immediately after action. For Option 2 (PR): Remove worktree after PR is created (branch still exists on remote). For Option 3 (Keep): Preserve worktree until explicitly cleaned up.
# Return to project root
cd "D:\Node JS Starter V1"
# Remove worktree
git worktree remove .worktrees/<feature-name>
# Prune any stale references
git worktree prune
# Verify clean state
git worktree list
git branch -vv | grep gone | awk '{print $1}' # List orphaned local branches
Stale Branch Cleanup
Run periodically to keep the repo clean:
# List branches merged into main
git branch --merged main | grep -v "^\*\|main"
# Delete merged local branches
git branch --merged main | grep -v "^\*\|main" | xargs git branch -d
# Prune deleted remote branches
git fetch --prune
# List remote branches
git branch -r | grep -v "HEAD\|main"
NodeJS-Starter-V1 PR Checklist
Before creating a PR, verify all of the following:
□ pnpm turbo run test — all tests passing (show count)
□ pnpm turbo run type-check — 0 TypeScript errors
□ pnpm turbo run lint — clean output
□ git status — working tree clean, all changes committed
□ git log --oneline main..HEAD — commits make sense, no junk commits
□ PR description generated with Summary + Test Plan sections
□ Conventional Commit format in PR title
□ Linear issue linked (if applicable)
□ No TODO comments left in code (or intentional TODOs noted in PR)
Merge Strategy Guide
| Scenario | Strategy | Why |
|----------|----------|-----|
| Single clean commit | --ff-only | Preserves linear history |
| Multiple messy commits | --squash | Clean history, single commit per feature |
| Complex feature with meaningful history | Regular merge | Preserves context |
| Hotfix | --ff-only directly to main | Fast, no PR needed |
NodeJS-Starter-V1 default: squash merge into main for features. This keeps git log --oneline readable.
Integration with Git Worktrees Skill
This skill is the natural exit point for the git-worktrees skill:
git-worktrees skill → [feature work] → finishing-branch skill
↑ ↓
Create worktree Merge/PR + cleanup worktree
After PR is approved and merged, return here to run Step 5 cleanup.
Related Skills
git-worktrees— Creates the worktree that this skill cleans uptdd— All code on the branch should have been written test-firstverification-before-completion— Step 1 (test verification) is an instance of this skilldispatching-parallel-agents— If CI fails during PR, use this to fix failures in parallel