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:

1. Verify all tests pass
2. Determine the base branch and merge strategy
3. Generate a meaningful PR description
4. Execute the chosen action
5. 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 up
• tdd — All code on the branch should have been written test-first
• verification-before-completion — Step 1 (test verification) is an instance of this skill
• dispatching-parallel-agents — If CI fails during PR, use this to fix failures in parallel