council-review

What this skill does

# 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.

```bash
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.