First, read ${CLAUDE_PLUGIN_ROOT}/.claude-plugin/plugin.json to get the current version number.

Then display the following guide to the user, replacing {VERSION} with the version from plugin.json:

review-loop {VERSION} — Quick Reference

How it works

/review-loop <work item description> [--handsfree]

review-loop entry (resolves `entry`, runs the stage A checks)
│
└── paired-session coordinator (run directory under <repo>/.review-loop/runs/)
    ├── PLAN   author drafts the plan → independent reviewer → iterate
    ├── EXEC   author implements → reviewer + shadow review → iterate
    ├── GATE   adversarial gate
    ├── with lifecycle on: FINISH → POLISH-Q specialists → docs → security
    └── DONE (or HOLD) → you accept or reject; nothing ships without your decision

Commands

The legacy workflow was removed in v2.13.0 (routing) and v2.13.1 (/review-loop:legacy, /review-loop:plan, /review-loop:execute and its protocol files). Their replacements: plan-only work → /review-loop:paired-session <work item> --plan-only; an existing plan or a review of existing code → /review-loop. Legacy session files under .review-loop/sessions/ are left on disk and never read; resuming one is refused. See docs/paired-session-migration.md.

Entry

The entry key in .review-loop/config.md takes legacy or paired-session, written unquoted (exact values only; since v2.13.0 legacy is refused, and anything else is warned about and treated as absent). With the key absent or paired-session, fresh work, an existing plan (used as the work item; PLAN drafts and reviews it again) and a review-only request on existing code (run --review-only, plus --base <ref> when you name a base) are handed to paired-session; resuming a legacy session is refused. Unrelated dirty work is not existing code: a review-only run reviews and, with auto_commit, delivers every change against its base. A failed check before the coordinator starts (a host other than macOS or native Windows, required CLIs, background or outside-sandbox execution, Codex home, on Codex an installed plugin older than v2.10.0, or a declined or unanswered worktree or test-command question; under handsfree any such question counts as unanswered) refuses with the reason, whether the key is set or not (unavailable background or outside-sandbox execution is reported as HOLD); nothing falls back. Once the coordinator has started, a refusal or HOLD is reported. Roles come from the operator profile you name or ~/.config/review-loop/paired-session.json; without one, Codex is the author and gate and Claude the reviewer. Gemini (Antigravity CLI agy) is an optional third vendor for the reviewer and the gate (README.md, Configuration). Every run uses one mode: every sandbox applies and no permission probe exists (permission-probe and strict mode were removed in v3.7.0; --strict only prints a NOTE). A reviewer turn that changes the workspace is voided and restored, and an author commit is a HOLD. Platforms: macOS and native Windows (Linux and WSL are refused). On Windows --detach is refused, Claude roles run without the Claude Code Bash sandbox, Git for Windows (Git Bash) is required, and run directories and workspaces stay out of OneDrive-synced folders. On Codex, ask "use paired-session for this task". Details: docs/paired-session-migration.md.

/review-loop:review-pr [PR number|PR URL|ref] [aspects] runs the paired-session report mode (entry: legacy and --legacy are refused since v2.13.0). A PR or ref is reviewed in a temporary clone (the operator's checkout is never touched); no tests run unless you confirm a test command; the EXEC reviewer, shadow, gate, the selected specialists (code errors comments types tests) and the security stage report into review-report.md in the run directory, and nothing is fixed, committed or posted. Posting is a separate request with a secret scan and a second confirmation of the full body (gh pr review --comment only). simplify is a writer and is refused on this route (run /review-loop:code-quality-loop on the change (its POLISH-Q simplifier)).

Usage

# Basic — starts the paired-session plan→review→implement→CR run
/review-loop add rate limiting to the /api/upload endpoint

# If code is already written, it hands off as a review-only run
/review-loop review the changes I just made to the parser

# I already have a plan: /review-loop (the plan becomes the work item)
/review-loop implement this plan: <plan text>

# Plan only
/review-loop:paired-session design an adaptive rate limiter for /api/upload --plan-only

# Show this guide — slash command or natural language
/review-loop:guide
show me the review-loop guide

After updating the plugin: exit with Ctrl-C twice, then claude --resume to reload plugins while keeping your conversation. Old sessions keep using the version loaded at startup.

Configuration

Create .review-loop/config.md in your project to customize:

Unset paired-session caps are plan 3 / exec 4 rounds. reviewer_model and executor_model only warn (models come from the operator profile); the other legacy keys are ignored. See docs/paired-session-migration.md (Config mapping).

review_focus examples

# Backend
review_focus: |
  - Concurrency: race conditions, deadlocks, mutex usage
  - Test coverage: error paths, not just happy paths

# Frontend
review_focus: |
  - Security: XSS, CSRF, input sanitization
  - Accessibility: WCAG, keyboard nav, screen reader

# Web API
review_focus: |
  - Security: auth checks, rate limiting, input validation
  - API contract: backward compatibility, proper status codes

Key features

• Independent review — the reviewer, shadow and gate never share the author's session
• Hard caps — blocking PLAN/EXEC reviews HOLD at the cap; resume --add-rounds N (1-10) continues the run. Eligible advisory-only reviews get one repair attempt per phase, then advisory acceptance, or exit at the cap without an attempt. Writer replay takes the advisory exit at any round and preserves the attempt. Blocking rounds preserve it; send-back grants a new EXEC attempt. EXEC needs a passed configured test, own run evidence and the current tree. See the advisory rules for open ledger rows.
• Acceptance stays yours — a DONE run is accepted or rejected only on your explicit decision
• Project-specific config — tailor review priorities per project

More info

GitHub: https://github.com/NYTC69/review-loop

Troubleshooting

• A plugin update does not take effect. Claude Code loads plugins at session start, and /reload-plugins does not switch versions. After /plugin update, start a new session (or exit with Ctrl-C twice and claude --resume to keep the conversation).
• A headless (claude -p) run stops when the turn ends. -p exits at the end of its turn and kills the background coordinator. Use an interactive session; on macOS a headless session can start the run with --detach (it returns at once with its pid and log; stop ends it).
• --detach is refused on Windows. A headless session is not supported there. Drop the flag and use an interactive session.
• An entry refuses with paired-session needs macOS or native Windows. Linux (WSL included) is not supported. Run from macOS or native Windows.
• A slash command does nothing in Codex (Unrecognized command). Codex matches skills by their description, in natural language only. Ask in plain words, for example "run review-loop on this branch" or "review PR 123".