@torka/claude-workflows 0.3.0 → 0.4.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/bmad-workflows/bmm/workflows/4-implementation/implement-epic-with-subagents/steps/step-01-init.md

@@ -67,22 +67,42 @@ current_path: $(pwd)
 
 ### 2. Discover Sidecar Files
 
-Scan for existing epic execution state files:
+Scan for existing epic execution state files.
 
+**IMPORTANT:** When running in a worktree, the sidecar was created in the **main repo** before session restart. You must search the main repo's sidecar folder, not just the local worktree folder.
+
+**If running in MAIN REPO (`is_worktree` = false):**
 ```bash
 ls -la {sidecarFolder}/epic-*-state.yaml 2>/dev/null
 ```
 
+**If running in WORKTREE (`is_worktree` = true):**
+```bash
+# Derive main repo path from git
+MAIN_REPO_PATH=$(dirname "$(git rev-parse --git-common-dir)")
+MAIN_SIDECAR_FOLDER="$MAIN_REPO_PATH/_bmad-output/epic-executions"
+
+# Search main repo sidecar folder (canonical location where setup created it)
+ls -la "$MAIN_SIDECAR_FOLDER"/epic-*-state.yaml 2>/dev/null
+```
+
+**Store main repo sidecar path for later use:**
+```
+main_sidecar_folder: "$MAIN_SIDECAR_FOLDER"  # Only when is_worktree=true
+```
+
 **For each sidecar found, extract:**
 - Epic number (from filename pattern)
 - `current_phase` value
 - `worktree_config.worktree_path` (if present)
 - `stories_pending` count
+- `sidecar_path` (full path to the sidecar file)
 
 **Build sidecar list:**
 ```
 sidecars_found:
   - file: "epic-2-state.yaml"
+    sidecar_path: "/main/repo/_bmad-output/epic-executions/epic-2-state.yaml"
     epic_number: 2
     phase: "executing"
     worktree_path: "/path/to/worktree" | null
@@ -106,10 +126,12 @@ Based on detection results, determine the appropriate path:
 ```
 Detected: Running in worktree for Epic {N}
 Found matching execution state with {X} stories pending.
+Sidecar location: {sidecar_path}
 
 Routing to continuation...
 ```
 
+→ Pass `sidecar_path` context for subsequent steps to use
 → Load, read entire file, then execute `{continueFile}`
 
 ---
@@ -131,7 +153,7 @@ Setup was completed in previous session.
 Ready to begin story execution...
 ```
 
-→ Update sidecar: `current_phase: "executing"`
+→ Update sidecar at `{sidecar_path}` (the matched sidecar's full path): `current_phase: "executing"`
 → Load, read entire file, then execute step-02-orchestrate.md
 
 ---

package/bmad-workflows/bmm/workflows/4-implementation/implement-epic-with-subagents/steps/step-01b-continue.md

@@ -72,9 +72,9 @@ To resume epic execution from a previous session by loading the sidecar state, d
 
 **Note:** This step is routed from step-01-init which already detected:
 - Whether we're in a worktree or main repo
-- Which sidecar file to use (passed as context)
+- Which sidecar file to use (passed as `sidecar_path` context)
 
-If sidecar was NOT specified by router (edge case):
+If `sidecar_path` was NOT specified by router (edge case):
 
 ```bash
 # Detect worktree context
@@ -82,21 +82,28 @@ GIT_DIR=$(git rev-parse --git-dir 2>/dev/null)
 GIT_COMMON=$(git rev-parse --git-common-dir 2>/dev/null)
 CURRENT_PATH=$(pwd)
 
-# If in worktree, find matching sidecar
+# Determine sidecar search location
 if [ "$GIT_DIR" != "$GIT_COMMON" ]; then
-  # Search for sidecar with matching worktree_path
-  # Parse each epic-*-state.yaml and match worktree_config.worktree_path
+  # In worktree - sidecar is in main repo
+  MAIN_REPO_PATH=$(dirname "$GIT_COMMON")
+  SIDECAR_FOLDER="$MAIN_REPO_PATH/_bmad-output/epic-executions"
+else
+  # In main repo - use local folder
+  SIDECAR_FOLDER="{sidecarFolder}"
 fi
+
+# Find sidecar with matching worktree_path (if in worktree)
+# Parse each epic-*-state.yaml and match worktree_config.worktree_path == CURRENT_PATH
 ```
 
 **Worktree-specific notes:**
-- Sidecar files are ALWAYS in main repo's `{sidecarFolder}`
-- When in worktree, sidecar is accessed via the shared git history
-- `worktree_config.worktree_path` in sidecar identifies the worktree
+- Sidecar files are ALWAYS created in the **main repo's** `_bmad-output/epic-executions/`
+- When in a worktree, you must derive the main repo path to find the sidecar
+- `worktree_config.worktree_path` in sidecar identifies which worktree it belongs to
 
 ### 1. Load Sidecar State
 
-Read the sidecar file at `{sidecarFolder}/epic-{N}-state.yaml`:
+Read the sidecar file at the path determined above (use `sidecar_path` from router context, or derive it as shown in section 0):
 
 Extract:
 - `epic_execution_state.epic_file`: Path to epic being executed

package/bmad-workflows/bmm/workflows/4-implementation/implement-epic-with-subagents/steps/step-02-orchestrate.md

@@ -79,11 +79,14 @@ To autonomously execute all pending stories in the epic by orchestrating special
 
 ## CONTEXT BOUNDARIES:
 
+- **Sidecar path:** Use `sidecar_path` from router context (step-01-init). In worktree mode, the sidecar is in the main repo's `_bmad-output/epic-executions/`, NOT the worktree's folder.
 - Sidecar file tracks current story and phase
 - Each agent gets fresh context with specific instructions
 - Sprint-status.yaml is source of truth for story states
 - Handoff messages provide phase completion status
 
+**CRITICAL for worktree mode:** All sidecar updates must use the absolute `sidecar_path` passed from step-01-init. Do NOT use `{sidecarFolder}` directly as it resolves to the wrong location in worktrees.
+
 ---
 
 ## STORY EXECUTION LOOP

package/bmad-workflows/bmm/workflows/4-implementation/implement-epic-with-subagents/steps/step-03-complete.md

@@ -74,6 +74,7 @@ To generate the Epic Completion Report, create a Pull Request, handle worktree c
 
 ## CONTEXT BOUNDARIES:
 
+- **Sidecar path:** Use `sidecar_path` from router context (step-01-init). In worktree mode, the sidecar is in the main repo's `_bmad-output/epic-executions/`, NOT the worktree's folder.
 - Sidecar file contains complete execution history
 - All story outcomes recorded in execution_log
 - Sprint-status reflects final story states
@@ -86,7 +87,9 @@ To generate the Epic Completion Report, create a Pull Request, handle worktree c
 
 ### 1. Load Execution Data
 
-Read the sidecar file at `{sidecarFolder}/epic-{N}-state.yaml`:
+Read the sidecar file using `sidecar_path` from router context (passed through step-01-init → step-01b/02):
+
+**Note:** In worktree mode, this path points to the main repo's sidecar location, not the worktree's.
 
 Gather:
 - `epic_execution_state.epic_file`, `epic_execution_state.epic_name`

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,446 @@
+---
+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, WARN the user (but do NOT block)
+   - Note: We only block if we need to checkout branches later for review comment fixes
+
+7. **Initialize operation log**: Create an in-memory log to track all operations performed.
+    - Track: operation type, target (PR/branch), status (success/failed)
+    - Log each operation as it completes
+
+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 review data
+
+Run `gh pr view <number> --json reviews,reviewDecision,comments` and `gh api repos/{owner}/{repo}/pulls/{number}/comments` to get:
+- Review decision (APPROVED, CHANGES_REQUESTED, REVIEW_REQUIRED)
+- All review comments with file paths and line numbers
+
+### 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
+   - Commit: `git commit -am "fix: address review comments"`
+   - 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
+
+**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
+     - 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 4: Merge PRs
+
+For each PR that passed CI (and has no pending review comments):
+
+### 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 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)
+
+### 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.0",
+  "version": "0.4.0",
   "description": "Claude Code workflow helpers: epic automation, git cleanup, agents, and design workflows",
   "keywords": [
     "claude-code",