Finishing a Development Branch (OpenSpec Integration)

Overview

Guide completion of development work: verify tests → present options → execute choice → archive OpenSpec change.

Core principle: Verify tests → Present options → Execute choice → Clean up → Archive specs.

Announce at start: "I'm using openspec-finishing-branch to complete this work."

The Process

Step 1: Verify Tests

Run project's test suite. If tests fail, stop. Cannot proceed until tests pass.

Step 2: Determine Base Branch

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

Step 3: Present 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?

Step 4: Execute Choice

Option 1: Merge Locally

git checkout <base-branch>
git pull
git merge <feature-branch>
# Verify tests on merged result
git branch -d <feature-branch>

Option 2: Push and Create PR

git push -u origin <feature-branch>
gh pr create --title "<title>" --body "<summary>"

Option 3: Keep As-Is

Report and preserve.

Option 4: Discard

Confirm, then delete branch.

Step 5: Cleanup Worktree

For Options 1, 2, 4 — remove worktree.
For Option 3 — keep worktree.

Step 6: Archive OpenSpec Change (NEW)

This is the key addition over standard Superpowers.

For Options 1 and 2 (merge/PR):

# Validate the change first
openspec validate <name> --json

# Archive — merges delta specs into project's main spec baseline
openspec archive <name> --yes

This preserves the formal specs in openspec/specs/ so knowledge accumulates across changes.

For Option 3 (keep as-is):
No archive action. Change remains in openspec/changes/.

For Option 4 (discard):

# Remove the change without merging specs
rm -rf openspec/changes/<name>

If archive fails: Report the error but do NOT block the git operation. Archive is advisory.

Remember

• Verify tests before offering options
• Present exactly 4 options
• Get typed confirmation for Option 4
• Always archive on merge/PR — this is how knowledge compounds
• Archive failure is non-blocking