What is River Review

River Review is an OSS framework that runs a team's own review judgment across requirements, design, plan, diff, and report.

This page covers features, usage, and the execution model. The overall concept — the problems, the core model, and the responsibility boundary — is collected in Concept.

A typical AI review tool treats the PR diff as its main input. River Review does not stop there: it also reviews the requirements, design, and plan that come before an AI agent starts implementing, and stays consistent through the diff, tests, and completion report afterwards.

This approach is also called Context Engineering — designing how the context needed for a review judgment is structured and handed to an LLM. By defining team-specific judgment criteria and procedures as version-controlled Agent Skills, it makes review findings reproducible while keeping operating costs in check. River Review is built around three core ideas:

• Capability pack: a bundle of skills / agent definitions that strengthens an AI's review ability.
• Skill Registry: a way to share team judgment criteria as versioned, repo-owned Skills.
• Review agent and review team: a dedicated review agent plus a review team that runs perspective-based reviewers in parallel.

Turning tacit knowledge into versioned, repo-owned Skills as a shared asset stays unchanged. The third axis defines who runs that asset and how.

In one sentence

River Review is a framework for reviewing the flow of development itself, not only the code.

• Requirements: are the purpose, success conditions, and scope clear?
• Design: is it consistent with the existing architecture and constraints?
• Plan: are the work breakdown, risks, and verification policy in place?
• Diff: does the implementation deviate from the requirements, design, or plan?
• Report: does it retain the rationale, verification results, and open items?

Purpose

• Detect drift and risks early in the design phase.
• Standardize review perspectives without stalling implementation reviews.
• Reduce regression and coverage gaps before test/release.

Positioning

River Review does not replace human reviewers. By handling skill-based checks to reduce oversights, it allows humans to focus on intent and team-specific judgments.

Its role also differs from PlanGate: River Review reviews, while PlanGate blocks / passes.

The responsibility split across the four actors — River Review, humans, AI implementation agents, and PlanGate / the caller — is collected in Concept. How human supervision is allocated across the cliff, hill, and field tiers is covered by Human Judgment Focus.

Execution model (who runs the review)

River Review's skills are not configuration for River Review to call an LLM itself — they are a capability pack (skills / agent definitions) that strengthens an AI's review ability. There are three ways they get executed, and whether an LLM key is needed is decided by this model, not by the execution surface.

1. AI-agent-driven (primary) — an agent (Claude Code / Cursor / Codex …) loads the skills (skills/agent-skills/) or the sub-agent (agents/river-review.md) and runs the review with its own model. The agent is the LLM, so no River Review LLM key is needed. This covers /review-local, sub-agent delegation, loading Agent Skills, etc.
2. Mechanical checks (heuristic / no model) — perspectives that can be decided deterministically (e.g. via regex) run with no LLM and no key. Today this covers security perspectives (hardcoded secrets / eval & XSS / disabled TLS / weak hash / command injection / GitHub Actions risks / invisible Unicode injection (GlassWorm and Trojan Source style)) plus quality and test perspectives (silent-catch / leftover debugger / merge-conflict markers / type-check suppression / missing tests / focused & disabled tests / accumulating caller special-cases / closures retaining a large enclosing scope / temporary-fix comments with no exit criteria), handled by nine skills across the security / logging / typescript / test / simplify / knowledge-alignment domains. More mechanically-decidable perspectives can be added over time.
3. Headless LLM (GitHub Action / standalone river run) — with no interactive agent present, River Review calls an LLM itself to execute the skills. Only this path needs an LLM key (ANTHROPIC_API_KEY / OPENAI_API_KEY / GOOGLE_API_KEY); the mechanical checks (2) still run without one.

In short: normal AI-driven development needs no LLM key because the agent applies the skills. A key is required only for headless execution (GitHub Action / standalone CLI) running skills beyond the mechanical checks.

Review agent and review team

River Review does more than bundle skills — it ships a dedicated review agent that runs them. This is a concrete form of the "AI-agent-driven" execution model above.

• Dedicated review agent — shipped as a sub-agent definition (agents/river-review.md) and invoked via /review-local and similar. The host agent loads this definition and runs the review with its own model.
• Parallel perspective reviewers with merge (review team) — src/lib/reviewer-orchestrator.mjs runs perspective-based reviewer roles (bug-hunter / security-scanner / test-gap / dependency-reviewer / frontend-reviewer / ci-cd-reviewer) in parallel, then clusters and merges their findings via connected-components. With --reviewers auto, the roles relevant to the diff are selected automatically.

Here, "multi-agent" means a single orchestrator running perspective-based reviewer roles in parallel and merging the results. It is not a set of fully autonomous, independent agents — it is specifically parallel execution and merge of perspective reviewers.

Iteration loop and decision material critic

River Review serves as the review stage in a generate → review → revise iteration loop.

• On each pass, it returns review results as decision material (findings / verdict / suggestedLoopSignal).
• The verdict is decision material only; it does not assert GO / NO-GO, auto-approval, or auto-merge. Whether to keep iterating or stop is the caller's responsibility.
• Mechanisms such as auto-approve are advisory and do not bypass human-in-the-loop (HITL) review. The cliff still requires human approval, and the field tier's autonomous continuation is not merge authority.

This contract and its reference implementation are defined in the loop convergence contract and the in-repo reference agent (examples/loop-reference-agent/).

Flow Connection

• Upstream: Check requirements, design, and ADRs to reduce downstream risks.
• Midstream: Review code and PRs, ensuring alignment between design intent and implementation diffs.
• Downstream: Check tests, QA, and release readiness to prevent regression and quality degradation.

For details, see Review scope and use cases and Upstream, midstream, downstream.