Finishing A Development Branch

Options: 1=Merge locally, 2=PR, 3=Keep as-is, 4=Discard (confirm)

Don't use for:

• Work still in progress
• Tests failing
• Epic has open tasks
• Mid-implementation (use hyperpowers:executing-plans)

Announce: "I'm using hyperpowers:finishing-a-development-branch to complete this work."

Verify all tasks closed:

bd dep tree bd-1  # Show task tree
bd list --status open --parent bd-1  # Check for open tasks

If any tasks still open:

Cannot close epic bd-1: N tasks still open:
- bd-3: Task Name (status: in_progress)
- bd-5: Task Name (status: open)

Complete all tasks before finishing.

STOP. Do not proceed.

If all tasks closed:

bd close bd-1

Step 2: Verify Tests

IMPORTANT: Use hyperpowers:test-runner agent to avoid context pollution.

Dispatch hyperpowers:test-runner agent:

Run: cargo test
(or: npm test / pytest / go test ./...)

Agent returns summary + failures only.

If tests fail:

Tests failing (N failures). Must fix before completing:

[Show failures]

Cannot proceed until tests pass.

STOP. Do not proceed.

If tests pass: Continue to Step 3.

Step 3: Determine Base Branch

git merge-base HEAD main 2>/dev/null || git merge-base HEAD master 2>/dev/null

Or ask: "This branch split from main - is that correct?"

Step 4: Present Options

Present exactly these 4 options:

Implementation complete. What would you like to do?

1. Merge back to <base-branch> locally
2. Push and create a Pull Request
3. Keep the branch as-is (I'll handle it later)
4. Discard this work

Which option?

Don't add explanation. Keep concise.

Step 5: Execute Choice

Option 1: Merge Locally

git checkout <base-branch>
git pull
git merge <feature-branch>

# Verify tests on merged result
Dispatch hyperpowers:test-runner: "Run: <test command>"

# If tests pass
git branch -d <feature-branch>

Then: Step 6 (cleanup worktree)

Option 2: Push and Create PR

Get epic info:

bd show bd-1
bd dep tree bd-1

Create PR:

git push -u origin <feature-branch>

gh pr create --title "feat: <epic-name>" --body "$(cat <<'EOF'
## Epic

Closes bd-<N>: <Epic Title>

## Summary
<2-3 bullets from epic implementation>

## Tasks Completed
- bd-2: <Task Name>
- bd-3: <Task Name>

## Test Plan
- [ ] All tests passing
- [ ] <verification steps from epic>
EOF
)"

Then: Step 6 (cleanup worktree)

Option 3: Keep As-Is

Report: "Keeping branch . Worktree preserved at ."

Don't cleanup worktree.

Option 4: Discard

Confirm first:

This will permanently delete:
- Branch <name>
- All commits: <commit-list>
- Worktree at <path>

Type 'discard' to confirm.

Wait for exact "discard" confirmation.

If confirmed:

git checkout <base-branch>
git branch -D <feature-branch>

Then: Step 6 (cleanup worktree)

Step 6: Cleanup Worktree

For Options 1, 2, 4 only:

# Check if in worktree
git worktree list | grep $(git branch --show-current)

# If yes
git worktree remove <worktree-path>

For Option 3: Keep worktree (don't cleanup).

Step 2: SKIPPED test verification

Jump directly to presenting options

"Implementation complete. What would you like to do?

1. Merge back to main locally
2. Push and create PR ..."

User selects Option 1

git checkout main git merge feature-branch

Tests fail! Broken code now on main

# After closing epic
bd close bd-1 ✓

# MANDATORY: Verify tests BEFORE presenting options
Dispatch hyperpowers:test-runner agent: "Run: cargo test"

# Agent reports
"Test suite passed (127 tests, 0 failures, 2.3s)"

# NOW present options
"Implementation complete. What would you like to do?
1. Merge back to main locally
..."

What you gain:

• Confidence tests pass before integration
• No broken code merged to main
• CI/CD stays green
• Other developers unblocked
• Professional workflow

Developer immediately cleans up worktree

git worktree remove ../feature-auth-worktree

PR gets feedback: "Please add rate limiting"

User: "Can you address the PR feedback?"

Worktree is gone! Have to recreate it

git worktree add ../feature-auth-worktree feature-auth

Lost local state, uncommitted experiments, etc.

git push -u origin feature-auth
gh pr create --title "feat: Add OAuth" --body "..."

# Report PR created
"Pull request created: https://github.com/user/repo/pull/42

Keeping worktree at ../feature-auth-worktree for PR updates."

# NO worktree cleanup
# User can address PR feedback in same worktree

Cleanup happens later when:

• PR is merged
• User explicitly requests cleanup
• User uses finishing-a-development-branch again after PR merges

What you gain:

• Worktree available for PR feedback
• No need to recreate worktree
• Preserve local state and experiments
• Efficient PR iteration workflow

Developer immediately executes

git checkout main git branch -D feature-experimental git worktree remove ../feature-experimental-worktree

50 commits deleted

User: "Wait, I meant discard the LAST commit, not the whole branch!"

Too late - work is gone

User: "Discard this work"

"This will permanently delete:
- Branch feature-experimental
- All commits:
  * a1b2c3d Add OAuth integration
  * d4e5f6g Add rate limiting
  * g7h8i9j Update tests
  ... (47 more commits)
- Worktree at ../feature-experimental-worktree

Type 'discard' to confirm."

# WAIT for exact confirmation
User types: "discard"

# NOW execute
git checkout main
git branch -D feature-experimental
git worktree remove ../feature-experimental-worktree

"Branch feature-experimental deleted."

What you gain:

• User sees exactly what will be deleted
• Explicit confirmation required
• Prevents accidental data loss
• Time to reconsider or clarify
• Safe destructive operations

1. Never skip test verification → Tests must pass before presenting options
2. Present exactly 4 options → No open-ended questions
3. Require confirmation for Option 4 → Type "discard" exactly
4. Keep worktree for Options 2 & 3 → PR and keep-as-is need worktree
5. Verify tests after merge (Option 1) → Merged result might break

Common Excuses

All of these mean: STOP. Follow the process.

• "Tests passed earlier, don't need to verify" (Might have changed, verify now)
• "User knows what they want" (Present options, let them choose)
• "Obvious they want to discard" (Require explicit confirmation)
• "PR done, cleanup worktree" (PR likely needs updates, keep worktree)
• "Too many options" (Exactly 4, no more, no less)

• bd epic closed (all child tasks closed)
• Tests verified passing (via test-runner agent)
• Presented exactly 4 options (no open-ended questions)
• Waited for user choice (didn't assume)
• If Option 4: Got typed "discard" confirmation
• Worktree cleaned for Options 1, 4 only (not 2, 3)
• If Option 1: Verified tests on merged result

Can't check all boxes? Return to process and complete missing steps.

Call chain:

hyperpowers:executing-plans → hyperpowers:review-implementation → hyperpowers:finishing-a-development-branch
                         ↓
                   (if gaps found: STOP)

This skill calls:

• hyperpowers:test-runner agent (for test verification)
• bd commands (epic management)
• gh commands (PR creation)

CRITICAL: Never read .beads/issues.jsonl directly. Always use bd CLI commands.

When stuck:

• Tasks won't close → Check bd status, verify all child tasks done
• Tests fail → Fix before presenting options (can't proceed)
• User unsure → Explain options, but don't make choice for them
• Worktree won't remove → Might have uncommitted changes, ask user