openspec-finishing-branch
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