English | 한국어
Deep Review Plugin
An independent Evaluator plugin for AI coding agents — cross-model code review with Codex integration and Sprint Contract support.
The Problem
AI coding agents have a fundamental blind spot: they review their own work.
- The agent that wrote the code also judges it — self-approval bias is structural
- Opus writes 500 lines and then "reviews" them in the same context window
- Critical bugs, architectural drift, and entropy accumulate undetected
- Without separation between Generator and Evaluator, "review" is just narration
Generator-Evaluator separation is not optional. It's the only way to get an honest second opinion.
The Solution
Deep Review spawns a separate Opus subagent with no knowledge of the original session context. It sees only the diff — not the reasoning, intentions, or assumptions behind the code. This is a structurally independent evaluation.
When Codex is installed, the review escalates to 3-way parallel verification: Claude Opus + codex:review + codex:adversarial-review. Findings are synthesized by confidence level.
Role in Harness Engineering
deep-review is the independent evaluator in the Deep Suite ecosystem, implementing the Generator-Evaluator separation from the Harness Engineering framework.
In the 2×2 matrix:
- Inferential Sensor: Independent Opus subagent review with zero Generator context — the primary quality gate for semantic issues that computational sensors cannot catch
- 3-Way Cross-Model Verification: Opus + Codex standard + Codex adversarial — exceeds the framework's "LLM-as-judge" concept
- Fitness-Aware Review: Consumes
fitness.json rules and health_report from deep-work for architecture-intent-aware evaluation
- Sprint Contract Verification: Structured success criteria checking
Key Commands
| Command | Description |
|---|
/deep-review | Review current changes with an independent Opus subagent |
/deep-review --contract | Sprint Contract-based structural verification |
/deep-review --entropy | Entropy scan (duplicates, pattern drift, naming mismatches) |
/deep-review init | Initialize per-project review rules interactively |
Review Pipeline
Deep Review runs a 4-stage pipeline on every invocation:
Stage 1: Collect — Detect environment, gather diff
Stage 2: Contract — Load Sprint Contract if present
Stage 3: Deep Review — Spawn Opus subagent in background (+ Codex if available)
Stage 4: Verdict — Synthesize findings, emit APPROVE / CONCERN / REQUEST_CHANGES
Stage 1: Collect
Environment detection script determines the git state and collects the appropriate diff:
non-git — ask user which files to reviewinitial (zero commits) — review all files against empty treeclean — git diff {review_base}..HEADstaged — git diff --cachedunstaged — git diffmixed — git diff HEADuntracked-only — git ls-files --others --exclude-standard
Excluded from diff: binaries, vendor/, node_modules/, *.min.js, *.generated.*, *.lock
Stage 2: Contract Check
--contract flag behavior:
--contract SLICE-NNN: Load only .deep-review/contracts/SLICE-NNN.yaml (must be status: active)--contract: Load all status: active contracts in .deep-review/contracts/- No flag: If active contracts exist in
.deep-review/contracts/, they are loaded automatically
status: archived contracts are excluded from auto-loading; if explicitly specified, a warning is shown- YAML parse errors: skip the contract and emit a warning
Each criterion is verified against the actual code changes.
Stage 3: Deep Review
An independent code-reviewer agent is spawned via the Agent tool with model: opus and run_in_background: true. Before spawning, the user is notified which reviewers will run (Opus-only or 3-way). It receives only the diff, rules, and contract — never the originating session context.
The agent evaluates 5 criteria:
| # | Criterion | Checks |
|---|
| 1 | Correctness | Logic bugs, edge cases, error handling |
| 2 | Architecture fit | rules.yaml violations, layer boundaries, dependency direction |
| 3 | Entropy | Duplicate code, pattern drift, ad-hoc helpers |
| 4 | Test coverage | Coverage relative to changes, missing scenarios |
| 5 | Readability | Will the next agent understand this on first read? |
Stage 4: Verdict
| Finding | Verdict |
|---|
| Any 🔴 Critical | REQUEST_CHANGES |
| 🟡 Warnings, all reviewers agree | REQUEST_CHANGES |
| 🟡 Warnings, split opinion | CONCERN |
| All pass | APPROVE |
Report is saved to .deep-review/reports/{YYYY-MM-DD}-review.md.
Cross-Model Verification
