code-review-specialists

name	code-review-specialists
description	Review a code change through an internally selected quick, focused, specialist, follow-up, or pre-merge mode and return evidence-grounded findings.

Code Review

Use this as the generic read-only code-review outcome. The workflow selects the smallest review mode that satisfies the request and risk, then returns findings before any summary.

Contract

Prereqs:

• Run inside the target git repository with git available on PATH.
• review-specialists is installed from the released nils-cli package and available on PATH.
• Know the base ref for the diff under review, or explicitly choose one before running scope detection.
• Keep this workflow read-only: it does not auto-fix code, merge, close PRs/MRs, open/close issues, or post live provider comments.
• Dispatch the managed read-only reviewer-<lens> subagents for the selected lenses whenever the active host exposes subagent dispatch. In Codex sessions, if multi_agent_v1.spawn_agent or an equivalent dispatch tool is exposed, Codex must dispatch the selected reviewers; inline lens execution is only the fallback when dispatch is unavailable or blocked, and the fallback must be stated. The parent agent owns lens selection, dispatch, validation, and merge.
• Leave provider review decisions to the owning PR or dispatch parent. Create a review-evidence CLI record only when findings need retained evidence.

Inputs:

• Diff base ref, optional review target summary, and optional validation evidence to inspect.
• Optional requested focus or forced specialist flags: --testing, --security, --performance, --data-migration, --api-contract, --maintainability, --red-team, or --all-specialists.
• Optional specialist JSONL finding files for deterministic validation, merge, rendering, and bundle synthesis.
• Optional confidence display threshold for merged findings.

Outputs:

• A mode decision (quick, focused, specialist, follow-up, or pre-merge) grounded in request, scope, and delivery context.
• Scope JSON from review-specialists scope describing changed files, diff size, stack signals, test framework signals, and suggested specialists.
• Read-only specialist findings with concrete file or evidence anchors.
• A final specialist review report using references/SPECIALIST_REVIEW_REPORT_TEMPLATE.md.
• Optional review-evidence records when retained workflow evidence is needed.
• No source edits, PR/MR comments, merge decisions, or close decisions from this workflow.

Failure modes:

• Base ref is missing or does not resolve in the target repository.
• Specialist output is malformed JSONL, lacks required fields, uses unsupported severity values, or omits evidence anchors.
• Findings lack enough confidence or evidence to support a concrete issue; mark them as residual risk instead of presenting them as verified findings.
• Caller tries to use this read-only workflow as a substitute for provider write authority owned by the PR or dispatch parent, retained evidence, browser-operation checks, CI repair automation, or implementation work.

Entrypoint

Use the released CLI directly:

review-specialists scope --base "$BASE_REF" --format json
review-specialists validate --input findings.jsonl --format json
review-specialists merge --input findings.jsonl --summary-out specialist-review.md --format json
review-specialists render --profile report --input merged-findings.json --out specialist-review.md
review-specialists bundle --input findings.jsonl --out-dir "$REVIEW_OUT" --profile report --format json

Mode Selection

The caller requests the review outcome; the workflow selects the mode.

• Follow-up — previous findings or review threads are supplied and must be classified as resolved, unresolved, accepted, or residual risk.
• Pre-merge — the review is a delivery gate. Force at least testing and maintainability, add risk lenses, preserve comment-before-fix ordering, and return a decision to the delivery owner.
• Focused — the user explicitly asks for one or more lenses. Force only those lenses unless scope reveals a mandatory safety lens.
• Quick — the diff is small or ordinary, with no migration, security, public API, or other specialist trigger. Inspect the complete diff directly and report concrete findings or a clean result plus residual test risk.
• Specialist — the diff is broad, risky, cross-cutting, or exceeds normal reviewer confidence. Use scope detection and the specialist workflow below.

All modes are read-only. When reviewer subagents are available and a mode uses one or more lenses, the workflow must dispatch the selected reviewers. The parent owns base selection, synthesis, and any authorized provider action.

Workflow

1. Establish the review target and base ref. For a PR/MR, use the actual PR/MR base or merge-base rather than a moving origin/main guess. Inspect previous findings and delivery context before selecting a mode.

2. Select the mode using the precedence above.

3. For quick mode, inspect the complete diff, changed tests, and validation evidence directly. Report findings first with file anchors; if clean, state that explicitly and name residual test or validation risk. Stop without manufacturing specialist work.

4. For follow-up mode, re-check every supplied finding against the current diff and classify it as resolved, unresolved, accepted, or residual-risk. Do not broaden scope unless a fix created a new concrete regression.

5. For focused, specialist, and pre-merge modes, run deterministic scope detection:

   review-specialists scope --base "$BASE_REF" --format json
   

6. Select specialists:

   • In focused mode, use the requested lenses.
   • In pre-merge mode, always include testing and maintainability.
   • In specialist mode, use the scope suggestions and rules below.
   • Always consider testing and maintainability for larger diffs.
   • Consider security for auth changes or backend changes over 100 diff lines.
   • Consider performance for backend or frontend runtime changes.
   • Consider data-migration for migration, schema, or data transform changes.
   • Consider api-contract for route, controller, API schema, OpenAPI, GraphQL, or protocol changes.

7. Select the matching managed reviewer subagents for the chosen lenses (reviewer-testing, reviewer-maintainability, reviewer-security, reviewer-performance, reviewer-data-migration, reviewer-api-contract), installed at ~/.codex/agents/reviewer-<lens>.toml and ~/.claude/agents/reviewer-<lens>.md.

8. Dispatch the selected read-only reviewer subagents one per lens, handing each the base ref and scope; each inspects read-only and returns JSONL findings for its lens. In Codex, use multi_agent_v1.spawn_agent when it is available. If dispatch is unavailable or blocked, state the fallback reason and run the same lenses inline by reading the prompt from references/specialists/. You stay the parent: you own base-ref selection, lens selection, dispatch, fallback justification, and the validation/merge steps below.

9. Collect each subagent's JSONL findings (or the inline equivalent) following references/SPECIALIST_REVIEW_CONTRACT.md. Treat malformed JSONL, missing required fields, unsupported severities, or absent evidence anchors as a workflow failure or residual risk for that lens — never promote it to a verified finding. Mark unverifiable claims as residual risk, not findings.

10. Validate and merge findings:

review-specialists validate --input findings.jsonl --validate-paths --format json
review-specialists merge --input findings.jsonl --summary-out specialist-review.md --format json

11. Run red-team only after the selected specialists when diff_lines > 200, any selected specialist produced a critical finding, or the reviewer forced it. Dispatch reviewer-red-team when subagent dispatch is available. If dispatch is unavailable or blocked, state the fallback reason and run the same red-team lens inline from references/specialists/red-team.md. Hand it the merged first-wave findings so it can probe cross-cutting failure modes. Pass the red-team JSONL through review-specialists validate, then append it to the first-wave JSONL and run review-specialists merge again over the combined input so duplicate fingerprints, confirming specialists, and confidence ordering are resolved in the final report.
12. Use the report template for the final synthesis. For pre-merge mode, apply references/DELIVERY_SPECIALIST_REVIEW_GATE.md and references/REVIEW_OUTCOME_POSTING_CONTRACT.md; the delivery owner, not a reviewer, posts provider comments and makes the merge decision. For every mode, the recommended next step may route to the dispatch parent's independent-review phase, a normal implementation workflow, or a retained review-evidence CLI record, but this workflow does not execute that decision.

Boundary

code-review-specialists owns mode selection, read-only diff inspection, scope detection, specialist selection, reviewer-subagent dispatch, follow-up classification, validation and merge of returned findings, and the final report. Each reviewer-<lens> subagent owns only its read-only lens. This workflow does not fix code, post PR or MR review comments, mark a draft reviewable ready, merge, close issues, or execute the recommended next step — those belong to the owning PR / MR or dispatch parent and the evidence control plane.

References

• Reviewer subagent sources: core/agents/code-review/reviewer-<lens>/AGENT.md.tera
• Specialist review contract: references/SPECIALIST_REVIEW_CONTRACT.md
• Report template: references/SPECIALIST_REVIEW_REPORT_TEMPLATE.md
• Specialist prompts: references/specialists/
• Delivery specialist review gate: references/DELIVERY_SPECIALIST_REVIEW_GATE.md
• Delivery review outcome comment: references/DELIVERY_REVIEW_OUTCOME_COMMENT.md
• Specialist review comment: references/SPECIALIST_REVIEW_COMMENT.md
• Review outcome posting contract: references/REVIEW_OUTCOME_POSTING_CONTRACT.md
• Delivery review outcome schema: references/DELIVERY_REVIEW_OUTCOME_SCHEMA.md
• Evidence routing policy: core/policies/evidence-control-plane.md