Initial commit

2025-11-30 09:06:38 +08:00
commit ed3e4c84c3
76 changed files with 20449 additions and 0 deletions
--- a/skills/finishing-a-development-branch/SKILL.md
+++ b/skills/finishing-a-development-branch/SKILL.md
@@ -0,0 +1,482 @@
+---
+name: finishing-a-development-branch
+description: Use when implementation complete and tests pass - closes bd epic, presents integration options (merge/PR/keep/discard), executes choice
+---
+
+<skill_overview>
+Close bd epic, verify tests pass, present 4 integration options, execute choice, cleanup worktree appropriately.
+</skill_overview>
+
+<rigidity_level>
+LOW FREEDOM - Follow the 6-step process exactly. Present exactly 4 options. Never skip test verification. Must confirm before discarding.
+</rigidity_level>
+
+<quick_reference>
+| Step | Action | If Blocked |
+|------|--------|------------|
+| 1 | Close bd epic | Tasks still open → STOP |
+| 2 | Verify tests pass (test-runner agent) | Tests fail → STOP |
+| 3 | Determine base branch | Ask if needed |
+| 4 | Present exactly 4 options | Wait for choice |
+| 5 | Execute choice | Follow option workflow |
+| 6 | Cleanup worktree (options 1,2,4 only) | Option 3 keeps worktree |
+
+**Options:** 1=Merge locally, 2=PR, 3=Keep as-is, 4=Discard (confirm)
+</quick_reference>
+
+<when_to_use>
+- Implementation complete and reviewed
+- All bd tasks for epic are done
+- Ready to integrate work back to main branch
+- Called by hyperpowers:review-implementation (final step)
+
+**Don't use for:**
+- Work still in progress
+- Tests failing
+- Epic has open tasks
+- Mid-implementation (use hyperpowers:executing-plans)
+</when_to_use>
+
+<the_process>
+## Step 1: Close bd Epic
+
+**Announce:** "I'm using hyperpowers:finishing-a-development-branch to complete this work."
+
+**Verify all tasks closed:**
+
+```bash
+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:**
+
+```bash
+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
+
+```bash
+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
+
+```bash
+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:**
+
+```bash
+bd show bd-1
+bd dep tree bd-1
+```
+
+**Create PR:**
+
+```bash
+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 <name>. Worktree preserved at <path>."
+
+**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:**
+
+```bash
+git checkout <base-branch>
+git branch -D <feature-branch>
+```
+
+Then: Step 6 (cleanup worktree)
+
+---
+
+## Step 6: Cleanup Worktree
+
+**For Options 1, 2, 4 only:**
+
+```bash
+# 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).
+</the_process>
+
+<examples>
+<example>
+<scenario>Developer skips test verification before presenting options</scenario>
+
+<code>
+# Step 1: Epic closed ✓
+bd close bd-1
+
+# 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
+</code>
+
+<why_it_fails>
+- Skipped mandatory test verification
+- Merged broken code to main branch
+- Other developers pull broken main
+- CI/CD fails, blocks deployment
+- Must revert, fix, merge again (wasted time)
+</why_it_fails>
+
+<correction>
+**Follow Step 2 strictly:**
+
+```bash
+# 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
+</correction>
+</example>
+
+<example>
+<scenario>Developer auto-cleans worktree for PR option</scenario>
+
+<code>
+# User selects Option 2: Create PR
+git push -u origin feature-auth
+gh pr create --title "feat: Add OAuth" --body "..."
+
+# 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.
+</code>
+
+<why_it_fails>
+- Cleaned worktree when PR still active
+- User likely needs worktree for PR feedback
+- Have to recreate worktree for changes
+- Lost any local uncommitted work
+- Inefficient workflow
+</why_it_fails>
+
+<correction>
+**Option 2 workflow (correct):**
+
+```bash
+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
+</correction>
+</example>
+
+<example>
+<scenario>Developer discards work without confirmation</scenario>
+
+<code>
+# User says: "Actually, discard this work"
+
+# 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
+</code>
+
+<why_it_fails>
+- No confirmation before destructive action
+- Misunderstood user intent
+- Permanent data loss
+- No way to recover work
+- Catastrophic for user
+</why_it_fails>
+
+<correction>
+**Option 4 workflow (correct):**
+
+```
+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
+</correction>
+</example>
+</examples>
+
+<option_matrix>
+| Option | Merge | Push | Keep Worktree | Cleanup Branch | Cleanup Worktree |
+|--------|-------|------|---------------|----------------|------------------|
+| 1. Merge locally | ✓ | - | - | ✓ | ✓ |
+| 2. Create PR | - | ✓ | ✓ | - | - |
+| 3. Keep as-is | - | - | ✓ | - | - |
+| 4. Discard | - | - | - | ✓ (force) | ✓ |
+</option_matrix>
+
+<critical_rules>
+## Rules That Have No Exceptions
+
+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)
+</critical_rules>
+
+<verification_checklist>
+Before completing:
+
+- [ ] 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.
+</verification_checklist>
+
+<integration>
+**This skill is called by:**
+- hyperpowers:review-implementation (final step after approval)
+
+**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.
+</integration>
+
+<resources>
+**Detailed guides:**
+- [Git worktree management](resources/worktree-guide.md)
+- [PR description templates](resources/pr-templates.md)
+- [bd epic reference in PRs](resources/bd-pr-integration.md)
+
+**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
+</resources>