docs: update guide content, examples, tools, and reference files

- guide/ultimate-guide.md — content updates - guide/workflows/README.md, guide/README.md — navigation improvements - guide/diagrams/ — diagram updates (context/sessions, config, MCP ecosystem) - guide/third-party-tools.md — additions - examples/README.md, hooks/README.md, scripts/README.md — examples updates - examples/skills/pr-triage/SKILL.md — expanded skill - machine-readable/reference.yaml — reference sync - tools/audit-prompt.md, tools/onboarding-prompt.md — tooling updates - docs/for-cto.md, docs/for-tech-leads.md, docs/resource-evaluations/README.md — doc updates - .gitignore — gitignore update Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
2026-03-09 15:32:33 +01:00 · 2026-03-09 15:32:33 +01:00 · 8f1dcecfa2
commit 8f1dcecfa2
parent 9c02214bb8
19 changed files with 639 additions and 104 deletions
--- a/examples/README.md
+++ b/examples/README.md
@ -14,18 +14,21 @@ Annotated templates that teach you **why** patterns work, not just how to config

 | Folder | Description | Count |
 |--------|-------------|-------|
-| [`agents/`](./agents/) | Custom AI personas for specialized tasks | 9 |
-| [`commands/`](./commands/) | Slash commands (workflow automation) | 26 |
-| [`hooks/`](./hooks/) | Event-driven security & automation scripts | 31 |
-| [`skills/`](./skills/) | Reusable knowledge modules — [9 on SkillHub](https://skills.palebluedot.live/owner/FlorianBruniaux) | 15 |
-| [`claude-md/`](./claude-md/) | CLAUDE.md configuration profiles | 6 |
-| [`config/`](./config/) | Settings, MCP, git templates | 5 |
+| [`agents/`](./agents/) | Custom AI personas for specialized tasks | 14 + 2 collections |
+| [`commands/`](./commands/) | Slash commands (workflow automation) | 31 |
+| [`hooks/`](./hooks/) | Event-driven security & automation scripts | 34 |
+| [`skills/`](./skills/) | Reusable knowledge modules — [9 on SkillHub](https://skills.palebluedot.live/owner/FlorianBruniaux) | 17 |
+| [`claude-md/`](./claude-md/) | CLAUDE.md configuration profiles | 7 |
+| [`config/`](./config/) | Settings, MCP, git templates | 8 |
 | [`memory/`](./memory/) | CLAUDE.md memory file templates | 2 |
-| [`scripts/`](./scripts/) | Diagnostic & utility scripts | 13 |
+| [`rules/`](./rules/) | Behavioral rules for common review patterns | 5 |
+| [`scripts/`](./scripts/) | Diagnostic & utility scripts | 16 |
+| [`team-config/`](./team-config/) | Team onboarding templates | 3 |
+| [`templates/`](./templates/) | Session and workflow templates | 1 |
 | [`github-actions/`](./github-actions/) | CI/CD workflows | 4 |
 | [`workflows/`](./workflows/) | Advanced development workflows | 3 |
 | [`plugins/`](./plugins/) | Community plugins (SE-CoVe, claude-mem) | 2 |
-| [`integrations/`](./integrations/) | External tool integrations (Agent Vibes TTS) | 4 |
+| [`integrations/`](./integrations/) | External tool integrations (Agent Vibes TTS) | 1 |
 | [`mcp-configs/`](./mcp-configs/) | MCP server configurations | 1 |
 | [`modes/`](./modes/) | Behavioral modes (SuperClaude) | 1 |
 | [`semantic-anchors/`](./semantic-anchors/) | Precise vocabulary for better LLM outputs | 1 |
@ -53,7 +56,7 @@ Annotated templates that teach you **why** patterns work, not just how to config

 ## Templates Index

-### Agents (9)
+### Agents (16)

 | File | Purpose | Model |
 |------|---------|-------|
@ -66,8 +69,15 @@ Annotated templates that teach you **why** patterns work, not just how to config
 | [planner.md](./agents/planner.md) | Strategic planning — read-only, before implementation | Opus |
 | [implementer.md](./agents/implementer.md) | Mechanical execution — bounded scope | Haiku |
 | [architecture-reviewer.md](./agents/architecture-reviewer.md) | Architecture & design review — read-only | Opus |
+| [adr-writer.md](./agents/adr-writer.md) | Architecture Decision Record generator — read-only | Opus |
+| [integration-reviewer.md](./agents/integration-reviewer.md) | Runtime integration validator — read-only | Sonnet |
+| [plan-challenger.md](./agents/plan-challenger.md) | Adversarial plan review across 5 dimensions — read-only | Sonnet |
+| [planning-coordinator.md](./agents/planning-coordinator.md) | Synthesis agent for dynamic research teams — read-only | Sonnet |
+| [security-patcher.md](./agents/security-patcher.md) | Apply security patches from audit findings — proposes for review | Sonnet |
+| [analytics-with-eval/](./agents/analytics-with-eval/) | Collection: analytics agent + evaluation hooks | — |
+| [cyber-defense/](./agents/cyber-defense/) | Collection: anomaly detector, log ingestor, risk classifier, threat reporter | — |

-### Skills (15) — [9 on SkillHub](https://skills.palebluedot.live/owner/FlorianBruniaux)
+### Skills (17) — [9 on SkillHub](https://skills.palebluedot.live/owner/FlorianBruniaux)

 | File | Purpose |
 |------|---------|
@ -84,10 +94,12 @@ Annotated templates that teach you **why** patterns work, not just how to config
 | [ccboard/](./skills/ccboard/) | Comprehensive TUI/Web dashboard for Claude Code monitoring |
 | [guide-recap/](./skills/guide-recap/) | Transform CHANGELOG entries into social content (LinkedIn, Twitter/X, Slack) |
 | [release-notes-generator/](./skills/release-notes-generator/) | Generate release notes in 3 formats from git commits |
-| [pr-triage/](./skills/pr-triage/) | 3-phase PR backlog management (audit, deep review, validated comments) |
+| [pr-triage/](./skills/pr-triage/) | 4-phase PR backlog management (audit, deep review, validated comments, worktree setup) |
 | [issue-triage/](./skills/issue-triage/) | 3-phase issue backlog management (audit, deep analysis, validated actions) |
+| [cyber-defense-team/](./skills/cyber-defense-team/) | Multi-agent cyber defense team orchestration |
+| [talk-pipeline/](./skills/talk-pipeline/) | 6-stage pipeline: raw material to slides via Kimi |

-### Commands (26)
+### Commands (31)

 | File | Trigger | Purpose |
 |------|---------|---------|
@ -117,12 +129,17 @@ Annotated templates that teach you **why** patterns work, not just how to config
 | [learn/quiz.md](./commands/learn/quiz.md) | `/learn:quiz` | Self-testing for learning concepts |
 | [learn/teach.md](./commands/learn/teach.md) | `/learn:teach` | Step-by-step concept explanations |
 | [learn/alternatives.md](./commands/learn/alternatives.md) | `/learn:alternatives` | Compare different approaches |
+| [audit-codebase.md](./commands/audit-codebase.md) | `/audit-codebase` | Codebase health audit scoring 7 categories |
+| [plan-start.md](./commands/plan-start.md) | `/plan-start` | 5-phase planning: PRD analysis, design review, technical decisions, research team, metrics |
+| [plan-execute.md](./commands/plan-execute.md) | `/plan-execute` | Execute validated plan: worktree isolation, TDD scaffolding, parallel agents, PR creation |
+| [plan-validate.md](./commands/plan-validate.md) | `/plan-validate` | 2-layer plan validation: structural checks + specialist agents, auto-fix issues |
+| [review-plan.md](./commands/review-plan.md) | `/review-plan` | Structured plan review across 4 axes before writing code |

-### Hooks (31)
+### Hooks (34)

 Security-first: 12 security hooks, 8 productivity hooks, 5 automation hooks, 5 monitoring hooks.

-**Security Hooks** (12 bash):
+**Security Hooks** (13 bash):

 | File | Event | Purpose |
 |------|-------|---------|
@ -138,8 +155,9 @@ Security-first: 12 security hooks, 8 productivity hooks, 5 automation hooks, 5 m
 | [claudemd-scanner.sh](./hooks/bash/claudemd-scanner.sh) | SessionStart | Detect CLAUDE.md injection attacks |
 | [output-secrets-scanner.sh](./hooks/bash/output-secrets-scanner.sh) | PostToolUse | Prevent API keys/tokens in Claude responses |
 | [pre-commit-secrets.sh](./hooks/bash/pre-commit-secrets.sh) | Git hook | Block secrets from entering commits |
+| [security-gate.sh](./hooks/bash/security-gate.sh) | PreToolUse | Detect vulnerable code patterns before writing to source files |

-**Productivity Hooks** (8):
+**Productivity Hooks** (10):

 | File | Event | Purpose |
 |------|-------|---------|
@ -151,8 +169,10 @@ Security-first: 12 security hooks, 8 productivity hooks, 5 automation hooks, 5 m
 | [rtk-baseline.sh](./hooks/bash/rtk-baseline.sh) | SessionStart | Save RTK baseline for session savings tracking |
 | [setup-init.sh](./hooks/bash/setup-init.sh) | SessionStart | Initialize session environment |
 | [subagent-stop.sh](./hooks/bash/subagent-stop.sh) | Stop | Clean up sub-agent resources |
+| [auto-rename-session.sh](./hooks/bash/auto-rename-session.sh) | SessionEnd | AI-powered session title generation (Haiku) |
+| [velocity-governor.sh](./hooks/bash/velocity-governor.sh) | PreToolUse | Rate-limit tool calls to avoid API throttling |

-**Monitoring Hooks** (5):
+**Monitoring Hooks** (6):

 | File | Event | Purpose |
 |------|-------|---------|
@ -180,7 +200,7 @@ Security-first: 12 security hooks, 8 productivity hooks, 5 automation hooks, 5 m

 > **See [hooks/README.md](./hooks/README.md) for full documentation, configuration examples, and security hardening patterns**

-### Config (5)
+### Config (8)

 | File | Purpose |
 |------|---------|
@ -189,6 +209,9 @@ Security-first: 12 security hooks, 8 productivity hooks, 5 automation hooks, 5 m
 | [.gitignore-claude](./config/.gitignore-claude) | Git ignore patterns |
 | [CONTRIBUTING-ai-disclosure.md](./config/CONTRIBUTING-ai-disclosure.md) | AI disclosure template for CONTRIBUTING.md |
 | [PULL_REQUEST_TEMPLATE-ai.md](./config/PULL_REQUEST_TEMPLATE-ai.md) | PR template with AI attribution |
+| [sandbox-native.json](./config/sandbox-native.json) | Native Claude Code sandbox configuration |
+| [settings-personalization.json](./config/settings-personalization.json) | UI personalization: spinner verbs, custom tips carousel |
+| [settings.local.json.example](./config/settings.local.json.example) | Local overrides example (gitignored) |

 ### Memory (2)

@ -197,7 +220,7 @@ Security-first: 12 security hooks, 8 productivity hooks, 5 automation hooks, 5 m
 | [CLAUDE.md.project-template](./memory/CLAUDE.md.project-template) | Team project memory |
 | [CLAUDE.md.personal-template](./memory/CLAUDE.md.personal-template) | Personal global memory |

-### CLAUDE.md Configurations (6)
+### CLAUDE.md Configurations (7)

 | File | Purpose |
 |------|---------|
@ -207,11 +230,12 @@ Security-first: 12 security hooks, 8 productivity hooks, 5 automation hooks, 5 m
 | [tts-enabled.md](./claude-md/tts-enabled.md) | Text-to-speech enabled configuration |
 | [rtk-optimized.md](./claude-md/rtk-optimized.md) | RTK token-optimized configuration |
 | [session-naming.md](./claude-md/session-naming.md) | Auto-rename sessions with descriptive titles for parallel work |
+| [design-reference-file.md](./claude-md/design-reference-file.md) | Brand-book and UI kit context for consistent UI generation |

 > **See [guide/learning-with-ai.md](../guide/learning-with-ai.md) for learning mode documentation**
 > **See [guide/devops-sre.md](../guide/devops-sre.md) for DevOps/SRE guide**

-### Scripts (13)
+### Scripts (16)

 | File | Purpose | Output |
 |------|---------|--------|
@ -222,15 +246,42 @@ Security-first: 12 security hooks, 8 productivity hooks, 5 automation hooks, 5 m
 | [clean-reinstall-claude.ps1](./scripts/clean-reinstall-claude.ps1) | Clean reinstall procedure (Windows) | Human |
 | [session-stats.sh](./scripts/session-stats.sh) | Analyze session logs & costs | JSON / Human |
 | [session-search.sh](./scripts/session-search.sh) | Fast session search & resume | Human |
+| [cc-sessions.py](./scripts/cc-sessions.py) | Advanced session search with incremental indexing | Human |
 | [fresh-context-loop.sh](./scripts/fresh-context-loop.sh) | Auto-restart sessions at context limits | Human |
 | [bridge.py](./scripts/bridge.py) | Plan bridging between sessions | JSON |
+| [bridge-plan-schema.json](./scripts/bridge-plan-schema.json) | JSON Schema for bridge plan v1 format | — |
 | [migrate-arguments-syntax.sh](./scripts/migrate-arguments-syntax.sh) | Migrate v1 → v2 argument syntax (bash) | Human |
 | [migrate-arguments-syntax.ps1](./scripts/migrate-arguments-syntax.ps1) | Migrate v1 → v2 argument syntax (PowerShell) | Human |
 | [rtk-benchmark.sh](./scripts/rtk-benchmark.sh) | Benchmark RTK token savings | Human |
 | [sync-claude-config.sh](./scripts/sync-claude-config.sh) | Sync Claude config across machines | Human |
+| [sonnetplan.sh](./scripts/sonnetplan.sh) | Alias to run Claude with Sonnet instead of Opus (cost optimization) | Human |

 > **See [scripts/README.md](./scripts/README.md) for detailed usage**

+### Rules (5)
+
+| File | Purpose |
+|------|---------|
+| [architecture-review.md](./rules/architecture-review.md) | Rules for architecture review sessions |
+| [code-quality-review.md](./rules/code-quality-review.md) | Rules for code quality review sessions |
+| [first-principles.md](./rules/first-principles.md) | First-principles reasoning rules |
+| [performance-review.md](./rules/performance-review.md) | Rules for performance review sessions |
+| [test-review.md](./rules/test-review.md) | Rules for test review sessions |
+
+### Team Config (3)
+
+| File | Purpose |
+|------|---------|
+| [claude-skeleton.md](./team-config/claude-skeleton.md) | Minimal CLAUDE.md skeleton for new team members |
+| [profile-template.yaml](./team-config/profile-template.yaml) | Profile assembly template for multi-tool teams |
+| [sync-script.ts](./team-config/sync-script.ts) | Sync Claude config across team machines |
+
+### Templates (1)
+
+| File | Purpose |
+|------|---------|
+| [session-handoff-lorenz.md](./templates/session-handoff-lorenz.md) | Session handoff template for context continuity |
+
 ### GitHub Actions (4)

 | File | Trigger | Purpose |
--- a/examples/hooks/README.md
+++ b/examples/hooks/README.md
@ -41,6 +41,9 @@ Hooks are scripts that execute automatically on Claude Code events. They enable
 | [pre-commit-secrets.sh](./bash/pre-commit-secrets.sh) | Git hook | Block secrets from entering commits | Bash |
 | [pre-commit-evaluator.sh](./bash/pre-commit-evaluator.sh) | Git hook | LLM-as-a-Judge pre-commit validation | Bash |
 | [notification.sh](./bash/notification.sh) | Notification | Contextual macOS sound alerts | Bash (macOS) |
+| [auto-rename-session.sh](./bash/auto-rename-session.sh) | SessionEnd | AI-powered session title generation via Haiku | Bash |
+| [security-gate.sh](./bash/security-gate.sh) | PreToolUse | Detect vulnerable code patterns before writing to source files | Bash |
+| [velocity-governor.sh](./bash/velocity-governor.sh) | PreToolUse | Rate-limit tool calls to avoid API throttling | Bash |
 | [security-check.ps1](./powershell/security-check.ps1) | PreToolUse | Block secrets in commands | PowerShell |
 | [auto-format.ps1](./powershell/auto-format.ps1) | PostToolUse | Auto-format after edits | PowerShell |

--- a/examples/scripts/README.md
+++ b/examples/scripts/README.md
@ -20,6 +20,12 @@ Utility scripts for Claude Code power users.
 | `cc-sessions.py` | Advanced session search with incremental indexing (Python) |
 | `session-stats.sh` | Statistics about Claude Code sessions |
 | `bridge.py` | Bridge: Claude Code → doobidoo → LM Studio |
+| `bridge-plan-schema.json` | JSON Schema for bridge plan v1 format |
+| `migrate-arguments-syntax.sh` | Migrate v1 → v2 slash command argument syntax (bash) |
+| `migrate-arguments-syntax.ps1` | Migrate v1 → v2 slash command argument syntax (PowerShell) |
+| `rtk-benchmark.sh` | Benchmark RTK token savings vs raw commands |
+| `sync-claude-config.sh` | Sync Claude config files across machines |
+| `sonnetplan.sh` | Run Claude with Sonnet replacing Opus (cost optimization alias) |

 ---

--- a/examples/skills/pr-triage/SKILL.md
+++ b/examples/skills/pr-triage/SKILL.md
@ -1,15 +1,15 @@
 ---
 name: pr-triage
 description: >
-  3-phase PR backlog management: audit open PRs, deep review selected ones, draft and post
-  review comments with mandatory validation. Args: "all" to review all, PR numbers to focus
-  (e.g. "42 57"), "en"/"fr" for language, no arg = audit only in French.
-tags: [github, pr, triage, review, maintainer, multi-agent]
+  4-phase PR backlog management: audit open PRs, deep review selected ones, post validated
+  review comments, and optionally create local worktrees for hands-on review. Args: "all"
+  to review all, PR numbers to focus (e.g. "42 57"), "en"/"fr" for language, no arg = audit only.
+tags: [github, pr, triage, review, maintainer, multi-agent, worktree]
 ---

 # PR Triage

-3-phase workflow for maintainers: automated audit of all open PRs, opt-in deep review via parallel agents, and validated comment posting.
+4-phase workflow for maintainers: automated audit of all open PRs, opt-in deep review via parallel agents, validated comment posting, and optional worktree setup for local review.

 ## When to Use This Skill

@ -158,6 +158,24 @@ _External — Problematic_: any of:

 0 PRs → display `No open PRs.` and stop.

+### Navigation Post-Phase 1
+
+After displaying the triage table, ask via `AskUserQuestion`:
+
+```
+question: "What would you like to do next?"
+header: "Next Step"
+options:
+  - label: "Phase 2 — Deep review"
+    description: "Analyze selected PRs with code-reviewer agents and generate comment drafts"
+  - label: "Phase 4 — Create worktrees"
+    description: "Set up local worktrees for hands-on review (skips comment generation)"
+  - label: "Done"
+    description: "End the workflow here"
+```
+
+Note: Phase 3 (posting comments) is NOT offered here — it requires the drafts generated in Phase 2. If the user picks "Phase 4", Phase 2 → Phase 3 remains accessible afterward.
+
 ### Automatic Copy

 After displaying the triage table, copy to clipboard using platform-appropriate command:
@ -352,6 +370,229 @@ Add your stack's checklist to the agent prompt in Phase 2. Examples by stack:

 ---

+---
+
+## Phase 4 — Worktree Setup (opt-in)
+
+Creates local git worktrees for each selected PR so you can run, test, or review code without switching branches.
+
+**Never triggered automatically** — only via Phase 1 navigation or explicit user request.
+
+### Step 4.1 — Cache check + PR list
+
+**Cache check**: before using data from Phase 1, verify it is less than 30 minutes old:
+
+```bash
+CACHE_FILE="/tmp/pr-triage-prs.json"
+CACHE_AGE=$(( $(date +%s) - $(stat -f %m "$CACHE_FILE" 2>/dev/null || echo 0) ))
+if [ "$CACHE_AGE" -gt 1800 ]; then
+  echo "STALE_CACHE"
+fi
+```
+
+If `STALE_CACHE` → re-run the Phase 1 data gathering before continuing.
+
+**Filter**: exclude Draft PRs and bot PRs (Dependabot, renovate, etc.):
+
+```bash
+python3 -c "
+import json
+prs = json.load(open('/tmp/pr-triage-prs.json'))
+filtered = [
+  p for p in prs
+  if not p['isDraft']
+  and not any(bot in p['author']['login'].lower() for bot in ['dependabot', 'renovate', 'snyk'])
+]
+import sys; json.dump(filtered, sys.stdout, indent=2)
+" > /tmp/pr-triage-phase4.json
+```
+
+If 0 PRs after filtering → display `No reviewable PRs available for worktree (all are drafts or bots).` + end Phase 4.
+
+**Display grouped by author** (use display name if available, fallback to login):
+
+```
+## PRs available for worktree (non-draft)
+
+### Alice Martin (@alice)
+  [1] #123 — feat(auth): add OAuth2 support
+      Branch: feat/oauth2  |  Size: M  |  CI: clean
+
+### Bob Chen (@bob)
+  [2] #456 — fix(api): handle empty response
+      Branch: fix/empty-response  |  Size: S  |  CI: dirty ⚠️
+```
+
+### Step 4.2 — Selection
+
+Ask via `AskUserQuestion` (multiSelect):
+
+```
+question: "Which PRs do you want to create a worktree for?"
+header: "Worktree Setup"
+multiSelect: true
+options:
+  - label: "All"
+    description: "Create worktrees for all {N} listed PRs"
+  - label: "[1] #{num} — {title} ({author})"
+    description: "Branch: {branch} | Size: {size} | CI: {ci}"
+  - label: "None"
+    description: "Cancel — return to menu"
+```
+
+If "None" → end Phase 4.
+
+### Step 4.3 — Sequential creation
+
+**Execution model**: Claude runs **one bash command per PR**, reads its output, updates its internal state (created / existing / failed), then moves to the next. Never a bash loop wrapping all PRs.
+
+For each selected PR, Claude sets variables explicitly then runs:
+
+```bash
+PR_NUM="123"
+BRANCH_NAME="feat/oauth2"
+WORKTREE_NAME="${BRANCH_NAME//\//-}"
+REPO_ROOT="$(cd "$(git rev-parse --git-common-dir)/.." && pwd)"
+WORKTREE_DIR="$REPO_ROOT/.worktrees/$WORKTREE_NAME"
+
+# Already exists?
+if [ -d "$WORKTREE_DIR" ]; then
+  echo "STATUS:EXISTING:$PR_NUM:$WORKTREE_DIR"
+  exit 0
+fi
+
+# .gitignore check (fail-fast)
+if ! grep -qE "^\.worktrees/?$" "$REPO_ROOT/.gitignore" 2>/dev/null; then
+  echo "STATUS:GITIGNORE_MISSING:$PR_NUM"
+  exit 1
+fi
+
+# Fetch remote branch
+if ! git fetch origin "$BRANCH_NAME" 2>/tmp/wt-fetch-$PR_NUM.log; then
+  echo "STATUS:FETCH_FAILED:$PR_NUM"
+  exit 1
+fi
+
+mkdir -p "$REPO_ROOT/.worktrees"
+
+# Create worktree (branch local exists or not)
+if ! git branch --list "$BRANCH_NAME" | grep -q "$BRANCH_NAME"; then
+  git worktree add -b "$BRANCH_NAME" "$WORKTREE_DIR" "origin/$BRANCH_NAME" \
+    2>/tmp/wt-err-$PR_NUM.log
+else
+  git worktree add "$WORKTREE_DIR" "$BRANCH_NAME" \
+    2>/tmp/wt-err-$PR_NUM.log
+fi
+
+if [ $? -ne 0 ]; then
+  if grep -q "already checked out" /tmp/wt-err-$PR_NUM.log; then
+    echo "STATUS:ALREADY_CHECKED_OUT:$PR_NUM"
+  else
+    echo "STATUS:CREATE_FAILED:$PR_NUM"
+  fi
+  exit 1
+fi
+
+# Optional: symlink node_modules (Node.js projects — avoids reinstall)
+[ -d "$REPO_ROOT/node_modules" ] && ln -sf "$REPO_ROOT/node_modules" "$WORKTREE_DIR/node_modules"
+
+# Copy project-specific files listed in .worktreeinclude (if present)
+if [ -f "$REPO_ROOT/.worktreeinclude" ]; then
+  while IFS= read -r entry || [ -n "$entry" ]; do
+    [[ "$entry" =~ ^#.*$ || -z "$entry" ]] && continue
+    entry="$(echo "$entry" | xargs)"
+    [ -e "$REPO_ROOT/$entry" ] && {
+      mkdir -p "$(dirname "$WORKTREE_DIR/$entry")"
+      cp -R "$REPO_ROOT/$entry" "$WORKTREE_DIR/$entry"
+    }
+  done < "$REPO_ROOT/.worktreeinclude"
+fi
+
+echo "STATUS:CREATED:$PR_NUM:$WORKTREE_DIR"
+```
+
+**Status handling** (Claude maintains internal state between PRs):
+
+| Status | Claude action |
+|--------|--------------|
+| `STATUS:CREATED:NUM:PATH` | Add to "created" list |
+| `STATUS:EXISTING:NUM:PATH` | Add to "existing" list → offer pull in Step 4.4 |
+| `STATUS:FETCH_FAILED:NUM` | Warn + continue to next PR |
+| `STATUS:GITIGNORE_MISSING:NUM` | Fail-fast: show fix instructions + stop Phase 4 |
+| `STATUS:ALREADY_CHECKED_OUT:NUM` | Warn: "Branch already checked out in another worktree. Run `git worktree list` to locate it." |
+| `STATUS:CREATE_FAILED:NUM` | Warn + continue to next PR |
+
+**GITIGNORE_MISSING fix instructions**:
+```
+.worktrees/ is not in .gitignore. Add it to avoid accidentally committing worktree files:
+  echo ".worktrees/" >> .gitignore
+Then re-run Phase 4.
+```
+
+### Step 4.4 — Update existing worktrees
+
+If any `STATUS:EXISTING` collected, offer a single prompt:
+
+```
+Existing worktrees detected:
+  PR #123 — .worktrees/feat-oauth2
+  PR #789 — .worktrees/fix-session-leak
+
+- [Pull all] git pull --ff-only in all existing worktrees
+- [#123] Pull PR #123 only
+- [Skip] Leave as-is
+```
+
+For each selected pull, Claude runs (one command per worktree):
+
+```bash
+PR_NUM="123"
+BRANCH_NAME="feat/oauth2"
+WORKTREE_DIR="/abs/path/.worktrees/feat-oauth2"
+
+cd "$WORKTREE_DIR" && git pull origin "$BRANCH_NAME" --ff-only 2>/tmp/wt-pull-$PR_NUM.log
+echo "PULL_STATUS:$?:$PR_NUM"
+```
+
+If `PULL_STATUS` ≠ 0:
+```
+⚠️ PR #123 — --ff-only failed (branches have diverged)
+   Manual fix: cd .worktrees/feat-oauth2 && git pull --rebase
+```
+
+### Step 4.5 — Summary
+
+```
+## Worktrees ready
+
+| PR | Author | Branch | Path | Status |
+|----|--------|--------|------|--------|
+| #123 | Alice | feat/oauth2 | .worktrees/feat-oauth2 | Created |
+| #456 | Bob | fix/empty-response | .worktrees/fix-empty-response | Created |
+| #789 | Alice | fix/session-leak | .worktrees/fix-session-leak | Updated (pull) |
+| #321 | Carol | feat/chat | .worktrees/feat-chat | Fetch failed ⚠️ |
+
+Note: if a PR modifies package.json, install dependencies manually:
+  cd .worktrees/<branch-name> && npm install   # or pnpm/yarn/bun
+
+Next steps:
+  cd .worktrees/<branch-name>
+  claude
+```
+
+### `.worktreeinclude` convention
+
+Create a `.worktreeinclude` file at the repo root to list files Phase 4 copies into each new worktree. Useful for local config files not tracked in git:
+
+```
+# .worktreeinclude
+.env.local
+.env.test
+config/local.json
+```
+
+---
+
 ## Edge Cases

 | Situation | Behavior |
@ -364,6 +605,11 @@ Add your stack's checklist to the agent prompt in Phase 2. Examples by stack:
 | Very large PR (>5000 additions) | Warn: "Partial review, diff truncated" |
 | Collaborators API 403/404 | Fallback to last 10 merged PR authors |
 | Parallel agents unavailable | Run sequential reviews, notify user |
+| Phase 4: `.gitignore` missing `.worktrees/` | Fail-fast, show fix instructions, stop Phase 4 |
+| Phase 4: branch already checked out | Warn with `git worktree list` hint, skip this PR |
+| Phase 4: stale cache (>30min) | Re-fetch PR list before creating worktrees |
+| Phase 4: PR modifies `package.json` | Warn in summary to run install manually |
+| Phase 4: 0 non-draft PRs | Display message + end Phase 4 |

 ---

@ -384,9 +630,9 @@ Add your stack's checklist to the agent prompt in Phase 2. Examples by stack:
 |--|-------------|--------------|
 | **Scope** | Full PR backlog | Single PR |
 | **Use when** | Catching up after accumulation, periodic triage | Reviewing a specific incoming PR |
-| **Phases** | 3 (audit + deep review + comments) | 1 (review only) |
+| **Phases** | 4 (audit + deep review + comments + worktrees) | 1 (review only) |
 | **Agents** | Parallel sub-agents per PR | Single session |
-| **Output** | Triage table + review reports + GitHub comments | Inline review |
+| **Output** | Triage table + review reports + GitHub comments + local worktrees | Inline review |
 | **Validation** | AskUserQuestion before posting | Manual decision |

-**Decision rule**: use `/pr-triage` for backlog triage (5+ PRs), `/review-pr` for focused review of a single PR.
+**Decision rule**: use `/pr-triage` for backlog triage (5+ PRs), `/review-pr` for focused review of a single PR. Use Phase 4 when you want to run the code locally rather than just reading the diff.