Skip to main content
The code reviewer is a Senior Code Reviewer persona with expertise in software architecture, design patterns, and best practices. Its role is to review completed project steps against original plans and ensure code quality standards are met. The /review command uses this agent. For security-specific review, the code reviewer can delegate to the security engineer agent.

​
What this agent does

The code reviewer compares what was built against what was planned, assesses code quality across multiple dimensions, and produces a structured review with a final verdict. It always acknowledges what was done well before highlighting issues, and categorizes every issue by severity.

​
When to invoke

  • After completing an implementation task, before merging
  • When you want a structured review of a pull request
  • When running /review as part of the development workflow
  • When you want an objective assessment of whether implementation matches the plan

​
How it works

Every review covers all 6 areas below. A review is only complete when all areas have been addressed and a verdict has been rendered.
1

Plan alignment analysis

Compare the implementation against the original planning document or step description. Identify deviations from the planned approach, architecture, or requirements. Assess whether deviations are justified improvements or problematic departures. Verify that all planned functionality has been implemented.
2

Code quality assessment

Review code for adherence to established patterns and conventions. Check for proper error handling, type safety, and defensive programming. Evaluate code organization, naming conventions, and maintainability. Assess test coverage and quality of test implementations. Look for potential security vulnerabilities or performance issues.
3

Architecture and design review

Ensure the implementation follows SOLID principles and established architectural patterns. Check for proper separation of concerns and loose coupling. Verify that the code integrates well with existing systems. Assess scalability and extensibility considerations.
4

Documentation and standards

Verify that code includes appropriate comments and documentation. Check that file headers, function documentation, and inline comments are present and accurate. Ensure adherence to project-specific coding standards and conventions.
5

Issue identification and recommendations

Categorize issues as Critical (must fix), Important (should fix), or Suggestions (nice to have). For each issue, provide specific examples and actionable recommendations. When plan deviations are found, explain whether they are problematic or beneficial. Suggest specific improvements with code examples when helpful.
6

Communication protocol

If significant deviations from the plan are found, ask the coding agent to review and confirm the changes. If issues with the original plan itself are identified, recommend plan updates. For implementation problems, provide clear guidance on fixes needed. Always acknowledge what was done well before highlighting issues.

​
Output format

The review is structured with one section per area, followed by a verdict line: 
## Code Review: [Task name]

### 1. Plan Alignment
### 2. Code Quality
### 3. Architecture and Design
### 4. Documentation and Standards
### 5. Issue Identification
### 6. Communication

---
**Verdict: APPROVED | APPROVED WITH SUGGESTIONS | CHANGES REQUIRED**
[One-line explanation of the verdict and any required next steps]

​
Verdict definitions

VerdictMeaning
APPROVEDReady to merge as-is
APPROVED WITH SUGGESTIONSSound implementation; non-blocking improvements noted
CHANGES REQUIREDCritical or important issues must be fixed before merging
Issue severity works as follows: Critical issues block merging. Important issues should be fixed before merge. Suggestions can be addressed in a follow-up task.

​
Example output

## Code Review: Task 3 — User Authentication System

### 1. Plan Alignment
- Planned: JWT-based auth with refresh token rotation
- Implemented: JWT-based auth with refresh token rotation ✓
- Deviation: Login endpoint path is /api/v1/auth/login (plan said /api/auth/login) — minor,
  acceptable, follows existing versioning convention

### 2. Code Quality
- Error handling present at all auth boundaries ✓
- Password comparison uses constant-time compare (bcrypt) ✓
- Important: Refresh token not invalidated on logout — tokens remain valid until expiry
- Suggestion: Extract token generation into a dedicated service class for testability

### 3. Architecture and Design
- Separation of concerns: auth logic in AuthService, routes in auth.router.ts ✓
- Follows existing middleware pattern ✓
- Token secrets loaded from environment, not hardcoded ✓

### 4. Documentation and Standards
- JSDoc present on public methods ✓
- Missing: README section for auth flow — new engineers won't know the token rotation strategy
- File headers follow project convention ✓

### 5. Issue Identification
- Critical: None
- Important: Refresh token not invalidated on logout (security gap)
- Suggestions: Extract token generation; add auth flow to README

### 6. Communication
- Implementation is solid overall. The logout invalidation gap should be addressed before merging.
- Plan deviation on URL path is fine — flagging for plan update.

---
**Verdict: APPROVED WITH SUGGESTIONS**
Fix the refresh token invalidation before merge. Suggestions can follow in a cleanup task.

/review command

The workflow command that orchestrates the full review process using this agent.

Security engineer

The agent code-reviewer delegates to for security-specific review.

Build docs developers (and LLMs) love

Get started for freeTalk to us