Code Review Specialists

Code Review Specialists

Use this workflow to review broad or risky diffs through focused, read-only specialist lenses before a reviewer makes a decision.

Contract

Prereqs:

• Run inside the target git repository with git 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, or

post live PR comments.

• Use explicit user instruction or a delegation mode such as parallel-first or

orchestrator-first before spawning reviewer subagents.

• Use dispatch-pr-review for PR decision actions and review-evidence only when

findings need a retained evidence record.

Inputs:

• Diff base ref, optional review target summary, and optional validation

evidence to inspect.

• Optional forced specialist flags:

--testing, --security, --performance, --data-migration, --api-contract, --maintainability, --red-team, or --all-specialists.

• Optional specialist JSONL finding files for deterministic merge and report

synthesis.

• Optional confidence display threshold for merged findings.

Outputs:

• Scope JSON from the deterministic helper 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 comments, merge decisions, or close decisions from this

workflow.

Exit codes:

• 0: helper command succeeded.
• 1: helper command failed due to missing repository state, malformed input,

invalid findings, or other runtime failure.

• 2: helper usage error from argparse.

Failure modes:

• Base ref is missing or does not resolve in the target repository.
• Diff is too small or low-risk for specialist review and no specialist was

forced.

• 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 workflow as a substitute for dispatch-pr-review,

review-evidence, browser-qa, CI repair automation, or implementation work.

Entrypoint

• $AGENT_HOME/skills/workflows/code-review/code-review-specialists/scripts/review_specialists.py

When To Use

• The user explicitly asks for specialist code review.
• A PR or diff is large, risky, security-sensitive, migration-heavy, API-contract

heavy, or broader than normal reviewer confidence.

• Normal tests are not enough to reason about cross-cutting risk.
• An issue or plan PR review needs supplemental specialist findings before the

dispatch-pr-review decision path.

Do not use it for tiny diffs, ordinary implementation work, pure formatting or doc-only changes unless requested, CI repair loops owned by gh-fix-ci, or browser-facing checks owned by browser-qa.

Workflow

1. Establish the review target and base ref.
2. Run deterministic scope detection:

``bash $AGENT_HOME/skills/workflows/code-review/code-review-specialists/scripts/review_specialists.py scope --base ``

1. If diff_lines 200, any

selected specialist produced a critical finding, or the reviewer forced it. Merge red-team findings into the final report.

1. Use the report template for the final synthesis. The recommended next step

may route to dispatch-pr-review, a normal implementation workflow, or a retained review-evidence record, but this workflow does not execute that decision.

References

• Specialist review contract:

references/SPECIALIST_REVIEW_CONTRACT.md

• Report template:

references/SPECIALIST_REVIEW_REPORT_TEMPLATE.md

• Specialist prompts:

references/specialists/

• PR decision workflow:

skills/workflows/issue/dispatch-pr-review/SKILL.md

• Review evidence tool:

skills/tools/workflow-evidence/review-evidence/SKILL.md

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: graysurf
• Source: graysurf/agent-kit
• License: MIT

Install and usage instructions live in the source repository linked above.