Autoreview

Auto Review

Run the bundled structured review helper as a closeout check. This is code review, not Guardian auto_review approval routing.

Codex review is the default when no engine is set. It uses gpt-5.6-sol with high reasoning by default, then retries once with gpt-5.6-terra only when the account cannot access Sol. Claude review is optional and uses claude-fable-5 by default.

For user-visible behavior, pair autoreview with behavior-validator. Autoreview is source-aware and judges the change bundle; behavior validation is source-blind and judges the running product or tool against a behavior contract. A clean autoreview is not proof that a UI, CLI, API, or generated artifact works from the user's perspective.

Use when:

• user asks for Codex review / Claude review / Pi review / autoreview / second-model review
• after non-trivial code edits, before final/commit/ship
• reviewing a local branch or PR branch after fixes

Do not require autoreview for a change whose entire diff is prose-only internal notes or SKILL.md documentation. Still inspect the diff directly and run the repository's lightweight documentation validation, if any. This exception does not cover user-facing documentation, executable examples, configuration, scripts, generated files, or behavior changes.

Contract

• Treat review output as advisory. Never blindly apply it.
• Verify every finding by reading the real code path and adjacent files.
• Read dependency docs/source/types when the finding depends on external behavior.
• Reject unrealistic edge cases, speculative risks, broad rewrites, and fixes that over-complicate the codebase.
• Prefer small fixes at the right ownership boundary; no refactor unless it clearly improves the bug class.
• When an accepted finding shows a bug class or repeated pattern, inspect the current PR scope for sibling instances before fixing.
• Fix the scoped bug class at once when practical; stop at touched surfaces, owner boundaries, and clear follow-up territory.
• Keep going until structured review returns no accepted/actionable findings only while the work remains inside the original task scope.
• If a review-triggered fix changes code, rerun focused tests and rerun the structured review helper.
• For security-audit suppression changes, verify accepted findings remain auditable: suppressed findings stay in structured output, active output keeps an unsuppressible suppression notice, and aggregate findings cannot hide unrelated active risk.
• Never switch or override the requested review engine/model except for the documented Codex Sol-to-Terra account-access fallback. Capacity, rate-limit, and unrelated failures keep the same engine/model.
• Be patient with large bundles. Structured review can take up to 30 minutes while the model call is active, especially with Codex tools or web search.
• Treat heartbeat lines like review still running: ... elapsed=... pid=... as healthy progress, not a hang. Let the helper continue while heartbeats are advancing. Pass --stream-engine-output when live engine text is useful; Codex and Claude filter tool/file chatter, other runnable engines pass raw output through.
• Do not kill a review just because it has been quiet for 2-5 minutes, or because it is still running under the 30-minute window. Inspect the process only after missing multiple expected heartbeats, after 30 minutes, or after an obviously failed subprocess; prefer letting the same helper command finish.
• Tools are useful in review mode. Codex receives the validated bundle in an empty workspace so ignored files and linked-worktree metadata remain unreadable; web search stays available for dependency contracts and upstream docs.
• Security perspective is always included, but it should not cripple legitimate functionality. Report security findings only when the change creates a concrete, actionable risk or removes an important safety check.
• Reviewer subprocesses preserve engine authentication and non-credentialed proxy variables needed by headless or restricted-network environments while stripping process-injection, Git override, and credentialed proxy values.
• Before engine invocation, autoreview runs TruffleHog over temporary snapshots of the exact added or modified content under review. It intentionally matches TruffleHog's low-false-positive pre-commit policy (verified,unknown); it does not classify arbitrary password-like strings or rescan unchanged history. Install TruffleHog using its official platform-neutral instructions; autoreview fails with that link when the binary is unavailable and never auto-installs it. Repositories should also run TruffleHog in pull-request CI as a backup outside autoreview; repository-local Git hooks are optional. Review bundles still omit security-sensitive paths or files, and explicit prompt and dataset inputs remain checked before engine invocation. Safe large diffs are sent as one pass while they fit the aggregate prompt limit, then partitioned into complete bounded passes without truncation.
• For regression provenance, keep roles separate: blamed code author, blamed PR author, PR merger/committer, current PR author, and PR/date. If no blamed PR is traceable, use the blamed commit as the provenance: commit SHA, date, and author username. Do not guess a merger or frame missing PR metadata as a separate finding.
• If the blamed PR was merged by clawsweeper[bot] or another automation, identify the human trigger when practical. Check timeline/comments first; if rate-limited, use gitcrawl/cache or public PR HTML. Look for maintainer commands such as @clawsweeper automerge, /landpr, or labels/status comments that armed automerge. Report automerge triggered by @login; if not found, say trigger unknown.
• Do not invoke built-in codex review, nested reviewers, or reviewer panels from inside the review. The helper builds one validated bundle, calls the selected engine once for normal inputs or once per complete bounded chunk for oversized inputs, validates the structured results, and stops.
• Stop as soon as the helper exits 0 with no accepted/actionable findings. Do not run an extra review just to get a nicer "clean" line, a second opinion, or clearer closeout wording.
• Treat the helper's successful exit plus absence of actionable findings as the clean review result, even if the underlying Codex CLI output is terse.
• Multi-reviewer panels are opt-in only. Use them when explicitly requested or when risk justifies the extra spend; the main agent still verifies every accepted finding before fixing.
• If rejecting a finding as intentional/not worth fixing, add a brief inline code comment only when it explains a real invariant or ownership decision that future reviewers should know.
• If gh/Gitcrawl reports database disk image is malformed, run gitcrawl doctor --json once to let the portable cache repair before retrying review; do not bypass the shim unless repair fails and freshness requires live GitHub.
• If Gitcrawl reports a portable manifest mismatch, source/runtime DB health error, or stale portable-store checkout, run gitcrawl doctor --json and inspect source_db_health, runtime_db_health, and portable_store_status before falling back to live GitHub.
• Do not push just to review. Push only when the user requested push/ship/PR update.

Scope Governor

Autoreview is a closeout gate, not permission to rewrite the task.

Before the first review, freeze a scope baseline: original request or issue, target branch, intended behavior, owner boundary, changed files, and non-test LOC. For inherited or already-bloated branches, use the intended PR diff as the baseline rather than accepting all existing branch drift.

Before patching a finding, classify it:

• In-scope blocker: the finding is introduced by the current diff, affects the same owner boundary, and can be fixed without changing the task's contract.
• Follow-up: the finding is real but belongs to an adjacent bug class, sibling surface, cleanup, or broader hardening track.
• Stop-and-escalate: the finding requires a new protocol/config/storage/public API contract, a different owner boundary, a release-process change, or a design choice outside the original request.

Stop patching and report the scope break instead of continuing when:

• a narrow PR turns into an architecture change, protocol change, migration, or release-process change;
• the diff grows past 2x the original files or non-test LOC without explicit approval to expand scope;
• two review-triggered patch cycles have not converged; pause and reclassify every remaining finding before another edit;
• the best fix is "define the canonical contract first" rather than another local inference layer;
• fixing the accepted finding would make the PR no longer describe the same behavior, issue, or owner boundary.

After the two-cycle pause, continue only when every remaining accepted finding is still an in-scope blocker. Otherwise preserve the useful analysis, identify the smallest safe landed subset if one exists, and open or request a follow-up for the larger fix. Do not keep committing speculative fixes just to satisfy the reviewer.

Do not stack or push review-triggered fix commits while scope classification or focused proof is unresolved. Keep exploratory edits local until the cycle is proven in scope; if scope breaks, remove them from the landing lane instead of preserving them as branch history.

Critical exceptions must be explicit: active data loss, crash, broken install/upgrade, release blocker, or concrete security exposure. If the exception is not one of those, it is not critical enough to blow up scope.

Release Branches And Release Process

On release, beta, stable, hotfix, signing, notarization, appcast, package-publish, or release-check work, use freeze discipline even when the branch name is not release-like:

• Fix only release blockers, failed release infrastructure, exact backports, install/upgrade breakage, data loss, crashes, or concrete security exposure.
• Treat non-blocking autoreview findings as follow-ups for main, not reasons to broaden the release branch.
• Do not introduce new product behavior, config surface, protocol shape, migration, plugin ownership, docs narrative, or process policy unless it directly unblocks the release.
• Keep proof tied to the release target: exact branch/ref, failing check or shipped-risk reason, smallest command/proof, and whether the fix must also forward-port to main.
• If review discovers a real but non-critical design problem during release closeout, stop with a follow-up issue/PR plan; do not use the release branch as the refactor lane.

Skill Path (set once)

Set the skill script paths once, then use "$AUTOREVIEW" and "$AUTOREVIEW_HARNESS" in the examples below.

Choose one:

# Project-local skill in the current repo for Codex and other agents:
export AUTOREVIEW=".agents/skills/autoreview/scripts/autoreview"
export AUTOREVIEW_HARNESS=".agents/skills/autoreview/scripts/test-review-harness"

# Claude Code project-local skill in the current repo:
export AUTOREVIEW=".claude/skills/autoreview/scripts/autoreview"
export AUTOREVIEW_HARNESS=".claude/skills/autoreview/scripts/test-review-harness"

# Source checkout of openclaw/agent-skills:
export AUTOREVIEW="skills/autoreview/scripts/autoreview"
export AUTOREVIEW_HARNESS="skills/autoreview/scripts/test-review-harness"

# Global skill:
export AGENTS_HOME="${AGENTS_HOME:-$HOME/.agents}"
export AUTOREVIEW="$AGENTS_HOME/skills/autoreview/scripts/autoreview"
export AUTOREVIEW_HARNESS="$AGENTS_HOME/skills/autoreview/scripts/test-review-harness"

When using Claude Code, set AGENTS_HOME="$HOME/.claude" for global skills.

On native Windows, choose the matching pair:

# Project-local skill in the current repo for Codex and other agents:
$AUTOREVIEW = ".agents\skills\autoreview\scripts\autoreview"
$AUTOREVIEW_HARNESS = ".agents\skills\autoreview\scripts\test-review-harness.ps1"

# Claude Code project-local skill in the current repo:
$AUTOREVIEW = ".claude\skills\autoreview\scripts\autoreview"
$AUTOREVIEW_HARNESS = ".claude\skills\autoreview\scripts\test-review-harness.ps1"

# Source checkout of openclaw/agent-skills:
$AUTOREVIEW = "skills\autoreview\scripts\autoreview"
$AUTOREVIEW_HARNESS = "skills\autoreview\scripts\test-review-harness.ps1"

# Global skill:
$AgentsHome = if ($env:AGENTS_HOME) { $env:AGENTS_HOME } else { Join-Path $HOME ".agents" }
$AUTOREVIEW = Join-Path $AgentsHome "skills\autoreview\scripts\autoreview"
$AUTOREVIEW_HARNESS = Join-Path $AgentsHome "skills\autoreview\scripts\test-review-harness.ps1"

Pick Target

Dirty local work:

"$AUTOREVIEW" --mode local

Use this only when the patch is actually unstaged/staged/untracked in the current checkout. --mode uncommitted is accepted as an alias for --mode local. For committed, pushed, or PR work, point the helper at the commit or branch diff instead; do not force dirty modes just because the helper docs mention dirty work first. A clean local review only proves there is no local patch.

Branch/PR work:

"$AUTOREVIEW" --mode branch --base origin/main

Optional review context is first-class. Prompt files and datasets must be repo-relative so review bundles cannot pull arbitrary host files:

"$AUTOREVIEW" --mode branch --base origin/main --prompt-file review-notes.md --dataset evidence.json

If an open PR exists, use its actual base:

base=$(gh pr view --json baseRefName --jq .baseRefName)
"$AUTOREVIEW" --mode branch --base "origin/$base"

Committed single change:

"$AUTOREVIEW" --mode commit --commit HEAD

Use commit review for already-landed or already-pushed work on main. Reviewing clean main against origin/main is usually an empty diff after push. For a small stack, review each commit explicitly or review the branch before merging with --base.

Oversized Bundles

The helper scans the full patch before partitioning it. A safe bundle that fits the aggregate prompt limit remains one integrated review pass. Larger bundles are split at bundle sections and file boundaries where possible; an oversized single-file block is split at line boundaries with repeated file/hunk context and an absolute new- or old-file line offset. Untracked snapshots use injection-safe source-line records so continuation passes retain reportable locations. A single physical diff line split across passes also retains its original addition, deletion, or context marker. Every original bundle byte appears exactly once across the pass sequence, and all validated reports are merged before required-finding and exit-status checks. The helper caps one run at eight bounded passes so an unexpectedly huge branch cannot create unbounded model calls; split still-larger work into coherent review targets.

Chunking makes large-diff review usable, but it cannot give one model call every cross-file implementation detail. For architecture-heavy changes, still prefer a coherent branch or PR shape whose semantic decision surface fits one pass. Removing verified non-authoritative generated noise remains useful, but never drop lockfiles, generated clients, policies, manifests, schemas, or other independently semantic artifacts merely to shrink the review.

Parallel Closeout

Format first if formatting can change line locations. Then it is OK to run tests and review in parallel:

"$AUTOREVIEW" --parallel-tests ""

On Windows, the default --parallel-tests shell preserves the platform cmd.exe semantics used by Python shell=True. Use --parallel-tests-shell powershell or --parallel-tests-shell pwsh when the focused test command is PowerShell-specific. Parallel tests inherit only a small allowlist of ordinary OS, CI, and toolchain variables. Put additional non-secre

…

Source & license

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

• Author: openclaw
• Source: openclaw/crabbox
• License: MIT
• Homepage: http://crabbox.sh

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