| name | code-review |
| description | Compatibility launcher for the code-review agent. Delegate a GitHub PR review to Codex via codex exec. Codex runs the test suite first (the gate), scores six axes, and writes ONE combined artifact IN THIS REPO under .reviews/<pr>/<sha>.md plus findings.json/suggestions.json. Use when the user runs /code-review, asks to review a PR, or is preparing a PR for human merge. |
/code-review — PR review with six-axis scoring + embedded tests
This skill is a compatibility command for the code-review agent. Workflow
docs should refer to the agent; this command exists so /code-review still
launches the same reviewer contract.
Produces one combined artifact in this repo at
.reviews/<pr-number>/<short_sha>.md. The schema, scoring rubric,
severity-based body rules, anti-slop checklist, and verdict logic are owned by
the in-repo contract — Codex reads .agents/code-review.md
before scoring (and .agents/testing.md for runner detection).
Forge: GitHub or GitLab, detected per repo (.claude/bin/forge; command
mapping in .agents/forge.md). Artifacts are
in-repo — no central dashboard, no harness phone-home.
Delegate to Codex
Do not perform the review inside Claude. Delegate the full review to Codex
so artifacts are produced by the standard reviewer. Run codex exec from this
repo's root (-C "$PWD"), and pass a self-contained prompt that points Codex at
the in-repo contract + output path. Do not use Codex's global /code-review
slash command — it targets a different (central) artifact store; the prompt
below keeps everything in-repo.
Rule: run in the background — review is the dev-speed bottleneck
Code review is the most common bottleneck to dev speed in this workflow. A
review takes ~4 minutes (test gate + six-axis scoring + artifact write).
Blocking the session on it is almost always the wrong call.
Default to a non-blocking background run. Fire Codex in the background,
surface the task id, and immediately go do other useful work during those
~4 minutes — start the next ticket, open the next PR, prep follow-up fixes,
update docs/session state. You'll be notified when the review completes; relay
the verdict + artifact path then. Do not poll or sleep waiting on it — that
just re-creates the block you were avoiding. Only stop and wait if there is
genuinely nothing else to advance.
Invoke via Bash with run_in_background: true:
codex exec -s danger-full-access -C "$PWD" "Review the PR/MR at <URL> at its current head commit. The forge is GitHub or GitLab: run .claude/bin/forge to find which, and use gh (GitHub) or glab (GitLab) per .agents/forge.md to resolve the change number, head SHA, base, and diff. Follow the review contract in .agents/code-review.md in this repo exactly: run the detected test suite first as the gate, and if tests are not green stop at a blocked test-gate artifact. Otherwise score the six axes (for the Security axis, first run the deterministic floor via .claude/skills/security-scan in diff mode and take the lower of its recommended score and your manual read), compose findings with copy-pasteable fix prompts, and pick a verdict. Write the combined artifact to .reviews/<number>/<short-sha>.md, and update .reviews/<number>/findings.json and .reviews/<number>/suggestions.json per the contract. If the change is visual/UX-affecting and a screenshot would help the reviewer or human merger decide, capture screenshots and write .reviews/<number>/screenshots.json per the contract's Screenshots section (save frames under .reviews/<number>/screenshots/); skip this entirely for non-visual changes. If you spot real work that is out of scope for this change (latent bugs elsewhere, worthwhile refactors, missing test surfaces, follow-up extensions), file a backlog ticket using .claude/skills/ticket: check bin/tickets open for duplicates, allocate an id with bin/next-ticket-id, write backlog/NNNN-slug.md per EXAMPLE.md, and reference the ticket id in the artifact Suggestions section."
-s danger-full-access is required: the test gate frequently binds loopback
TCP ports, writes /tmp, or calls local infra. The default workspace-write
sandbox blocks loopback bind and turns a passing suite into a false
test_status: fail + blocked verdict.
Backticks footgun. The codex prompt is passed through the shell — any
literal backtick becomes command substitution and codex hangs reading stdin.
Keep the prompt backtick-free (write "tsc" not the backticked form). If
backticks are unavoidable, write the prompt to a temp file and pass
"$(cat /tmp/prompt.txt)".
Stacked-MR batch mode
In /stacked-mr mode this skill is invoked once per PR as a parallel batch at
the end of the stack — not per-PR during the build. Each invocation is still a
normal single-PR review (one URL → one preflight packet → one
.reviews/<number>/<sha>.md + its own findings.json/suggestions.json). The
/stacked-mr skill orchestrates the concurrency and gives each review its own
worktree so the parallel reviews don't corrupt each other's checkout. Don't try
to review N PRs in one call — there is no multi-URL mode. See
.agents/code-review.md → "Batch stacked-MR
review".
When to run synchronously (foreground)
Only when the next step depends on the verdict: the user said "wait for it",
you're inside an explicit fix-until-approve loop, or this is the final pass
before an imminent manual merge. When in doubt, background.
Reading background results
When the completion notification arrives, read the task output and surface, in
one concise message: the verdict (approve/request-changes/blocked), the
artifact path (.reviews/<pr>/<sha>.md), test totals, and key findings
(counts + severities). Don't replay the transcript.
Fallback
Run the review directly in Claude only if codex is unavailable OR the user
explicitly asks. Inline reviews lose the standard-reviewer behavior (six-axis,
test gate, findings.json diff) so are last-resort. If you do, follow
.agents/code-review.md yourself.
Hard rules (override everything in the contract)
- Tests must pass.
test_status != pass → verdict: blocked. No exceptions.
- Approve is earned. Requires
test_status == pass, zero ≥ medium
findings, AND a one-sentence articulation of why the PR is safe. If you
can't write that sentence, don't approve. (Per this project's bar the
overall score is informational — the gate is verdict + 0 medium+ + tests.)
- No merge-to-main bypassing. Any push/force-push/merge to a protected
branch, anything violating global §8 → automatic critical finding, verdict
blocked.
What this skill is NOT
- Not the built-in
/review (a generic ad-hoc reviewer). This produces the
in-repo .reviews/ artifact format.
- Not a fixer. Findings get fix prompts; fixes happen in a follow-up commit
— re-run
/test-suite to confirm green, then /code-review to re-score.
- Not standalone test-run. Use
/test-suite for ad-hoc runs that print to
chat without writing an artifact.
Activity
After the review artifact is written, emit a feed event:
.claude/bin/activity pr-verdict "Review · <verdict> · !<iid>" "<repo> @ <short_sha>" --pr <iid>
