Guide

First, read ~/.claude/plugins/marketplaces/review-loop-marketplace/.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]

Orchestrator (this session)
│
├── Context file: .review-loop/sessions/{uuid}.md
│   Single source of truth — all agents read it each round
│
├── [Planning phase]
│   → Executor drafts plan → Reviewer critiques → iterate
│
├── [Execution phase]
│   → Executor implements → Reviewer does CR → iterate
│
├── [Quality Polish]  (skip with skip_quality_polish: true)
│   → Language analysis → Code quality → Simplify → Tests → Docs Consistency
│
└── Delivery: findings table + quality summary + time breakdown

Three skills

The review-loop workflow is now split into three composable skills. Pick the one that matches where your work currently is:

All three skills write the same session-file schema under .review-loop/sessions/{uuid}.md, so you can hand off between them (and between runtimes — plan on one, execute on the other). Codex Stage 1 follows the same broad exec -> polish -> docs -> security -> delivery lifecycle. Codex Stage 1 assumes a single orchestrator-owned workspace for the session.

Usage

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

# Handsfree — decision questions go to Reviewer, not you
/review-loop refactor auth middleware --handsfree

# If code is already written, it auto-detects and skips to CR
/review-loop review the changes I just made to the parser

# Plan-only, then execute separately (good for big multi-batch work)
/review-loop:plan design an adaptive rate limiter for /api/upload
# → prints "Next: review-loop:execute --session <uuid>"

# Fresh plan → execute multi-batch → delivery
/review-loop:execute --session <uuid> --stop-after before-delivery
# review diff, then:
/review-loop:execute --session <uuid>

# Review-only pipeline (pure CR over already-written code)
/review-loop:execute --review-only --description "parser refactor in src/parse/*"

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

Example session — fresh plan → multi-batch execution → delivery

# 1. Plan-only. Reviewer iterates until APPROVE, then exits.
/review-loop:plan split auth middleware into request-scoped + global layers

# → prints session UUID, e.g. a3c4...

# 2. Execute the plan but stop before Quality Polish so you can
#    review the raw CR diff first.
/review-loop:execute --session a3c4... --stop-after before-polish

# 3. Satisfied — resume the same session for polish + docs + security + delivery.
/review-loop:execute --session a3c4...

Example session — review-only pipeline

# Workspace is dirty from a previous coding session. You want pure CR
# on the existing diff — no plan, no re-implementation.
/review-loop:execute --review-only --description "hot-reload watcher in src/watcher/*"

# First round is Reviewer-only (no Executor runs). If REQUEST_CHANGES,
# subsequent rounds are the standard Executor → Reviewer CR → fix loop.

--stop-after <stage> (execute only)

--stop-after is accepted only by /review-loop:execute. The umbrella /review-loop skill does NOT accept --stop-after — its argument surface remains <work item description> [--handsfree] for backward compatibility. If you need mid-flow stops, invoke /review-loop:execute directly.

Stop cleanly at a seam between stages. Claude Code and Codex Stage 1 support the full set:

Unsupported values are rejected at parse time, before any lock is acquired or session field is written. Codex Stage 1 supports before-polish, before-docs, and before-security as clean stop points. Executor-created hidden worktrees are forbidden in Codex Stage 1.

--accept-external-state (unsafe opt-in)

This flag auto-accepts every "external drift detected — (A) accept / (B) abort" pause-and-confirm prompt the Orchestrator would otherwise surface:

• The drift-check decision tree (external commits / edits between batches).
• The backward-compat fallback for old sessions missing baseline metadata.

Unsafe: you are opting out of pausing on external tree drift. Use only when you know the external changes are intentional and you want to reset baseline silently. Handsfree mode alone does NOT auto-accept — this flag must be passed explicitly.

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:

Codex Stage 1 keeps review on the outside-sandbox Claude reviewer path by default. The local Codex reviewer is explicit opt-in only via codex_reviewer_backend: codex. cheap_model remains accepted-but-no-op in Codex Stage 1 because only judgment-tier Codex agents are shipped today. When neither reviewer_model nor judgment_model is set, that default Claude reviewer path backstops to claude-sonnet-4-6. quality_focus applies only when Step 3.5 Quality Polish actually runs. skip_quality_polish: true mints polish as a no-op completion and still continues through docs and security.

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

• Live Reports — see what the Reviewer found after every round
• Plan Conformance — flags unauthorized Executor deviations as CRITICAL
• Context file — persistent session for traceability and fast agent startup
• Soft limits + stuck detection — no hard cap, smart stopping
• Subagent mode — no Codex needed; uses a Claude Code sub-agent as Reviewer
• Project-specific config — tailor review priorities per project

More info

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