Agent Cross-Review

Protocol for structured collaboration between specialized agents.

When to Use

• One agent reviewing another's output
• Handoff between feature and expert agents
• Validating cross-cutting concerns
• Resolving conflicting recommendations

Core Principle

Review in domain, defer on scope.

Each agent excels in their specialty. Cross-review catches blind spots without overstepping boundaries.

---

Review Protocol

Step 1: Scope Identification

Before reviewing, identify:

## Cross-Review Context

| Item | Value |
|------|-------|
| Reviewer | {agent-name} |
| Author | {agent-name} |
| Artifact | {file or output} |
| Review Type | Technical / Structural / Integration |

Step 2: Domain Check

Reviewer Type	Review Focus	Defer On
Feature Agent	Structure, naming, coverage	Pytest patterns, DRY
Expert Agent	Code quality, patterns	Project conventions
Architecture	Boundaries, dependencies	Implementation details

Step 3: Calibrated Feedback

Use priority tiers:

### Cross-Review: {artifact}

**CRITICAL** (blocks merge)
- [Issue affecting correctness or security]

**MAJOR** (should fix)
- [Issue affecting maintainability]

**MINOR** (nice to have)
- [Improvement suggestion]

**DEFER** (out of scope for this review)
- [Valid concern but not reviewer's domain]

---

Role-Specific Protocols

feature-interface-cli Reviewing expert-python

Focus Areas:

• Test file naming follows project conventions
• Coverage targets CLI-critical paths
• Integration with existing command structure

Defer To expert-python:

• Fixture design decisions
• pytest marker selection
• Test helper organization

Template:

## CLI Feature Review

### Structure
- [ ] Test files in correct location
- [ ] Naming follows test_{feature}_cmd.py
- [ ] Coverage priorities align with CLI usage

### Concerns for expert-python
- [List items needing pytest expertise]

expert-python Reviewing feature-interface-cli

Focus Areas:

• Type hints complete and correct
• pytest patterns followed
• DRY violations identified

Defer To feature-interface-cli:

• CLI-specific testing approaches
• Typer/Rich patterns
• Project structure decisions

Template:

## Python Quality Review

### Code Quality
- [ ] Type hints present on public functions
- [ ] No mutable default arguments
- [ ] Error handling is specific

### Test Quality
- [ ] Fixtures use appropriate scope
- [ ] No duplicate fixture definitions
- [ ] AAA pattern followed

### Concerns for feature-interface-cli
- [List items needing project context]

---

Handoff Protocol

From Feature Agent to Expert Agent

## Handoff: {feature} implementation

### Completed
- [What's done]

### Needs Review
- [Specific areas needing expert input]

### Context
- [Domain-specific decisions made and why]

### Questions
1. [Specific question for expert]

From Expert Agent to Feature Agent

## Technical Recommendations: {area}

### Recommendations
1. [Recommendation with rationale]

### Priority Assessment
- **Now**: [Must address before merge]
- **Soon**: [Address in follow-up]
- **Later**: [Nice to have]

### Scope Consideration
- [Note if recommendation needs project context validation]

---

Conflict Resolution

When agents disagree:

Priority Framework

Concern Type	Primary Authority
Project conventions	Feature agent
Language patterns	Expert agent
Test structure	Shared (use pytest-fixtures skill)
Architecture	Architecture skill/agent

Resolution Steps

1. State the conflict clearly
2. Identify domain - whose expertise applies?
3. Check project context - what do existing patterns show?
4. Propose compromise - can both concerns be addressed?
5. Escalate if needed - ask user for decision

---

Common Pitfalls

Pitfall	Example	Solution
Scope creep	Expert suggesting CLI changes	Defer with note
Missing context	Recommending unused pattern	Check project first
Priority mismatch	Low priority as critical	Use tier framework
Over-optimization	Refactor working code	Focus on current task

---

Output Format

Quick Review

## Cross-Review Summary

**Artifact**: {file/output}
**Verdict**: Approve / Needs Changes / Discuss

### In My Domain
- [Finding 1]
- [Finding 2]

### Deferred (not my domain)
- [Observation for other agent]

Detailed Review

## Cross-Review: {artifact}

### Context
- Author: {agent}
- Reviewer: {agent}
- Type: {technical/structural}

### Findings

**CRITICAL**
- None / [issues]

**MAJOR**
- [issues]

**MINOR**
- [issues]

### Deferred Items
| Item | Recommended Reviewer | Reason |
|------|---------------------|--------|
| X | expert-python | pytest expertise |
| Y | feature-cli | project conventions |

### Verdict
[Approve / Needs Changes]

Quality Checklist

• Identified review scope before starting
• Focused on domain expertise
• Used priority tiers appropriately
• Deferred out-of-domain concerns
• Provided actionable feedback
• Considered project context