@torka/claude-workflows 0.3.1 → 0.5.0

package/.claude-plugin/plugin.json

@@ -12,8 +12,12 @@
       "description": "Analyze epic files to identify which epics can run in parallel using Git worktrees"
     },
     {
-      "name": "git-cleanup-and-merge",
-      "description": "Analyze git branches, cleanup merged branches, push changes, create PRs, wait for CI, and merge"
+      "name": "git-local-cleanup-push-pr",
+      "description": "Analyze local branches, cleanup merged branches, push changes, and create PRs"
+    },
+    {
+      "name": "github-pr-resolve",
+      "description": "Assess open PRs, handle review comments, run CI, and merge"
     }
   ],
   "agents": [

package/commands/{git-cleanup-and-merge.md → git-local-cleanup-push-pr.md}

@@ -1,5 +1,5 @@
 ---
-description: 'Analyze git branches, cleanup merged branches, push changes, create PRs, wait for CI, and merge to main'
+description: 'Analyze local branches, cleanup merged branches, push changes, and create PRs'
 ---
 
 IT IS CRITICAL THAT YOU FOLLOW THIS WORKFLOW EXACTLY.
@@ -33,7 +33,7 @@ Before any operations, verify the environment is safe:
    - Run `git branch --show-current` to get current branch name
    - **If empty (detached HEAD)**: Run `git rev-parse HEAD` to save the commit SHA instead
    - Run `git rev-parse --show-toplevel` to record the current worktree path
-   - Track whether we started in detached HEAD state for Phase 8 restoration
+   - Track whether we started in detached HEAD state for Phase 6 restoration
 
 8. **Build worktree inventory**: Run `git worktree list --porcelain` to detect all worktrees.
    - Parse the output to build a map: `{ branch_name -> worktree_path }`
@@ -58,7 +58,7 @@ Before any operations, verify the environment is safe:
 11. **Initialize operation log**: Create an in-memory log to track all operations performed.
     - This log will be used for error recovery if something fails mid-workflow
     - Track: operation type, target (branch/worktree), status (success/failed)
-    - Log each destructive operation as it completes (worktree removal, branch deletion, push, PR creation, merge)
+    - Log each destructive operation as it completes (worktree removal, branch deletion, push, PR creation)
 
 If any pre-flight check fails, STOP and clearly explain what the user needs to do.
 
@@ -213,11 +213,6 @@ For each branch now eligible for deletion:
 
 - Run `git branch -vv | grep ': gone]'` and delete them
 
-### Step 7: Final cleanup
-
-- Run `git fetch --prune` to clean up stale refs
-- Run `git worktree prune` to clean up stale worktree admin entries
-
 ---
 
 ## Phase 4: Push Local Changes to Remote
@@ -307,123 +302,31 @@ For each confirmed branch:
 
 ---
 
-## Phase 6: CI Loop
-
-For each open PR (including newly created ones):
-
-**Configuration:**
-- Max 3 fix attempts per PR
-- Max 5 minute wait per CI run
-- 30 second polling interval
-
-**Process:**
-1. Check CI status: `gh pr checks <pr-number>` or `gh pr view <pr-number> --json statusCheckRollup`
-2. If CI is running:
-   - Display: "Waiting for CI on PR #<number>... (attempt X/3, Xs elapsed)"
-   - Wait 30 seconds
-   - Re-check (up to 5 minutes total)
-3. If CI passes: Mark PR as ready for merge, proceed to Phase 7
-4. If CI fails:
-   - Fetch and display the failure output
-   - Categorize the failure:
-     - **Lint/Formatting errors**: Offer to run `npm run lint -- --fix` automatically
-     - **Type errors**: Show errors, ask user: "Skip this PR", "I'll fix manually"
-     - **Test failures**: Show test output, ask user: "Skip this PR", "I'll fix manually"
-     - **Build errors**: Show error, ask user: "Skip this PR", "I'll fix manually"
-   - If auto-fix chosen (lint only):
-     - Run the fix command
-     - Show the diff to user
-     - Ask for confirmation before committing
-     - Commit with message: "fix: auto-fix lint errors"
-     - Push and decrement retry counter
-   - If manual fix chosen:
-     - Inform user and pause for this PR
-     - Ask: "Continue with other PRs?" or "Wait for manual fix?"
-5. If max retries exceeded:
-   - Ask user: "Skip this PR", "Abort workflow", or "I'll fix manually"
-   - Handle accordingly
-
-**IMPORTANT**: NEVER auto-fix test failures or type errors. Only lint/formatting issues are safe to auto-fix.
-
----
-
-## Phase 7: Merge PRs
-
-For each PR that passed CI:
-
-**Pre-merge checks:**
-1. Re-verify CI status (avoid race condition): `gh pr view <pr-number> --json statusCheckRollup`
-2. Check merge state: `gh pr view <pr-number> --json mergeStateStatus,mergeable`
-
-**If branch is behind default branch (`mergeStateStatus` is `BEHIND`):**
-- Ask user: "Update branch via GitHub" or "Skip this PR"
-- If update chosen:
-  - Run: `gh api repos/{owner}/{repo}/pulls/{pr-number}/update-branch -X PUT`
-  - If the API call fails (e.g., merge conflicts), inform user and offer to skip
-- Wait for CI to re-run after update
-- Re-check merge state
-
-**If merge conflicts exist (`mergeable` is `CONFLICTING`):**
-- STOP - cannot auto-merge
-- Show the PR URL
-- Ask user: "Skip this PR" or "I'll resolve conflicts manually"
-- If manual resolution, wait for user confirmation then re-check
-
-**Merge:**
-- Run `gh pr merge <pr-number> --delete-branch`
-- This respects the repository's merge strategy settings
-- The `--delete-branch` flag removes the remote branch after merge
-
-**If merge fails:**
-- Report the error
-- Ask user how to proceed
-
----
-
-## Phase 8: Final Cleanup & Summary
+## Phase 6: Local Cleanup & Summary
 
-### Step 1: Handle orphaned worktrees from merged PRs
-
-For any worktrees whose branches were merged in Phase 7:
-- The remote branch is now deleted, but the local worktree may still exist
-- For each such worktree, ask user:
-  ```
-  Worktree at '<path>' is now on merged branch '<branch>'.
-
-  Options:
-  1. Remove worktree (Recommended)
-  2. Keep worktree (switch to <default-branch>)
-  ```
-- If remove: `git worktree remove <path>`
-- If keep: `git -C <path> checkout <default-branch>`
-
-### Step 2: Clean up stale refs and worktree entries
+### Step 1: Clean up stale refs and worktree entries
 
 1. Run `git fetch --prune` to clean up all stale remote refs
 2. Run `git worktree prune` to clean up stale worktree admin entries
-3. Delete any local branches that were merged (check against PRs merged in Phase 7)
-   - Skip branches that are checked out in remaining worktrees
 
-### Step 3: Return to original context
+### Step 2: Return to original context
 
 - **If original state was a branch**: Run `git checkout <original-branch>` (if it still exists, otherwise stay on default branch)
 - **If original state was detached HEAD**: Run `git checkout <original-commit-sha>` to restore exact position
-- If the original branch was merged and deleted, inform user: "Your original branch '<branch>' was merged. You are now on '<default-branch>'."
+- If the original branch was deleted, inform user: "Your original branch '<branch>' was deleted. You are now on '<default-branch>'."
 
-### Step 4: Display final summary
+### Step 3: Display final summary
 
 ```
 =====================================================
-        Git Branch Cleanup Complete!
+        Local Git Cleanup Complete!
 =====================================================
 
 BRANCHES:
 ✓ Deleted X merged branches (local + remote)
 ✓ Pushed X branches to remote
 ✓ Created X PRs
-✓ Merged X PRs
 ○ Skipped X WIP branches
-✗ X PRs skipped (CI failed / merge conflicts)
 
 WORKTREES:
 ✓ Removed X worktrees (merged branches)
@@ -434,6 +337,10 @@ CURRENT STATE:
   Branch: <current-branch>
   Worktree: <current-worktree-path>
 
+PRs CREATED:
+  - PR #42: feature-x
+  - PR #43: bugfix-1
+
 REMAINING BRANCHES:
   - feature-wip (in worktree: /path/to/feature-wip)
   - bugfix-active (ahead 2)
@@ -442,9 +349,8 @@ ACTIVE WORKTREES:
   /path/to/main        main        (this worktree)
   /path/to/feature     feature-wip clean
 
-WARNINGS (if any):
-  - PR #42 has merge conflicts, needs manual resolution
-  - Worktree at /path/to/feature has uncommitted changes
+NEXT STEPS:
+  Run `/github-pr-resolve` to handle CI, reviews, and merging.
 =====================================================
 ```
 
@@ -481,11 +387,6 @@ If the workflow fails at any point, display:
    - Branch is pushed, PR was not created
    - Retry: `gh pr create --head <branch>`
 
-   **If failed during merge:**
-   - PR still exists, not merged
-   - Check PR status: `gh pr view <number>`
-   - Retry via GitHub UI or: `gh pr merge <number>`
-
    **If failed during rebase:**
    - Rebase may be in progress
    - Check: `git status`
@@ -502,8 +403,6 @@ If the workflow fails at any point, display:
 - NEVER use force push (`--force` or `-f`)
 - NEVER use force delete for branches (`-D`) unless confirmed squash-merged
 - ALWAYS confirm with user before destructive operations
-- NEVER merge without CI passing
-- ALWAYS respect retry limits
 - ALWAYS preserve the user's working context (return to original branch)
 
 ### Worktree Safety Rules

package/commands/github-pr-resolve.md

@@ -0,0 +1,584 @@
+---
+description: 'Assess open PRs, handle review comments, run CI, and merge'
+---
+
+IT IS CRITICAL THAT YOU FOLLOW THIS WORKFLOW EXACTLY.
+
+<workflow CRITICAL="TRUE">
+
+## Phase 0: Pre-flight Checks
+
+Before any operations, verify the environment is safe:
+
+1. **Check gh authentication**: Run `gh auth status`. If not authenticated, STOP and inform user.
+
+2. **Detect remote name**: Run `git remote` and use the first result (usually `origin`).
+
+3. **Detect default branch**: Run `gh repo view --json defaultBranchRef -q .defaultBranchRef.name`. Fallback to `main` if this fails.
+
+4. **Record current branch and worktree**:
+   - Run `git branch --show-current` to get current branch name
+   - **If empty (detached HEAD)**: Run `git rev-parse HEAD` to save the commit SHA instead
+   - Run `git rev-parse --show-toplevel` to record the current worktree path
+   - Track whether we started in detached HEAD state for Phase 5 restoration
+
+5. **Build worktree inventory**: Run `git worktree list --porcelain` to detect all worktrees.
+   - Parse the output to build a map: `{ branch_name -> worktree_path }`
+   - For each branch, record if it's checked out in a worktree and where
+
+6. **Check for uncommitted changes**: Run `git status --porcelain`.
+   - If output is non-empty, offer handling options:
+     ```
+     You have uncommitted changes in your working directory.
+
+     Options:
+     1. Stash changes now (I'll restore them at the end)
+     2. Proceed carefully (I'll warn before any checkout operation)
+     3. Let me commit/stash manually first (pause workflow)
+     ```
+   - If stash chosen: Run `git stash push -m "github-pr-resolve: auto-stash"` and track `stash_used = true`
+   - Track stash state for restoration in Phase 5
+
+7. **Initialize task tracking**: Use TodoWrite to create a task list for the session.
+   - Add tasks for each phase: PR assessment, review comments, CI fixes, merges, cleanup
+   - Update task status as work progresses (this ensures nothing is missed)
+   - The todo list provides visibility to the user and keeps the workflow on track
+
+If gh authentication fails, STOP and clearly explain what the user needs to do.
+
+---
+
+## Phase 1: PR Discovery & Assessment
+
+Gather comprehensive information about all open PRs:
+
+1. **Fetch all open PRs**: Run `gh pr list --state open --json number,title,headRefName,baseRefName,statusCheckRollup,reviewDecision,isDraft,createdAt,url`
+
+2. **For each PR, gather additional details**:
+   - Review status: `gh pr view <number> --json reviews,reviewDecision`
+   - CI status: Parse `statusCheckRollup` from the list query
+   - Mergeable status: `gh pr view <number> --json mergeStateStatus,mergeable`
+
+3. **Categorize PRs**:
+
+   | Category | Description | Action |
+   |----------|-------------|--------|
+   | Ready to Merge | CI passed, approved, no conflicts | Phase 4 |
+   | Needs Review Comments | Has pending/requested changes | Phase 2 |
+   | CI Running | Checks in progress | Phase 3 |
+   | CI Failed | Checks failed | Phase 3 |
+   | Draft | Marked as draft | Skip unless user requests |
+   | Conflicts | Has merge conflicts | Warn user |
+
+4. **Present summary table**:
+   ```
+   Open PRs Assessment:
+
+   | # | Title | Branch | Status | Reviews | CI | Mergeable |
+   |---|-------|--------|--------|---------|----|-----------|
+   | 42 | Add auth | feature-auth | Ready | Approved | ✓ | Yes |
+   | 43 | Fix bug | bugfix-123 | Review | Changes Requested | ✓ | Yes |
+   | 44 | New API | api-v2 | CI | - | Running | Yes |
+   | 45 | Refactor | refactor | Conflicts | - | ✓ | No |
+   ```
+
+5. **Ask user how to proceed**:
+   - "Process all PRs in order"
+   - "Let me select which PRs to process"
+   - "Skip to specific phase" (if user only wants merging)
+
+---
+
+## Phase 2: Review Comments Handling
+
+For each PR with pending reviews or requested changes:
+
+### Step 1: Fetch ALL review data (multiple sources required)
+
+GitHub stores review feedback in THREE separate places. You MUST check all three:
+
+1. **PR-level reviews** (approval/rejection decisions):
+   ```bash
+   gh pr view <number> --json reviews,reviewDecision
+   ```
+
+2. **PR conversation comments** (general discussion):
+   ```bash
+   gh pr view <number> --json comments
+   ```
+
+3. **Inline code review comments** (line-specific feedback - CRITICAL, OFTEN MISSED):
+   ```bash
+   gh api repos/{owner}/{repo}/pulls/{number}/comments
+   ```
+   This returns comments attached to specific lines of code. These are the most actionable!
+
+**CRITICAL**: The `--json comments` flag does NOT include inline code review comments.
+You MUST call the `/pulls/{number}/comments` API endpoint separately.
+
+Parse each source and combine into a unified list with:
+- Comment body/text
+- Author (check if bot - see Step 1.5)
+- File path and line number (for inline comments)
+- Whether it's resolved/outdated
+- Creation timestamp
+
+### Step 1.5: Identify bot reviewers
+
+Before categorizing comments, identify automated reviewers:
+
+**Known CI/review bots:**
+- `github-actions[bot]`
+- `chatgpt-codex-connector[bot]` or similar Codex bots
+- `coderabbitai[bot]`
+- `dependabot[bot]`
+- `renovate[bot]`
+- `sonarcloud[bot]`
+
+**Bot comment handling:**
+- Bot comments are often MORE actionable than they appear (security suggestions, code quality)
+- ALWAYS expand/check bot comments even if they seem informational
+- Display bot comments separately in the summary
+
+### Step 2: Categorize comments
+
+Analyze each comment and categorize:
+
+| Category | Auto-addressable? | Examples |
+|----------|-------------------|----------|
+| Add comment/docstring | Yes | "Please add a comment explaining this", "Add JSDoc" |
+| Rename variable/function | Yes | "Rename `x` to `count`", "Use more descriptive name" |
+| Add type annotation | Yes | "Add type for this parameter" |
+| Fix typo | Yes | "Typo: 'recieve' -> 'receive'" |
+| Logic change | No - guided | "This should handle the null case" |
+| Refactor request | No - guided | "Extract this into a separate function" |
+| Question/clarification | No - guided | "Why is this needed?" |
+| Approval/praise | Skip | "LGTM", "Nice work" |
+
+### Step 3: Display summary and ask user
+
+For each PR with comments:
+
+```
+PR #42: "Add user authentication"
+Review status: Changes Requested
+Reviewer: @reviewer-name
+
+Comments: 5 total
+  - 3 auto-addressable (add docstring, rename var, fix typo)
+  - 2 need guidance (logic change, refactor request)
+
+Options:
+1. Auto-address 3 simple comments (Recommended)
+2. Guide me through all 5 comments
+3. View all comments first
+4. Skip this PR
+```
+
+### Step 4: Auto-address simple comments
+
+If user chooses auto-address:
+
+1. **Checkout the PR branch** (if not already):
+   - Check if branch is in a worktree - if so, operate there with `git -C`
+   - Otherwise: `git checkout <branch>`
+
+2. **For each auto-addressable comment**:
+   - Read the file at the specified path
+   - Identify the exact location (line number from review comment)
+   - Make the change based on the comment type:
+     - **Add comment/docstring**: Generate appropriate documentation
+     - **Rename**: Use find/replace for the identifier
+     - **Add type annotation**: Infer or use suggested type
+     - **Fix typo**: Apply the correction
+   - Show diff to user: "Change X to Y in file.ts:42"
+   - Ask: "Apply this change?" / "Skip" / "Edit manually"
+
+3. **After all accepted changes**:
+   - Show consolidated diff
+   - Ask for confirmation before committing
+   - **Stage ONLY modified files explicitly** (NEVER use `git add .` or `git commit -a`):
+     ```bash
+     git add <file1> <file2> ...  # Only files that were actually modified
+     ```
+   - Verify staging is correct: `git status --short`
+   - If unexpected files are staged, warn user and ask how to proceed
+   - Commit: `git commit -m "fix: address review comments"`
+   - **Check upstream tracking before push**:
+     ```bash
+     # If no upstream set, use -u flag
+     git rev-parse --abbrev-ref --symbolic-full-name @{upstream} 2>/dev/null || git push -u origin <branch>
+     # Otherwise just push
+     git push
+     ```
+
+### Step 5: Guided resolution for complex comments
+
+If user chooses guided resolution or has complex comments remaining:
+
+For each complex comment:
+1. Display the comment with full context:
+   ```
+   File: src/auth/login.ts
+   Line: 42-45
+   Reviewer: @reviewer-name
+   Comment: "This should handle the null case - what happens if user is undefined?"
+
+   Current code:
+   40 |   const user = getUser(id);
+   41 |   return user.name;  // <- reviewer's concern
+   42 | }
+   ```
+
+2. Ask user with `AskUserQuestion`:
+   ```
+   How would you like to address this?
+   1. Show me the file (I'll make the fix)
+   2. Suggest a fix (Claude will propose code)
+   3. Mark as resolved with reply
+   4. Skip for now
+   ```
+
+3. **If "Suggest a fix"**:
+   - Analyze the code and comment
+   - Propose a code change
+   - Show diff and ask for confirmation
+   - Apply if accepted
+
+4. **If "Mark as resolved with reply"**:
+   - Ask user for reply text
+   - Post reply: `gh api repos/{owner}/{repo}/pulls/{number}/comments/{comment_id}/replies -f body="<reply>"`
+
+### Step 6: Post-comment handling
+
+After addressing comments:
+- Ask: "Re-request review from @reviewer?" / "Mark ready for review?" / "Leave as-is"
+- If re-request: `gh pr ready <number>` (if was draft) or comment @-mentioning reviewer
+
+### Safety Guardrails
+
+- NEVER auto-address comments that involve logic changes
+- ALWAYS show diff before committing auto-addressed changes
+- ALWAYS confirm before pushing
+- Track which comments were addressed vs skipped for summary
+- NEVER modify code that the comment doesn't directly reference
+
+---
+
+## Phase 3: CI Loop
+
+For each open PR that needs CI verification:
+
+**Configuration:**
+- Max 3 fix attempts per PR
+- Max 5 minute wait per CI run
+- 30 second polling interval
+
+### CI Wait Strategy
+
+At the start of Phase 3, if multiple PRs have CI running, ask user:
+
+```
+Multiple PRs have CI in progress:
+- PR #39: CI running (2 min elapsed)
+- PR #40: CI running (1 min elapsed)
+- PR #41: CI running (just started)
+
+Options:
+1. Wait for all CIs before proceeding (slower but complete)
+2. Process PRs as their CI completes (faster, may revisit)
+3. Only process PRs with CI already complete
+4. Check back in X minutes (pause workflow)
+```
+
+If a PR is created during the workflow (e.g., a CI fix PR), ask:
+- "Wait for this PR's CI before continuing"
+- "Continue with other ready PRs, check back later"
+- "This PR is a prerequisite - wait for it, then re-check dependent PRs"
+
+**Process:**
+
+1. **Check CI status**: `gh pr view <pr-number> --json statusCheckRollup`
+
+2. **If CI is running**:
+   - Display: "Waiting for CI on PR #<number>... (attempt X/3, Xs elapsed)"
+   - Wait 30 seconds
+   - Re-check (up to 5 minutes total)
+
+3. **If CI passes**: Mark PR as ready for merge, proceed to Phase 4
+
+4. **If CI fails**:
+   - Fetch and display the failure output
+   - Categorize the failure:
+     - **Lint/Formatting errors**: Offer to run `npm run lint -- --fix` automatically
+     - **Type errors**: Show errors, ask user: "Skip this PR", "I'll fix manually"
+     - **Test failures**: Show test output, ask user: "Skip this PR", "I'll fix manually"
+     - **Build errors**: Show error, ask user: "Skip this PR", "I'll fix manually"
+   - If auto-fix chosen (lint only):
+     - Checkout branch (handle worktree if needed)
+     - Run the fix command
+     - Show the diff to user
+     - Ask for confirmation before committing
+     - **Stage ONLY files that were actually fixed** (use explicit paths, never `git add .`)
+     - Commit with message: "fix: auto-fix lint errors"
+     - **Check upstream tracking before push** (use `-u` flag if needed)
+     - Push and decrement retry counter
+   - If manual fix chosen:
+     - Inform user and pause for this PR
+     - Ask: "Continue with other PRs?" or "Wait for manual fix?"
+
+5. **If max retries exceeded**:
+   - Ask user: "Skip this PR", "Abort workflow", or "I'll fix manually"
+   - Handle accordingly
+
+**IMPORTANT**: NEVER auto-fix test failures or type errors. Only lint/formatting issues are safe to auto-fix.
+
+---
+
+## Phase 4: Merge PRs
+
+For each PR that passed CI (and has no pending review comments):
+
+### Merge Order Strategy
+
+When multiple PRs are ready to merge, order matters:
+
+1. **Check for file overlap** between PRs:
+   ```bash
+   gh pr diff <pr1> --name-only > /tmp/pr1_files
+   gh pr diff <pr2> --name-only > /tmp/pr2_files
+   comm -12 <(sort /tmp/pr1_files) <(sort /tmp/pr2_files)
+   ```
+
+2. **Recommended merge order**:
+   | Priority | Criteria | Rationale |
+   |----------|----------|-----------|
+   | 1 | CI/infrastructure fixes | Unblocks other PRs |
+   | 2 | PRs with no file overlap | Independent, safe in any order |
+   | 3 | Dependency PRs first | If PR B depends on PR A's changes |
+   | 4 | Oldest PRs | Reduce stale PR backlog |
+   | 5 | Smallest PRs | Quick wins |
+
+3. **Present merge plan to user**:
+   ```
+   Recommended merge order:
+   1. PR #41 "Fix CI" (infrastructure - may unblock others)
+   2. PR #40 "Add feature X" (no conflicts)
+   3. PR #39 "Update component Y" (no conflicts)
+
+   Proceed with this order? [Yes / Let me reorder / Merge one at a time]
+   ```
+
+4. **Between merges**: Re-check remaining PRs for new conflicts after each merge
+
+### Pre-merge checks
+
+1. Re-verify CI status (avoid race condition): `gh pr view <pr-number> --json statusCheckRollup`
+2. Check merge state: `gh pr view <pr-number> --json mergeStateStatus,mergeable`
+
+### Handle branch behind default branch
+
+**If `mergeStateStatus` is `BEHIND`:**
+- Ask user: "Update branch via GitHub" or "Skip this PR"
+- If update chosen:
+  - Run: `gh api repos/{owner}/{repo}/pulls/{pr-number}/update-branch -X PUT`
+  - If the API call fails (e.g., merge conflicts), inform user and offer to skip
+- Wait for CI to re-run after update
+- Re-check merge state
+
+### Handle merge conflicts
+
+**If `mergeable` is `CONFLICTING`:**
+- STOP - cannot auto-merge
+- Show the PR URL
+- Ask user: "Skip this PR" or "I'll resolve conflicts manually"
+- If manual resolution, wait for user confirmation then re-check
+
+### Merge
+
+- Present merge summary before proceeding:
+  ```
+  Ready to merge:
+  PR #42: "Add user authentication" (feature-auth -> main)
+
+  This will:
+  - Merge the PR using repository's merge strategy
+  - Delete the remote branch
+
+  Proceed? [Yes / Skip / Abort]
+  ```
+- Run `gh pr merge <pr-number> --delete-branch`
+- This respects the repository's merge strategy settings
+- The `--delete-branch` flag removes the remote branch after merge
+
+### Handle merge failure
+
+- Report the error
+- Ask user how to proceed
+
+---
+
+## Phase 5: Final Cleanup & Summary
+
+### Step 0: Restore stashed changes (if applicable)
+
+If changes were stashed in Phase 0:
+1. After returning to original branch (Step 4), run `git stash pop`
+2. If pop fails (conflicts), warn user:
+   ```
+   Could not automatically restore your stashed changes.
+   Your changes are still in the stash. Run `git stash list` to see them.
+   Restore manually with: `git stash pop` or `git stash apply`
+   ```
+3. Show `git status` to confirm restoration
+
+### Step 1: Handle orphaned worktrees from merged PRs
+
+For any worktrees whose branches were merged in Phase 4:
+- The remote branch is now deleted, but the local worktree may still exist
+- For each such worktree, ask user:
+  ```
+  Worktree at '<path>' is now on merged branch '<branch>'.
+
+  Options:
+  1. Remove worktree (Recommended)
+  2. Keep worktree (switch to <default-branch>)
+  ```
+- If remove: `git worktree remove <path>`
+- If keep: `git -C <path> checkout <default-branch>`
+
+### Step 2: Clean up local branches
+
+For each PR merged in Phase 4:
+- Delete local branch if it exists: `git branch -d <branch>`
+- Skip if branch is checked out in a remaining worktree
+
+### Step 3: Clean up stale refs
+
+1. Run `git fetch --prune` to clean up all stale remote refs
+2. Run `git worktree prune` to clean up stale worktree admin entries
+
+### Step 4: Return to original context
+
+- **If original state was a branch**: Run `git checkout <original-branch>` (if it still exists, otherwise stay on default branch)
+- **If original state was detached HEAD**: Run `git checkout <original-commit-sha>` to restore exact position
+- If the original branch was merged and deleted, inform user: "Your original branch '<branch>' was merged. You are now on '<default-branch>'."
+
+### Step 5: Display final summary
+
+```
+=====================================================
+        GitHub PR Resolution Complete!
+=====================================================
+
+PRs PROCESSED:
+✓ Merged X PRs
+  - PR #42: "Add user authentication"
+  - PR #43: "Fix login bug"
+○ Skipped X PRs (CI failed / conflicts)
+  - PR #45: "Refactor" (merge conflicts)
+
+REVIEW COMMENTS:
+✓ Auto-addressed X comments
+✓ Manually resolved X comments
+○ Skipped X comments
+
+CI FIXES:
+✓ Auto-fixed X lint issues
+○ X PRs need manual fixes
+
+CLEANUP:
+✓ Deleted X remote branches
+✓ Deleted X local branches
+✓ Removed X worktrees
+
+CURRENT STATE:
+  Branch: <current-branch>
+  Worktree: <current-worktree-path>
+
+REMAINING OPEN PRs:
+  - PR #45: "Refactor" - merge conflicts, needs manual resolution
+  - PR #46: "Draft feature" - draft, skipped
+
+WARNINGS (if any):
+  - PR #45 has merge conflicts at src/auth/login.ts
+=====================================================
+```
+
+</workflow>
+
+## Error Recovery
+
+If the workflow fails at any point, display:
+
+1. **Operations completed successfully** (from the operation log)
+2. **The operation that failed** and the error message
+3. **Current repository state**:
+   - Current branch: `git branch --show-current`
+   - Uncommitted changes: `git status --porcelain`
+   - Any in-progress operations: check for rebase/merge/cherry-pick
+
+4. **Recovery guidance based on failure point**:
+
+   **If failed during review comment fix:**
+   - Changes may be uncommitted
+   - Check: `git status` and `git diff`
+   - Either commit or stash the changes
+   - PR is still open (safe)
+
+   **If failed during CI fix commit:**
+   - Changes may be uncommitted
+   - Check: `git status`
+   - Commit manually: `git commit -am "fix: ..."`
+   - Push: `git push`
+
+   **If failed during merge:**
+   - PR still exists, not merged
+   - Check PR status: `gh pr view <number>`
+   - Retry via GitHub UI or: `gh pr merge <number>`
+
+   **If failed during worktree cleanup:**
+   - Worktree may be partially removed
+   - Run: `git worktree prune` to clean up
+   - Check: `git worktree list`
+
+   **If failed during branch deletion:**
+   - Local branch may be deleted but remote still exists (or vice versa)
+   - Check: `git branch -a | grep <branch>`
+   - Manual cleanup if needed
+
+5. **Always safe to re-run**: The workflow is idempotent - running it again will skip already-completed operations.
+
+---
+
+## Safety Rules
+
+### PR Safety Rules
+- NEVER merge without CI passing
+- NEVER force merge when conflicts exist
+- ALWAYS verify merge state before merging
+- ALWAYS respect retry limits
+
+### Review Comment Safety Rules
+- NEVER auto-address comments that involve logic changes
+- ALWAYS show diff before committing changes
+- ALWAYS confirm before pushing
+- NEVER modify code that the comment doesn't directly reference
+- ALWAYS track which comments were addressed for summary
+
+### Branch Safety Rules
+- NEVER use force push (`--force` or `-f`)
+- ALWAYS preserve the user's working context (return to original branch)
+
+### Commit Safety Rules
+- NEVER use `git commit -a` or `git add .` without first reviewing what will be staged
+- ALWAYS use explicit file paths when staging: `git add <specific-file>`
+- ALWAYS run `git status` before committing to verify staged files
+- If the commit includes unexpected files, STOP and ask user before proceeding
+- ALWAYS check upstream tracking before push (use `-u` flag if no upstream)
+
+### Worktree Safety Rules
+- NEVER remove a worktree with uncommitted changes without explicit user confirmation
+- ALWAYS check worktree status before operations
+- ALWAYS run `git worktree prune` after removing worktrees
+- ALWAYS use `git -C <path>` for operations in linked worktrees

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@torka/claude-workflows",
-  "version": "0.3.1",
+  "version": "0.5.0",
   "description": "Claude Code workflow helpers: epic automation, git cleanup, agents, and design workflows",
   "keywords": [
     "claude-code",