ultra-review

SKILL.md

name

ultra-review

description

Multi-agent, lead-orchestrated code review that gates a merge. You act as the LEAD: you spin off one or more external review agents — Claude (`claude -p`), Codex (`codex review`/`codex exec`), and Antigravity (`agy -p`) — collect every agent's findings, apply the important ones yourself (typically p0–p2, usually skipping p3), then re-run the full panel and loop until a clean round produces no findings worth blocking the merge on. Use this skill whenever the user says "ultra review," "ultra-review," "multi-agent review," "panel review," "review with codex and antigravity," "review with all the agents," "merge gate," "review and fix until clean," "gauntlet review," or any variation of "have several AIs review this and fix what matters before merge." This is a review→fix→re-review LOOP that ends only when no significant (p0–p2) findings remain, not a single review pass. For a single self-review with no external agents and no auto-fixing, use `ranked-review` instead.

ultra-review — lead-orchestrated multi-agent merge gate

You are the LEAD reviewer and integrator. You do not just collect opinions — you own the outcome. The external CLIs (claude, codex, agy) are read-only reviewers that you spawn; you are the only one who edits code. You loop until the change is clean enough to merge.

flowchart TD
    A[Setup: scope, base branch, reviews dir] --> B[Compose shared review brief]
    B --> C{Spawn panel in parallel}
    C --> C1[claude -p  · 1+]
    C --> C2[codex review · 1+]
    C --> C3[agy -p · 1+]
    C1 --> D[Collect + normalize all findings]
    C2 --> D
    C3 --> D
    D --> E[Triage by severity + dedupe]
    E --> F[Apply p0–p2 fixes · run tests/build]
    F --> G{Clean round?\n0 new p0–p2}
    G -- no, and rounds < max --> B
    G -- yes / max rounds --> H[Final merge-readiness report]

Loading

---

Step 0 — Setup

1. Determine the review target (scope).
   • Default: everything that would land in the PR — the diff of the current branch against its base, plus any uncommitted working-tree changes.
   • Detect the base branch: git rev-parse --abbrev-ref --symbolic-full-name @{u} or fall back to main/master (git remote show origin | sed -n 's/.*HEAD branch: //p'). Store as $BASE.
   • Respect any user override (a path, a commit range, "just the working tree", a specific branch).
2. Snapshot the diff once so every reviewer sees the same thing and offline reviewers don't need git access:
   • git --no-pager diff "$BASE"...HEAD and git --no-pager diff (unstaged) and git --no-pager diff --staged, plus git status --porcelain for the changed-file list.
3. Create a run directory for this invocation's reports (keep rounds separate):
   • REV_DIR="$(git rev-parse --show-toplevel)/.ultra-review" ; round files go in $REV_DIR/round-$N/<tool>-<i>.md. Add .ultra-review/ to .gitignore if it isn't already ignored (do not commit review scratch).
4. Pick the panel size. Default 1 of each (claude + codex + agy). For a high-stakes or large diff, scale to "one or more" per the user's request by assigning distinct lenses (below) — more independent perspectives catch more. Note the chosen panel to the user before running.

Suggested lenses when running multiple agents of a kind (assign one per reviewer):

Lens	Focus
correctness	logic errors, broken control flow, off-by-one, inverted conditions
security	injection, authz, secrets, unsafe deserialization, SSRF
data-integrity	silent data loss, validation gaps, unsafe coercion, races
api-contract	request/response shape, breaking changes, versioning
tests	missing/weak coverage, stale tests, untested branches
performance	N+1, unbounded work, hot-path allocations

---

Step 1 — Compose the shared review brief

Write one brief ($BRIEF) that every agent receives, so findings are comparable. It must contain:

• Scope: the base ref, the changed-file list, and (for offline-leaning agents like agy) the inlined diff. Tell reviewers they may read the wider repo for context but must not modify files.

• What to look for / not flag: reuse the priorities and exclusions from the ranked-review skill (logic & correctness first, style last; don't flag formatting, unrelated TODOs, or out-of-diff refactors).

• Severity scale (identical to ranked-review, so triage is consistent):

  Priority	Label	Definition	Lead's default action
  p0	Critical	Security hole, data loss, credential exposure, build/CI breakage	Apply
  p1	High	Broken logic, crash, silent failure, wrong business logic	Apply
  p2	Medium	Unhandled edge case, missing error handling, real perf concern	Apply
  p3	Low	Naming, readability, minor clarity	Skip (list only)

• Required output format — make every agent emit the same machine-greppable shape so you can merge reports without re-parsing prose:

  ### [P{n}] {short title}
  - file: path/to/file.ext:LINE
  - issue: one sentence on what is wrong
  - why: one sentence on the concrete consequence
  - fix: concrete remediation (snippet or precise description)
  

  End with a line: SUMMARY: {p0} p0 · {p1} p1 · {p2} p2 · {p3} p3. If zero findings, emit exactly SUMMARY: 0 p0 · 0 p1 · 0 p2 · 0 p3 and nothing invented.

Keep the brief in a variable/file you can pass to all three (e.g. $REV_DIR/brief.md).

---

Step 2 — Spawn the panel (read-only, in parallel)

Launch each reviewer in the background (separate Bash calls with run_in_background, or one shell with & + wait) so the panel runs concurrently. Each writes its report to a file. None of them may edit code — that is the lead's job, and it also prevents three agents clobbering the same files.

Claude reviewer — claude -p (headless, read-only)

claude -p "$(cat "$REV_DIR/brief.md")" \
  --append-system-prompt "You are a read-only reviewer. Never modify files. Output only the findings in the required format." \
  --allowedTools "Read,Grep,Glob,Bash" \
  --disallowedTools "Edit,Write,MultiEdit,NotebookEdit" \
  --output-format text \
  > "$REV_DIR/round-$N/claude-1.md" 2>&1

• --allowedTools lets it read files and run git/grep without hanging on permission prompts; omitting the edit tools (and disallowing them) keeps it read-only in non-interactive mode.
• For multiple claude reviewers, append the lens to the prompt and write claude-2.md, etc. Add --model <id> to vary the model if desired.

Codex reviewer — codex review (purpose-built, sandboxed read-only)

# Diff vs base branch (typical merge gate):
codex review --base "$BASE" "$(cat "$REV_DIR/brief.md")" \
  > "$REV_DIR/round-$N/codex-1.md" 2> "$REV_DIR/round-$N/codex-1.err"
# Or, to review the working tree (staged + unstaged + untracked):
#   codex review --uncommitted "$(cat "$REV_DIR/brief.md")" > codex-1.md 2> codex-1.err

• codex review understands the diff itself and runs read-only; the custom prompt injects our severity scale + output format.
• Noise: codex writes findings to stdout but leaks MCP-auth warnings, hook: lines, and a token-count footer to stderr — keep stderr in a separate .err file (as above) so the report stays clean. If you must combine streams, ignore lines matching ERROR rmcp, ^hook:, ^tokens used, and bare digit lines.
• Alternative if you want the identical brief semantics rather than codex's own diff handling: codex exec -s read-only "$(cat "$REV_DIR/brief.md")" > codex-1.md 2> codex-1.err. The -s read-only sandbox guarantees it cannot write.

Antigravity reviewer — agy -p (print mode, read-only)

agy -p "$(cat "$REV_DIR/brief.md")" --print-timeout 12m \
  > "$REV_DIR/round-$N/agy-1.md" 2>&1

• Print mode default timeout is 5m; bump it for large diffs.
• agy's print-mode tool-permission behavior is the least predictable, so make it need no tool access: inline the full diff and changed-file list directly in the brief, and run it under --sandbox (terminal-restricted) for a read-only posture. The brief already tells it to review only and never write. If it still can't make progress without a permission you're unwilling to grant in a config, drop agy from the panel for that run and note the gap rather than weakening the sandbox — never silently broaden a reviewer's permissions. Pin a model with --model <id> if wanted (agy models lists them).

Run all three (or more) concurrently. Wait for every report file to be complete before collecting. If a reviewer dies or returns empty, note it and proceed with the rest — never block the gate on one agent, but do report the gap.

---

Step 3 — Collect & normalize

• Read every round-$N/*.md.
• Parse the ### [P{n}] blocks into one combined list tagged with the originating agent.
• Dedupe: collapse findings that point at the same file+line+root-cause, even when worded differently across agents. Keep the highest severity any agent assigned, and record corroboration (e.g. "flagged by claude + codex"). Cross-agent agreement raises confidence; a lone flag deserves a quick sanity check before you act.

---

Step 4 — Triage (you decide, not the agents)

For each unique finding decide: apply, defer, or reject.

• Apply by default: p0, p1, p2. These are the blockers.
• Skip by default: p3. List them in the final report as optional polish; don't fix unless trivial and adjacent to a fix you're already making, or the user asked for p3s too.
• Reject any finding you judge wrong, out of scope, or a false positive — but record the rationale. Disagreeing with an agent is fine; silently dropping a blocker is not.
• Re-rank when an agent mis-severitized. Your judgment as lead is authoritative; the p-labels are inputs, not orders.
• A test/build/CI failure you can reproduce is p0, regardless of how an agent labeled it.

---

Step 5 — Apply fixes (lead only)

• Make the edits yourself, smallest correct change first, matching surrounding code style.
• After applying a round's fixes, run the project's tests and build/lint (per the repo's own conventions). Treat any newly-failing test as a p0 to resolve before the round counts as done.
• For any behavioral fix, add or update a test that would have caught the bug (regression-first), consistent with the repo's testing rules. Keep coverage from regressing.
• Commit only if the user asked; otherwise leave the working tree staged/clean for their review.

---

Step 6 — Re-review loop & termination

After applying a round's fixes, start a fresh round from Step 1's brief (regenerate the diff — it changed) and spawn the panel again into round-$((N+1))/.

Stop when a complete round produces zero new findings at or above the blocking threshold (default p2 — i.e. 0 new p0/p1/p2). Remaining p3s and any consciously-rejected items don't block.

Guards:

• MAX_ROUNDS = 4 (configurable). If blockers persist at the cap, stop and report the unresolved blockers rather than looping forever — don't hide non-convergence.
• Thrash detection: if the same finding reappears after you tried to fix it, the panel may be wrong, or your fix incomplete, or two agents disagree. Investigate and resolve deliberately; do not blindly re-apply the same edit each round.
• Diminishing returns: if a round only surfaces p3s, you're done — that's a clean gate.

---

Step 7 — Final report

Summarize for the user (a short markdown summary inline; offer an Artifact only if they'd want a shareable page):

• Verdict: ✅ merge-ready / ⚠️ merge-ready with noted caveats / ❌ blockers remain (with what).
• Rounds run and per-round severity counts (e.g. R1: 2 p0 · 3 p1 · 1 p2 → R3: 0 p0 · 0 p1 · 0 p2).
• Applied: each fix with file:line reference and a one-line description.
• Deferred (p3) / Rejected: list with one-line rationale each.
• Panel: which agents ran, plus any that failed/were skipped.
• Tests/build: final status.

---

Configuration & arguments

Accept these from the user's invocation (sensible defaults in bold):

Knob	Default	Notes
panel composition	1 claude · 1 codex · 1 agy	scale up with lenses for big/risky diffs
scope	branch vs $BASE + working tree	or a path, commit range, or "working tree only"
blocking threshold	p2 (apply p0–p2)	raise to p1 for a lighter touch, lower to p3 to fix everything
MAX_ROUNDS	4	safety cap on the loop
models	each CLI's default	override per reviewer via --model

---

Notes, gotchas & rules of thumb

• You are the lead. Agents advise; you decide and you alone edit. Never delegate the fix-apply to the CLIs — concurrent edits conflict, and you own correctness.
• Read-only reviewers. Every spawn is sandboxed/read-only by flags + instruction. If a reviewer asks to edit, that's a misconfiguration — fix the flags or drop that agent; never broaden a reviewer's write permissions to push a review through.
• Parallelism. Launch the panel concurrently (background Bash); a round is gated by the slowest reviewer, not the sum.
• Codex stderr is noisy — always split it to a .err file or filter it; the real findings are on stdout.
• Agy can stall on permissions in print mode — inline the diff and use --sandbox; if that's not enough, drop it from the panel and report the gap rather than loosening its sandbox.
• Don't invent findings. A clean round is a valid, good outcome — report it plainly.
• Cross-agent agreement is signal; act on corroborated blockers first.
• Sibling skills: ranked-review (single read-only review, no fixes) and code-review (your own diff review). ultra-review is the multi-agent, fix-and-loop superset.