Archery Apprentice Documentation

agent-review-protocol

4 min read

Agent Review Protocol

Version: 1.0 Introduced: PR #352 (Phase 6f) Command: /agent-review

Overview

The Agent Review Protocol enables automated code reviews by Agent 3 (AAA - Analysis/Testing). This slash command initiates a comprehensive code review of a specified PR, posts the review to GitHub, and updates coordination files.

Key Features:

  • Automated PR context gathering
  • 10-point scoring system across 5 criteria
  • GitHub PR review posting via gh pr review
  • Coordination file updates for tracking

Usage

Command Syntax

/agent-review <PR_NUMBER>

Or for current branch:

/agent-review current

Example

/agent-review 352

Review Process

Step 1: Get PR Details

# If argument is "current" or empty
gh pr view --json number,title,url,headRefName,baseRefName,body,files
 
# Otherwise fetch by PR number
gh pr view $PR_NUMBER --json number,title,url,headRefName,baseRefName,body,files

Step 2: Gather Context

# List all changed files
gh pr diff $PR_NUMBER --name-only
 
# Get actual diff for review
gh pr diff $PR_NUMBER

Step 3: Update Coordination File

Updates agent-3-current.md on the agent-coordination branch:

# Agent 3 (AAA) - Analysis/Testing
 
**Status:** ASSIGNED
**Assignment:** Code Review PR #$PR_NUMBER
**Assigned By:** Orchestrator
**Assigned At:** 2025-12-04 12:00 UTC
 
---
 
## Review Assignment
 
**PR:** #$PR_NUMBER - $PR_TITLE
**URL:** $PR_URL
**Branch:** $HEAD_BRANCH -> $BASE_BRANCH
 
### Files to Review
$FILE_LIST
 
### Review Scope
- Code quality and best practices
- Architecture alignment
- Test coverage assessment
- Security considerations
- Platform parity (iOS <-> Android)
- Documentation adequacy

Step 4: Perform Review

The review evaluates code against five criteria, each worth 0-2 points.

Review Criteria

1. Code Quality (0-2 points)

ScoreCriteria
0Major quality issues, unreadable code
1Minor issues, mostly clean
2Clean, readable, follows conventions

Checks:

  • Clean, readable code
  • Proper naming conventions
  • DRY principles followed
  • No unused code or dead paths

2. Architecture (0-2 points)

ScoreCriteria
0Violates established patterns
1Minor deviations, acceptable trade-offs
2Fits patterns perfectly

Checks:

  • Fits existing patterns (MVVM, Repository, etc.)
  • Proper separation of concerns
  • No god classes or methods
  • Appropriate abstraction levels

3. Testing (0-2 points)

ScoreCriteria
0No tests or broken tests
1Some tests, gaps in coverage
2Comprehensive, meaningful tests

Checks:

  • Adequate test coverage
  • Tests are meaningful, not just for coverage
  • Edge cases considered
  • Mocks used appropriately

4. Security (0-2 points)

ScoreCriteria
0Security vulnerabilities present
1Minor concerns, no critical issues
2No security issues, best practices followed

Checks:

  • No hardcoded secrets
  • Input validation
  • Proper auth checks
  • No SQL injection, XSS, etc.

5. Platform Parity (0-2 points)

ScoreCriteria
0Platform inconsistencies
1Minor differences, acceptable
2iOS and Android fully aligned

Checks:

  • iOS and Android aligned
  • Shared KMP code used appropriately
  • No platform-specific hacks
  • Consistent behavior across platforms

Scoring Summary

ScoreVerdict
9-10APPROVED
7-8APPROVED with minor suggestions
5-6CHANGES REQUESTED (non-blocking)
0-4CHANGES REQUESTED (blocking)

Posting Review

Approval

gh pr review $PR_NUMBER --approve --body "## Agent 3 (AAA) Code Review
 
### Overall Score: 9/10
 
#### Code Quality: 2/2
Clean implementation with proper naming...
 
#### Architecture: 2/2
Follows established MVVM pattern...
 
#### Testing: 2/2
Comprehensive test coverage...
 
#### Security: 2/2
No security concerns...
 
#### Platform Parity: 1/2
Minor: Consider aligning constant names...
 
### Verdict: APPROVED
 
---
*Automated review by Agent 3 (AAA) via coordination protocol*"

Comment Only

gh pr review $PR_NUMBER --comment --body "..."

Request Changes

gh pr review $PR_NUMBER --request-changes --body "..."

Coordination Updates

After review, update agent-3-current.md:

**Status:** COMPLETED
**Assignment:** Code Review PR #$PR_NUMBER
**Completed At:** 2025-12-04 12:30 UTC
 
## Review Summary
- **Score:** 9/10
- **Verdict:** APPROVED
- **Key Findings:** Clean implementation, good test coverage, minor parity suggestion

Example Output

## Agent 3 Review Assignment

PR #352 - feat: iOS Tournament Guest Archers
https://github.com/user/repo/pull/352

### Files Under Review
- AddGuestSheet.swift (+199 lines)
- TournamentScoringViewModel.swift (+180 lines)
- TournamentScoringView.swift (+25 lines)
- TournamentScoringViewModelTests.swift (+159 lines)

### Review Posted

**Score: 9/10**
**Verdict: APPROVED**

Key findings:
- Clean implementation matching Android patterns
- Good error handling with GuestError enum
- Test coverage for new functionality
- Minor: Could add integration tests for Firebase writes

View review: https://github.com/user/repo/pull/352#pullrequestreview-XXXXX

Last Updated: 2025-12-04

Graph View

Backlinks