Autoreview

Auto Review

Run an independent review when the user or an owning workflow asks for one. This is code review, not Guardian approval routing. Let the reviewer choose how to analyze the change; provide the target, relevant context, and desired severity. Findings are advice to verify, not instructions to apply blindly.

Before starting a review, read the complete diagnostic and result guidance. It is part of this skill; follow its output-path, status, failure, usage, and diagnostic rules.

Run

Use scripts/autoreview beside this skill. Keep its custom codex exec path: native codex review cannot combine explicit Git target flags with custom instructions. The helper combines those with evidence, severity filtering, and validated JSON; it leaves review judgment to Codex. Install this skill once with the canonical repository's python3 scripts/install-skills autoreview. The default installation at ~/.agents/skills/autoreview links to this source checkout.

Run from the repository being reviewed:

AUTOREVIEW="$HOME/.agents/skills/autoreview/scripts/autoreview"
python3 "$AUTOREVIEW" --mode local

In the canonical agent-skills repo, the path is skills/autoreview/scripts/autoreview. Use the selected installation path when installed with --target. On Windows, invoke the helper with Python 3.10 or newer, or use the adjacent autoreview.ps1 launcher. Use --help for the complete flags and environment overrides.

Repositories keep only the shared-skill entrypoint. Read this full skill and its required references from the shared installation. Keep repository-specific thresholds and review requirements in the consumer's instructions. Upstream changes to shared behavior here.

Update the canonical checkout once to update every symlinked consumer. Finish active reviews before updating their helper. Copy-mode installations require re-running scripts/install-skills --mode copy --force autoreview after updating the source checkout. Review commands never download or update themselves.

Choose the Git target explicitly when the default is ambiguous:

--mode auto selects local work when dirty, otherwise a branch review using the PR base or origin/main. Clean main has no implicit review target. --mode uncommitted is an alias for local. The helper does not fetch refs.

Registered nested linked checkouts from the same repository are outside the current review scope. Their presence or edits do not make the parent dirty; ordinary adjacent files remain included in the review. Worktree boundaries are revalidated without changing Git ignore rules.

For a complete PR candidate including dirty rewrites, use local mode with its pinned merge base—not branch mode:

pr_base=$(gh pr view --json baseRefName --jq .baseRefName)
merge_base=$(git merge-base HEAD "origin/$pr_base")
"$AUTOREVIEW" --mode local --base "$merge_base"

When a file has both staged and unstaged changes, both states are reviewed. A defect in the index remains actionable even if the working tree fixes it; the report labels it INDEX-only. Git display settings cannot suppress context markers or add patch colors; repository configuration is not changed. Source paths and text retain literal whitespace. An empty present source uses line 1, column 1, and an empty excerpt; empty physical lines also use an empty excerpt at column 1. Source identity remains mandatory.

Binary deletions remain in scope as Git deletion metadata; their former contents are not included or reviewed. Each local transition is checked independently: deleting a file in the working tree cannot hide a staged binary change.

Finding locations may use native absolute paths that resolve inside the reviewed repository; these become repository-relative paths before scope and attribution checks, preserving a changed symlink's path when its target is also inside. Parent traversal and paths resolving outside the repository remain invalid. An invalid location still fails the report; findings are never silently dropped.

Local selection honors core.autocrlf from external operator Git configuration, with repository-local values and attributes retaining precedence. Only its validated scalar value reaches diff/status; other global and system Git configuration stays disabled. Repository-owned or relative global-config overrides are not imported, and reviewed source bytes are not rewritten.

Local collection disables effective Git clean/process commands and requires conversion to succeed. Unused drivers, unchanged filtered neighbors, staged-only changes, and deletions can still be reviewed without executing converters. If Git needs executable conversion to assemble the diff, collection fails before any reviewer starts. This can include an unchanged filtered file whose stat cache needs refreshing. Use explicit branch or commit mode for committed content in that case. Built-in line-ending normalization remains enabled; raw bytes never stand in for a required executable conversion. PR-base discovery uses trusted external Git and a scoped GitHub CLI environment, preserving external authentication/configuration and proxy settings while excluding inherited Git routing, GH_REPO redirection, and checkout-owned executables. A differently named AUTOREVIEW_GIT override that cannot also be selected as git by the child requires an explicit --base; rejected GitHub configuration paths also require one.

Context and severity

Use --prompt for task-specific guidance, or --prompt-file and --dataset for repository-relative context files. Context does not expand the selected Git target. The reviewer cannot read unchanged repository files from its empty sandbox; supply relevant source or dependency evidence when the diff is insufficient. --prompt-file also accepts an absolute path inside the repository; the same sensitive-path, symlink, and mutation checks apply. --dataset stays repo-relative. Repeated paths in the same evidence role share one validated capture. Equal content at different paths and prompt-file versus dataset roles stay distinct.

For unchanged committed source, use repeatable --source-context <repo-relative-path> with branch or commit mode. Use --source-context-file <repo-relative-path> when that source must stay intact in every review pass. Both read the exact regular-file blob from the frozen reviewed commit (branch HEAD or --commit), including executable source files. Local mode, including an auto-selected local target, is unsupported. No separate context revision or working-copy substitution is accepted. The checkout path must remain a regular file; its bytes and path topology are revalidated throughout review. Repeated normalized source-context paths share one capture after every argument is validated; different paths and evidence roles remain distinct.

Both roles use tracked-source filename classification, so source names such as src/token_count.py are accepted. Credential directories, stores and keyfiles remain forbidden. Existing prompt-file and dataset restrictions are unchanged. Every source block carries path, commit, blob and mode provenance. --source-context bytes are partitioned with the change when needed. --source-context-file blocks stay complete in every pass and must fit with the instructions and change framing; the helper refuses an over-capacity plan without dropping required evidence. Context never adds finding targets or instruction authority. This is a source-provenance contract, not secret-content scanning.

"$AUTOREVIEW" --mode branch --base origin/main --source-context src/token_count.py
"$AUTOREVIEW" --mode branch --base origin/main --source-context-file src/token_count.py

The default threshold is P0 only: material blockers to normal operation or safety. Use --max-priority P1, P2, or P3 when the caller requests a wider review. AUTOREVIEW_MAX_PRIORITY accepts the same P0–P3 values; an explicit flag overrides it. Invalid resolved priorities fail during argument parsing, before preparation or reviewer startup. Do not add unrelated redesign goals or prescribe file counts, reading sequences, or ritual extra passes. Historical blame requires a verified parent-relative patch; otherwise leave the attribution unknown.

"$AUTOREVIEW" --mode local --prompt-file review-notes.md --dataset evidence.json

Engines

For automatic reviewer selection, try OpenAI models through Codex before Claude. Start with --engine codex even when the invoking agent uses Codex or asks for an independent second opinion. Use Claude only when the user explicitly selects it or Codex is unavailable for the review; report the concrete availability failure before switching. Do not switch because a review is slow, rate-limited, or returns findings, or to bypass a safety refusal or isolation failure.

Codex defaults to gpt-6.1-sol, high reasoning, with a single gpt-6-sol retry only for an account-access failure. Explicit gpt-6.1-sol selections use the same retry. Explicit gpt-6-sol selections retain their access-only gpt-6-luna retry; other explicit models, including Luna and Astra, have no model fallback. Explicit gpt-5.6-sol selections retain their access-only gpt-5.6-terra retry. GPT-6.1 Sol rejects none and minimal effort before review preparation; GPT-6 Sol and Luna reject minimal. An effort-only override keeps the default model. Honor explicit user engine/model choices. The helper does not automatically fall back between engines.

Use --engine, --model, and --thinking to override the defaults. --codex-speed fast selects priority service when supported; --codex-speed ultrafast selects Ultrafast when the active model catalog lists it (Codex otherwise silently sends the standard tier). Only Claude accepts --fallback-model. Per-engine environment overrides use AUTOREVIEW_<ENGINE>_*.

If your account cannot access Sol or Luna, pin an available model. To require GPT-6 Astra without a model fallback, select it explicitly:

"$AUTOREVIEW" --mode local --model gpt-6-astra --thinking high

GPT-6.1 Sol and GPT-6 Astra support low, medium, high, xhigh, and max; neither supports none or minimal. GPT-6 Sol and Luna additionally support none, but not minimal. AutoReview defaults to high and does not fall back from an explicit Luna or Astra selection. Codex's ultra mode uses automatic delegation and is outside this helper's supported effort levels. Use max for its deepest supported review. For EU data residency, use --codex-speed default; GPT-6 fast mode is unavailable there. See the GPT-6.1 Sol, GPT-6 Sol, and GPT-6 Luna model docs and Codex reasoning modes.

By default, Codex preserves only authentication settings from user configuration; provider, profile, context and catalogue settings remain ignored. To project a named route, select it explicitly through the existing config override:

"$AUTOREVIEW" --mode local --codex-config 'model_provider="review_api"'

The selector must match model_provider in the operator's external CODEX_HOME/config.toml. It accepts one bare or simply quoted identifier; provider definitions and other capabilities cannot be supplied through overrides. Projection requires Python 3.11 or tomli; default auth-only operation retains its existing fallback parser.

The selected route must use https://api.openai.com/v1 and command authentication with an absolute external executable. Fixed arguments belong in that executable's wrapper; omitted or empty auth.args are accepted. Omitted wire_api and requires_openai_auth retain Codex's responses and false defaults. Optional auth timing and context settings keep native defaults and semantics.

On POSIX, a private launcher restores the validated caller HOME only for the selected authentication executable; the engine and reviewer tools retain their isolated environment and filesystem access. Caller HOME must be an available absolute directory with no repository-owned path or symlink provenance. Windows keeps the native executable route. Command-auth runs suppress raw provider diagnostics and report fixed failure categories, while retaining compact progress, usage and assistant report streaming. An empty final report fails without exposing captured stdout.

Catalogue and authentication working-directory paths resolve relative to the operator config directory and must remain outside the reviewed repository. A supplied catalogue is copied byte-for-byte into the private client runtime; retries use the same route and catalogue snapshot. Dry runs check the same ownership and route shape without executing authentication. Codex owns catalogue validation, model access and context clamping. Other custom provider forms and split context overrides are unsupported when projection is selected.

--engine kimi remains recognized but is refused for reviews and --dry-run before any Kimi process, configuration read or authentication setup. The supported Kimi Code prompt mode accepts review content only as a command-line argument; the helper has no supported private prompt input channel for it. This intentionally retires the previous Kimi execution path rather than exposing the bundle in process arguments. Existing --kimi-bin arguments remain accepted for the same clear refusal; the helper never silently selects another engine. A custom agent file is not an equivalent replacement because it changes the input into a templated system prompt.