feat(finalize-pr): add multi-PR modes, bot support, and skill authoring guidance

AGENTS.md

@@ -141,6 +141,43 @@ It must always be clear whether child phases/steps can run in parallel or not. B
 sub-steps are assumed to be sequential. If they can run in parallel, this should be explicitly
 stated (e.g., "Steps 3.1 and 3.2 can be run in parallel.").
 
+### Skill and Command Authoring
+
+Skill files should describe **what** to accomplish and any non-obvious constraints — let the AI
+determine the implementation.
+
+**Do** state goals, required field names, important flags, and API paths in prose.
+**Do** use `text` blocks to show expected output formats so the AI knows what to produce.
+**Do** use code blocks for GraphQL mutations, non-obvious API endpoints, or complex queries that
+cannot be reasonably inferred.
+
+**Why this matters**: Spelling out trivial bash trains the AI to reach for shell scripts even when
+native tools (Read, Edit, Glob, Write) are faster and safer. Prose-based instructions let AIs choose
+the most appropriate tool and improve their approach as capabilities grow.
+
+Prefer:
+
+> List all open PRs (limit 50) with number, title, author, and headRefName.
+
+Over:
+
+```bash
+gh pr list --state open --limit 50 --json number,title,author,headRefName
+```
+
+Prefer:
+
+> Verify the working tree is clean before proceeding.
+
+Over:
+
+```bash
+git status --porcelain
+```
+
+Reserve code blocks for non-obvious things: GraphQL mutations, specific API endpoint paths, complex
+jq pipelines, and expected output formats.
+
 ### Hook Implementation Language Selection
 
 Choose the implementation language based on complexity:

github-workflows/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "github-workflows",
-  "version": "1.1.0",
-  "description": "PR management, multi-repo PR finalization, and issue shaping with Shape Up methodology",
+  "version": "1.2.0",
+  "description": "PR finalization (single, repo-wide, or org-wide including bots), squash-merge, review thread resolution, and issue shaping",
   "author": {
     "name": "JacobPEvans"
   },

github-workflows/README.md

@@ -4,7 +4,7 @@ Claude Code plugin for PR management and issue shaping with Shape Up methodology
 
 ## Skills
 
-- **`/finalize-pr`** - Automatically finalize pull requests for merge (CodeQL checks, CI, review threads)
+- **`/finalize-pr`** - Finalize PRs for merge: single PR, all repo PRs (`all`), or all org PRs (`org`). Includes bot-authored PRs in all modes.
 - **`/squash-merge-pr`** - Validate PR readiness and squash merge into main (errors if not ready)
 - **`/resolve-pr-threads`** - Orchestrate resolution of PR review threads (requires superpowers plugin)
 - **`/shape-issues`** - Shape raw ideas into actionable GitHub Issues using Shape Up methodology
@@ -19,7 +19,10 @@ claude plugins add jacobpevans-cc-plugins/github-workflows
 ## Usage
 
 ```text
-/finalize-pr              # Automatic PR finalization workflow
+/finalize-pr              # Finalize PR on current branch
+/finalize-pr 42           # Finalize specific PR by number
+/finalize-pr all          # Finalize all open PRs in repo (including bots)
+/finalize-pr org          # Finalize all open PRs across org (including bots)
 /squash-merge-pr          # Validate and squash merge
 /resolve-pr-threads       # Batch resolve review threads
 /shape-issues             # Shape ideas into GitHub issues

github-workflows/skills/finalize-pr/SKILL.md

@@ -2,18 +2,18 @@
 name: finalize-pr
 description: >-
   Automatically finalize pull requests for merge by resolving CodeQL violations,
-  review threads, merge conflicts, and CI failures. Assumes PR already exists.
-  Use when a PR needs to be prepared for merge. Handles single PR from argument
-  or current branch.
-argument-hint: "[PR_NUMBER]"
+  review threads, merge conflicts, and CI failures. Handles single PR (current
+  branch or by number), all open PRs in the repo, or all open PRs across the org.
+  Includes bot-authored PRs in all modes.
+argument-hint: "[PR_NUMBER | all | org]"
 ---
 
 <!-- cspell:words worktree oneline -->
 
 # Finalize PR
 
-**FULLY AUTOMATIC** - Finalizes YOUR PRs as author: monitor, fix, prepare for merge. Assumes PR already exists.
-No manual intervention required. For reviewing others' PRs, use `/review-pr`.
+**FULLY AUTOMATIC** - Fully automates PR finalization: monitor, fix, prepare for merge. Assumes PR already exists.
+No manual intervention required. For manual review-focused workflows, use `/review-pr`.
 
 ## Critical Rules
 
@@ -26,42 +26,90 @@ No manual intervention required. For reviewing others' PRs, use `/review-pr`.
 7. **Monitor CI early, block last** - Start CI monitoring in background immediately, but fix other issues while it runs
 8. **Update PR metadata automatically** - Before reporting ready, update title, description, and linked issues via haiku subagent
 9. **Take direct action** - Identify issues and fix them automatically (except merge decisions)
+10. **Include bot PRs** - Never filter by author. All modes include dependabot, release-please, claude, github-actions, etc.
+11. **Never cross org boundaries** - Org mode derives owner from current repo only
 
-## Phase 1: Resolution Loop (AUTOMATIC — PARALLEL)
+## Phase 1: PR Discovery and Targeting
+
+Parse the argument to determine mode, then discover and confirm the target set.
+Steps 1.1 through 1.4 run sequentially.
+
+### 1.1 Parse Argument
+
+| Argument | Mode | Target |
+|---|---|---|
+| _(none)_ | Current branch | Single PR on current branch |
+| `42` (a number) | Single PR | PR #42 |
+| `all` | Repo-wide | All open PRs in current repo |
+| `org` | Org-wide | All open PRs across all repos in current org |
+
+### 1.2 Discover PRs
+
+**Single/current-branch mode**: Resolve the PR number from the current branch, then skip to Phase 2.
+
+**Repo-wide (`all`) mode**: List all open PRs (limit 50) with number, title, author, and headRefName.
+
+**Org-wide (`org`) mode**: Enumerate all repos in the org, then for each repo list open PRs (limit 50
+per repo) including the `repository` field (needed for checkout and merge commands). Merge all results
+sorted by PR number, capped at 50 total. Emit a warning and continue if any repo cannot be listed.
+
+### 1.3 Tag Bot PRs
+
+For each discovered PR, check if `author.login` ends with `[bot]`
+(e.g., `dependabot[bot]`, `github-actions[bot]`, `claude[bot]`).
+Tag these as `[bot]` in the discovery list for reporting purposes only — they are
+processed identically to human-authored PRs.
+
+### 1.4 Confirm Batch (Multi-PR Only)
+
+For `all` and `org` modes, display the discovery list before proceeding:
+
+```text
+Found N open PRs:
+  #42  feat: add user auth          (alice)
+  #43  chore: bump dependencies     [bot] (dependabot[bot])
+  #58  fix: resolve edge case       [bot] (claude[bot])
+
+Proceeding to finalize all N PRs sequentially.
+```
+
+Verify the working tree is clean before proceeding. If dirty, report and ask the user to commit or
+stash. Note the current branch for restoration after each PR iteration.
+
+## Phase 2: Resolution Loop (AUTOMATIC)
 
 **Execution strategy**: CI checks take 10+ minutes. Start monitoring them in
 the background FIRST, then fix all other issues in parallel while CI runs.
 Never block on CI when other work is available.
 
-### 1.1 Start CI Monitoring (BACKGROUND)
+_For multi-PR modes, Phases 2-5 execute once per PR in sequence. Check out each PR branch at the
+start of each iteration. For org-wide mode, use `repository.nameWithOwner` from Phase 1 as the
+`--repo` argument when checking out._
 
-Launch CI monitoring in a background Task agent (`run_in_background: true` on
-the Task tool). The agent runs this blocking command in its own context:
+Steps 2.1 and 2.2 start concurrently (2.1 is non-blocking). Steps 2.3 and 2.4 run sequentially after 2.2.
 
-```bash
-gh pr checks <PR> --watch
-```
+### 2.1 Start CI Monitoring (BACKGROUND)
+
+Launch CI monitoring in a background Task agent (`run_in_background: true` on the Task tool).
+Monitor CI checks using `--watch` so the agent blocks until all complete.
 
-Do NOT wait for the Task to complete — proceed to 1.2 immediately. Check the
-background task's output after completing other fixes in 1.2.
+Do NOT wait for the agent to finish — proceed to 2.2 immediately.
 
-### 1.2 Parallel Fixes
+### 2.2 Parallel Fixes
 
 Run these checks simultaneously. Launch independent fixes in parallel via
 Task agents when they touch different files. Invoke `superpowers:dispatching-parallel-agents` for dispatch patterns.
 
 #### CodeQL Violations
 
-```bash
-OWNER=${OWNER:-$(gh repo view --json owner --jq '.owner.login')}
-REPO=${REPO:-$(gh repo view --json name --jq '.name')}
+Check for open code-scanning alerts:
 
+```bash
 gh api repos/${OWNER}/${REPO}/code-scanning/alerts --paginate \
   --jq '[.[] | select(.state == "open")] | length'
 ```
 
-**If violations found**: Invoke `/resolve-codeql fix`, then /simplify,
-validate locally.
+**If violations found**: Invoke `/resolve-codeql fix`, then /simplify, validate locally.
 
 #### Review Threads
 
@@ -70,33 +118,22 @@ After completion, invoke /simplify and validate locally.
 
 #### Merge Conflicts
 
-```bash
-gh pr view <PR> --json mergeable
-```
-
-**If conflicts**: Fetch main, attempt merge, report unresolvable conflicts for
-user. After resolution, invoke /simplify and validate locally.
-
-### 1.3 CI Failure Fixes
-
-Check background CI results from 1.1:
+Check if the PR is mergeable. **If conflicts**: Fetch main, attempt merge, report unresolvable
+conflicts for user. After resolution, invoke /simplify and validate locally.
 
-- **All passing**: Proceed to Phase 2
-- **Failures**: Get logs via `gh run view <RUN_ID> --log-failed`, fix locally,
-  invoke /simplify, validate, commit and push. Restart background CI
-  monitoring and loop back to 1.2 if new issues emerged.
+### 2.3 CI Failure Fixes
 
-### 1.4 Health Check
+Check background CI results from 2.1:
 
-Verify final PR status after all fixes:
+- **All passing**: Proceed to Phase 3
+- **Failures**: Fetch failed run logs, fix locally, invoke /simplify, validate, commit and push.
+  Restart background CI monitoring and loop back to 2.2 if new issues emerged.
 
-```bash
-gh pr view <PR> --json state,mergeable,statusCheckRollup
-```
+### 2.4 Health Check
 
-If fixes introduced new issues, loop back to 1.2.
+Verify final PR state, mergeability, and check status. If fixes introduced new issues, loop back to 2.2.
 
-## Phase 2: Pre-Handoff Verification
+## Phase 3: Pre-Handoff Verification
 
 Verify ALL conditions automatically and proceed directly:
 
@@ -107,62 +144,39 @@ Verify ALL conditions automatically and proceed directly:
 5. ✅ **All checks pass**: `gh pr checks <PR>` all green
 6. ✅ **Local validation**: Project linters pass
 
-**Only if ALL six pass**: Proceed to Phase 3 to update PR metadata.
-
-## Phase 3: Update PR Metadata
+**Only if ALL six pass**: Proceed to Phase 4 to update PR metadata.
 
-Delegate to a **haiku subagent** to keep full diff out of main context.
-Sub-steps 3.1 and 3.2 can run in parallel within the agent.
-
-### 3.1 Update PR Title and Description
-
-1. Run compact summary commands:
+**Multi-PR handling**: If a PR needs human intervention (unresolvable conflict,
+unrecoverable CI failure, etc.), log it with reason and continue to the next PR.
+Do not stop the batch for one blocked PR.
 
-   ```bash
-   git fetch origin main
-   git log --oneline origin/main..HEAD
-   git diff --stat origin/main...HEAD
-   ```
+## Phase 4: Update PR Metadata
 
-2. Read current PR title and body:
+Delegate to a **haiku subagent** to keep full diff out of main context.
+Steps 4.1 and 4.2 can run in parallel within the agent. Step 4.3 runs after both.
 
-   ```bash
-   gh pr view <PR> --json title,body
-   ```
+### 4.1 Update PR Title and Description
 
-3. Generate updated title (conventional commit format, <70 chars) and
-   description with sections: **Summary**, **Changes**, **Test Plan**.
+1. Summarize branch history and diff stats against main; read current PR title and body.
+2. Generate updated title (conventional commit format, <70 chars) and description with sections:
+   **Summary**, **Changes**, **Test Plan**.
 
-### 3.2 Link Related Issues and PRs
+### 4.2 Link Related Issues and PRs
 
 1. Extract keywords from branch name and commit messages.
-2. Search for related items:
-
-   ```bash
-   gh issue list --search "<keywords>" --json number,title --limit 5
-   gh pr list --search "<keywords>" --json number,title --limit 5
-   ```
-
-3. Add `Closes #X` (directly related issues) or `Related: #X` (adjacent PRs)
-   to description. Only link clearly related items — no guessing.
+2. Search GitHub issues and PRs for related items (limit 5 each).
+3. Add `Closes #X` (directly related issues) or `Related: #X` (adjacent PRs) — no guessing.
 
-### 3.3 Apply Updates
+### 4.3 Apply Updates
 
-After 3.1 and 3.2 complete, apply using a multiline-safe pattern:
+After 4.1 and 4.2 complete, write the body to a temp file and apply with `gh pr edit --body-file`
+(safer than inline for multiline content).
 
-```bash
-cat <<'EOF' > /tmp/pr-body.md
-...
-EOF
-
-gh pr edit <PR> --title "..." --body-file /tmp/pr-body.md
-```
+Proceed to Phase 5.
 
-Proceed to Phase 4.
+## Phase 5: Record Result
 
-## Phase 4: Report Ready Status
-
-After verifying all conditions pass and updating PR metadata, report:
+**Single/current-branch mode**: Report ready status and wait for user:
 
 ```text
 ✅ PR #{NUMBER} ready for final review!
@@ -173,17 +187,59 @@ To merge, invoke one of:
   /rebase-pr          # Rebase commits onto main (preserves history)
 ```
 
-Wait for explicit user merge command.
+**Multi-PR mode**: Record the per-PR result (ready / blocked / needs-human). Restore the original
+branch and continue to the next PR. Do NOT emit a ready report — that happens in Phase 6.
+
+## Phase 6: Aggregate Report (Multi-PR Only)
+
+After processing all PRs, emit a summary. For org-wide mode, merge commands must include `--repo`
+since PR numbers are scoped per-repository; use `repository.nameWithOwner` from Phase 1 discovery.
+
+```text
+PR Finalization Summary
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+  ✅  #42  feat: add user auth          (alice)         [owner/repo]
+  ✅  #58  fix: resolve edge case       [bot] (claude[bot])  [owner/repo]
+  ⛔  #43  chore: bump dependencies     [bot] (dependabot[bot])  [owner/repo]  — unresolvable conflict
+
+Ready to merge (2):
+  gh pr merge 42 --squash --repo owner/repo
+  gh pr merge 58 --squash --repo owner/repo
+
+Blocked — needs human (1):
+  #43  chore: bump dependencies  — unresolvable conflict in package-lock.json
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+For repo-wide (`all`) mode, `--repo` may be omitted since all PRs share the current repo.
+
+Wait for explicit user merge commands.
 
 ## Workflow
 
 ```text
-/init-worktree → [implement] → gh pr create → /finalize-pr
+Single PR:
+/init-worktree → [implement] → gh pr create → /finalize-pr [number]
                                                       ↓
-                              Phase 1: Resolution Loop (automatic fixes)
-                              Phase 2: Pre-Handoff Verification
-                              Phase 3: Update PR Metadata (title, description, linked issues)
-                              Phase 4: Report ready (wait for user)
+                              Phase 1: Resolve PR number
+                              Phase 2: Resolution Loop (automatic fixes)
+                              Phase 3: Pre-Handoff Verification
+                              Phase 4: Update PR Metadata
+                              Phase 5: Report ready (wait for user)
                                                       ↓
                               User invokes: /squash-merge-pr or /rebase-pr
+
+Repo-wide:
+/finalize-pr all
+  ↓
+Phase 1: Discover all open PRs (including bots), confirm batch
+Phases 2-5: Loop over each PR sequentially
+Phase 6: Aggregate report with merge commands for ready PRs
+
+Org-wide:
+/finalize-pr org
+  ↓
+Phase 1: Derive org owner, enumerate repos, collect and merge all open PRs
+Phases 2-5: Loop over each PR sequentially
+Phase 6: Aggregate report with --repo-qualified merge commands for ready PRs
 ```