council-review

name

council-review

description

Multi-perspective code review that synthesizes findings from multiple reviewers into a unified report. Use when the user asks to review code changes, audit a diff, check code quality, review a PR, review commits, or review uncommitted changes. Also covers 'code review', 'review my changes', 'check this before I merge', or wanting multiple perspectives on code. Do not use for documentation/markdown review or trivial single-line changes.

Council Review

Run Codex, Claude's own /review, and /code-review max in parallel, then cross-validate and synthesize into one unified report — like a review board where three reviewers examine the code from different angles, and Claude as lead reviewer delivers the final opinion.

Prerequisites

• Codex CLI: Install with npm i -g @openai/codex, authenticate with codex login

If only one CLI is installed, fall back to the available reviewer with a warning — the review still has value with fewer perspectives, so don't fail entirely.

Workflow

Do not read script source code. Run scripts directly and use --help for usage.

Step 1: Determine Review Scope

If the scope is not already clear, use AskUserQuestion to ask:

• Uncommitted changes (default) — staged, unstaged, and untracked changes
• Branch diff — compare current branch against a base branch
• Specific commit — audit a single changeset

Step 2: Run All Three Reviews in Parallel

All three reviewers read the same diff independently — none depends on another's output. Launch all three at once in a single message to eliminate sequential wait time.

Scripts are in scripts/ relative to this skill's directory and enforce the correct model and read-only mode internally. Run <script> --help for full usage.

Codex — scripts/codex-review.py (background Bash task)

Launch as a background Bash task (run_in_background: true). Codex CLI may take up to 30 minutes. When it completes, use the Read tool on the output-file path from the notification to retrieve the review.

python3 scripts/codex-review.py uncommitted
python3 scripts/codex-review.py branch --base main
python3 scripts/codex-review.py commit <SHA>

Claude — /review skill (background Agent)

Launch a background Agent (run_in_background: true) to run /review on the same scope. Prompt the agent to invoke the /review skill (via the Skill tool) and return its complete findings. The agent's output arrives directly in its completion notification.

Quality — /code-review max skill (background Agent)

Launch a background Agent (run_in_background: true) to run /code-review max on the same scope. Prompt the agent to invoke the code-review skill with max effort (via the Skill tool), then return only its analysis and findings as text — do not apply any code fixes. The agent's output arrives directly in its completion notification. (/code-review fixes issues by default, so the report-only instruction is required, not optional.)

After launching all three background tasks, end your turn immediately. Do not output anything else, do not proceed to Step 3, and do not check on task progress. You will be notified automatically when each task completes.

Step 3: Cross-Validate Findings

Once you have received completion notifications for all three tasks, cross-validate:

1. Validate external findings — For each finding from Codex and /code-review max:
   • Confirm — Claude independently agrees the issue exists and is correctly described.
   • Dispute — Claude believes the finding is a false positive or incorrectly categorized. Note the reasoning.
   • Enhance — The issue exists but the explanation or suggested fix can be improved. Provide the improved version.
2. Add Claude's own findings — Include any issues from /review that the other reviewers didn't catch.
3. Note cross-reviewer agreement — Track which findings were flagged by multiple reviewers (higher confidence).

Step 4: Synthesize into Unified Report

After your own review and validation are complete, merge, deduplicate, and rewrite all findings into one coherent report as if written by a single reviewer. Do not copy-paste or concatenate raw outputs.

Load references/output-format.md for the report template. Load references/merge-rules.md for how to reconcile findings across reviewers.

Rules

• Use the same review scope for all reviewers. Comparing different scopes would make deduplication meaningless.
• Run /code-review max agent as report-only. Instruct the agent explicitly to return findings as text and skip code fixes.
• Write one unified opinion. The report reads as a single reviewer's assessment. Do not structure findings by reviewer (no "Codex found..." or "Quality found..." sections).
• Sort findings by priority — P0 → P1 → P2 → P3 → P4.
• Exclude low-confidence findings. If Claude disputes an external finding or evidence is purely circumstantial, omit it from the report. The council's value is cross-validation; findings that fail it are noise.
• Always use the wrapper script for Codex. The script sets the correct model and read-only mode; calling codex CLI directly bypasses these.
• Suppress intermediate outputs. Running each skill in a subagent keeps raw reviewer output out of the main conversation. The only review output the user should see is the final unified report.
• Read background-task output via the Read tool on the output-file path from the completion notification. TaskOutput cannot find background Bash task IDs and will fail. For background Agents, read the result directly from the completion notification.
• If a reviewer fails at runtime, fall back to the remaining reviewers when at least two succeed. With fewer than two reviewers, stop and report the error — a single-reviewer result lacks cross-validation.