Code Review Agents
Relevant source files
The following files were used as context for generating this wiki page:
Code Review Agents in the Roughly project are specialized subagents designed to evaluate code changes for correctness, security, project convention compliance, and structural integrity. These agents operate within a gated, subagent-per-task architecture, ensuring that every modification is vetted before being finalized. The primary goal of these agents is to prevent context overflow—a common failure mode in long AI sessions—by dispatching fresh, focused processes for specific review tasks.
Sources: README.md:92-95, skills/review/SKILL.md:1-5
Parallel 3-Agent Review Architecture
The core of the Roughly review system is a parallel dispatch of three distinct agents: code-reviewer, static-analysis, and silent-failure-hunter. This "Parallel 3-agent code review" synthesizes findings from different technical dimensions into a single, severity-grouped report.
The following diagram illustrates the dispatch and synthesis flow of the review process:
The review process begins by identifying the scope (e.g., uncommitted changes via git diff), running the agents in parallel, and merging results.
Sources: skills/review/SKILL.md:1-50, README.md:162-170
Agent Specializations
Each agent in the parallel review pipeline has a unique focus and utilizes different tools to accomplish its job.
| Agent | Model | Primary Focus | Key Tools |
|---|---|---|---|
code-reviewer | Sonnet | Logic errors, security, project conventions, and bug detection. | Glob, Grep, Read, Bash |
static-analysis | Sonnet | Type checking, linting, build verification, and dead code detection. | Glob, Grep, Read, Bash |
silent-failure-hunter | Sonnet | Identifying swallowed errors, missing error handling, and domain-specific risks. | Glob, Grep, Read, Bash |
Sources: agents/code-reviewer.md:1-8, agents/static-analysis.md:1-8, agents/silent-failure-hunter.md:1-8, README.md:162-170
Review Processes and Logic
The code-reviewer Logic
This agent focuses on the qualitative aspects of the code. It is instructed to read CLAUDE.md and .roughly/known-pitfalls.md first to understand the specific context and historical issues of the project. Its process involves:
- Checking git context (
git log/git blame) to understand change intent. - Evaluating correctness (null handling, race conditions).
- Scanning for OWASP Top 10 security vulnerabilities.
- Flagging convention violations documented in
CLAUDE.md.
Sources: agents/code-reviewer.md:13-25, skills/review/SKILL.md:21-25
The static-analysis Logic
Unlike the others, this agent relies on the project's actual toolchain. It reads CLAUDE.md to find specific commands for type checking, linting, and building. It is strictly prohibited from speculating; it must run actual commands and report the output.
- Type Check: Executes the project's type check command.
- Lint: Runs the linter if configured.
- Build: Verifies the project builds cleanly.
- Structural Analysis: Detects unused imports or orphaned files in the changed set.
Sources: agents/static-analysis.md:11-19, skills/review/SKILL.md:27-31
The silent-failure-hunter Logic
This agent is specialized in finding "silent" issues that static analysis or standard code reviews might miss. It specifically looks for patterns where errors are swallowed or where domain-specific risk patterns (defined in known-pitfalls.md) are present.
Sources: agents/silent-failure-hunter.md:1-20, skills/review/SKILL.md:33-36
Pre-Implementation Review: epic-reviewer
While the 3-agent pipeline reviews code, the epic-reviewer agent (utilizing the Opus model) reviews specifications before any code is written. This agent performs "cross-story reasoning" to catch issues when they are cheap to fix.
The sequence shows how the epic-reviewer validates the technical feasibility of a plan against the actual codebase.
Sources: agents/epic-reviewer.md:1-15, skills/review-epic/SKILL.md:1-10, ADR-008 in CLAUDE.md:110
AC Mutual Satisfiability
A critical feature of the epic-reviewer is checking "AC Mutual Satisfiability." For each pair of Acceptance Criteria (ACs) that reference overlapping surfaces (the same file, step, or prose region), the agent verifies if they create a structural impossibility. For example, if AC1 requires a modification and AC2 forbids modifications in that same area, the agent flags this as a blocker.
Sources: agents/epic-reviewer.md:26-34
Report Synthesis and Verdicts
Findings from agents are merged into a unified report grouped by severity.
| Severity | Description |
|---|---|
| Critical | Must fix; likely causes bugs or vulnerabilities. |
| Warning | Should fix; anti-patterns or convention violations. |
| Info | Consider; minor improvements or optional suggestions. |
| Clean | Areas that passed all reviews. |
If multiple agents flag the same issue, the orchestrator deduplicates the finding while noting which agents caught it. A final verdict is issued:
- Critical findings: "Review found [N] critical issues. These must be fixed before proceeding."
- Clean: "Review passed clean across all three agents."
Sources: skills/review/SKILL.md:41-71, agents/code-reviewer.md:27-42
Known Pitfalls Integration
After a review, the orchestrator asks if the findings revealed patterns that should be added to .roughly/known-pitfalls.md. If so, the doc-writer agent is dispatched to update project documentation, ensuring future runs benefit from the current discovery.
Sources: skills/review/SKILL.md:58-62, agents/doc-writer.md:1-15
Summary
Code Review Agents in Roughly represent a multi-layered defense strategy. By combining qualitative code review, toolchain-based static analysis, and specialized failure hunting, the system ensures that code changes are correct and adhere to project standards. Furthermore, by utilizing pre-implementation agents like the epic-reviewer, the project prevents structural flaws from entering the development pipeline at the specification stage.