gh-jeanluciano-quaestor-src-quaestor/skills/reviewing-and-shipping/AGENTS.md

# Multi-Agent Review Strategies

This file describes how to coordinate multiple specialized agents for comprehensive code review and quality assurance.

## Agent Overview

### Available Agents for Review

```yaml
workflow-coordinator:
  role: "Pre-review validation and workflow state management"
  use_first: true
  validates:
    - Implementation phase completed
    - All specification tasks done
    - Tests passing before review
    - Ready for review/completion phase
  coordinates: "Transition from implementation to review"
  criticality: MANDATORY

refactorer:
  role: "Code quality and style review"
  specializes:
    - Code readability and clarity
    - SOLID principles compliance
    - Design pattern usage
    - Code smell detection
    - Complexity reduction
  focus: "Making code maintainable and clean"

security:
  role: "Security vulnerability review"
  specializes:
    - Authentication/authorization review
    - Input validation checking
    - Vulnerability scanning
    - Encryption implementation
    - Security best practices
  focus: "Making code secure"

qa:
  role: "Test quality and coverage review"
  specializes:
    - Test coverage analysis
    - Test quality assessment
    - Edge case identification
    - Mock appropriateness
    - Performance testing
  focus: "Making code well-tested"

implementer:
  role: "Documentation and feature completeness"
  specializes:
    - Documentation completeness
    - API documentation review
    - Code comment quality
    - Example code validation
    - Feature implementation gaps
  focus: "Making code documented and complete"

architect:
  role: "Architecture and design review"
  specializes:
    - Component boundary validation
    - Dependency direction checking
    - Abstraction level assessment
    - Scalability evaluation
    - Design pattern application
  focus: "Making code architecturally sound"
  when_needed: "Major changes, new components, refactoring"
```

---

## Agent Selection Rules

### MANDATORY: Workflow Coordinator First

**Always Start with workflow-coordinator:**

```yaml
Pre-Review Protocol:
  1. ALWAYS use workflow-coordinator agent first
  2. workflow-coordinator validates:
     - Implementation phase is complete
     - All tasks in specification are done
     - Tests are passing
     - No blocking issues remain
  3. If validation fails:
     - Do NOT proceed to review
     - Report incomplete work to user
     - Guide user to complete implementation
  4. If validation passes:
     - Proceed to multi-agent review

NEVER skip workflow-coordinator validation!
```

### Task-Based Agent Selection

**Use this matrix to determine which agents to invoke:**

```yaml
Authentication/Authorization Feature:
  agents:
    - security: Security requirements and review (primary)
    - refactorer: Code quality and structure
    - qa: Security and integration testing
    - implementer: Documentation completeness
  reason: Security-critical feature needs security focus

API Development:
  agents:
    - refactorer: Code structure and patterns (primary)
    - implementer: API documentation
    - qa: API testing and validation
  reason: API quality and documentation critical

Performance Optimization:
  agents:
    - refactorer: Code efficiency review (primary)
    - qa: Performance testing validation
    - architect: Architecture implications (if major)
  reason: Performance changes need quality + testing

Security Fix:
  agents:
    - security: Security fix validation (primary)
    - qa: Security test coverage
    - implementer: Security documentation
  reason: Security fixes need security expert review

Refactoring:
  agents:
    - refactorer: Code quality improvements (primary)
    - architect: Design pattern compliance (if structural)
    - qa: No regression validation
  reason: Refactoring needs quality focus + safety

Bug Fix:
  agents:
    - refactorer: Code quality of fix (primary)
    - qa: Regression test addition
  reason: Simple bug fixes need basic review

Documentation Update:
  agents:
    - implementer: Documentation quality (primary)
  reason: Documentation changes need content review only

New Feature (Standard):
  agents:
    - refactorer: Code quality and structure
    - security: Security implications
    - qa: Test coverage and quality
    - implementer: Documentation completeness
  reason: Standard features need comprehensive review

Major System Change:
  agents:
    - architect: Architecture validation (primary)
    - refactorer: Code quality review
    - security: Security implications
    - qa: Comprehensive testing
    - implementer: Documentation update
  reason: Major changes need all-hands review
```

---

## Agent Coordination Patterns

### Pattern 1: Parallel Review (Standard)

**When to Use:** Most feature reviews where agents can work independently.

```yaml
Parallel Review Pattern:
  Spawn 4 agents simultaneously:
    - refactorer: Review code quality
    - security: Review security
    - qa: Review testing
    - implementer: Review documentation

  Each agent focuses on their domain independently

  Wait for all agents to complete

  Consolidate results into unified review summary

Advantages:
  - Fast (all reviews happen simultaneously)
  - Comprehensive (all domains covered)
  - Independent (no agent blocking others)

Time: ~5-10 minutes
```

**Example: New Feature Review**

```yaml
Review Authentication Feature:

Spawn in Parallel:
  Use the refactorer agent to:
    - Review code structure and organization
    - Check SOLID principles compliance
    - Identify code smells
    - Suggest improvements

  Use the security agent to:
    - Review authentication logic
    - Check password hashing
    - Validate token handling
    - Identify security risks

  Use the qa agent to:
    - Analyze test coverage
    - Check edge case handling
    - Validate test quality
    - Identify missing tests

  Use the implementer agent to:
    - Review API documentation
    - Check code comments
    - Validate examples
    - Identify doc gaps

Wait for All Completions

Consolidate:
  - Combine all agent findings
  - Identify common themes
  - Prioritize issues
  - Generate unified review summary
```

### Pattern 2: Sequential Review with Validation

**When to Use:** Critical features where one review informs the next.

```yaml
Sequential Review Pattern:
  Step 1: First agent reviews
    → Wait for completion
    → Analyze findings

  Step 2: Second agent reviews (builds on first)
    → Wait for completion
    → Analyze findings

  Step 3: Third agent reviews (builds on previous)
    → Wait for completion
    → Final analysis

Advantages:
  - Each review informs the next
  - Can adjust focus based on findings
  - Deeper analysis possible

Time: ~15-20 minutes
```

**Example: Security-Critical Feature Review**

```yaml
Review Security Feature:

Step 1: Use the security agent to:
  - Deep security analysis
  - Identify vulnerabilities
  - Define security requirements
  - Assess risk level

  Output: Security requirements document + vulnerability report

Step 2: Use the refactorer agent to:
  - Review code with security context
  - Check if vulnerabilities addressed
  - Ensure secure coding patterns
  - Validate security requirements met

  Context: Security agent's findings
  Output: Code quality + security compliance report

Step 3: Use the qa agent to:
  - Review tests with security focus
  - Ensure vulnerabilities tested
  - Check security edge cases
  - Validate security test coverage

  Context: Security requirements + code review
  Output: Test coverage + security testing report

Step 4: Use the implementer agent to:
  - Document security implementation
  - Document security tests
  - Add security examples
  - Document threat model

  Context: All previous reviews
  Output: Documentation completeness report
```

### Pattern 3: Iterative Review with Fixing

**When to Use:** When issues are expected and fixes needed during review.

```yaml
Iterative Review Pattern:
  Loop:
    1. Agent reviews and identifies issues
    2. Same agent (or another) fixes issues
    3. Re-validate fixed issues
    4. If new issues: repeat
    5. If clean: proceed to next agent

Advantages:
  - Issues fixed during review
  - Continuous improvement
  - Final review is clean

Time: ~20-30 minutes (depends on issues)
```

**Example: Refactoring Review with Fixes**

```yaml
Review Refactored Code:

Iteration 1 - Code Quality:
  Use the refactorer agent to:
    - Review code structure
    - Identify 3 issues:
      • Function too long (85 lines)
      • Duplicate code in 2 places
      • Complex nested conditionals

  Use the refactorer agent to:
    - Break long function into 4 smaller ones
    - Extract duplicate code to shared utility
    - Flatten nested conditionals

  Validate: All issues fixed ✅

Iteration 2 - Testing:
  Use the qa agent to:
    - Review test coverage
    - Identify 2 issues:
      • New functions not tested
      • Edge case missing

  Use the qa agent to:
    - Add tests for new functions
    - Add edge case test

  Validate: Coverage now 89% ✅

Iteration 3 - Documentation:
  Use the implementer agent to:
    - Review documentation
    - Identify 1 issue:
      • Refactored functions missing docstrings

  Use the implementer agent to:
    - Add docstrings to all new functions
    - Update examples

  Validate: All documented ✅

Final: All issues addressed, ready to ship
```

### Pattern 4: Focused Review (Subset)

**When to Use:** Small changes or specific review needs.

```yaml
Focused Review Pattern:
  Select 1-2 agents based on change type:
    - Bug fix → refactorer + qa
    - Docs update → implementer only
    - Security fix → security + qa
    - Performance → refactorer + qa

  Only review relevant aspects

  Skip unnecessary reviews

Advantages:
  - Fast (minimal agents)
  - Focused (relevant only)
  - Efficient (no wasted effort)

Time: ~3-5 minutes
```

**Example: Bug Fix Review**

```yaml
Review Bug Fix:

Use the refactorer agent to:
  - Review fix code quality
  - Check if fix is clean
  - Ensure no new issues introduced
  - Validate fix approach

Use the qa agent to:
  - Verify regression test added
  - Check test quality
  - Ensure bug scenario covered
  - Validate no other tests broken

Skip:
  - security (not security-related)
  - implementer (no doc changes)
  - architect (no design changes)

Result: Fast, focused review in ~5 minutes
```

---

## Review Aspect Coordination

### Code Quality Review (refactorer)

**Review Focus:**

```yaml
Readability:
  - Variable/function names clear
  - Code organization logical
  - Comments appropriate
  - Formatting consistent

Design:
  - DRY principle applied
  - SOLID principles followed
  - Abstractions appropriate
  - Patterns used correctly

Maintainability:
  - Functions focused and small
  - Complexity low
  - Dependencies minimal
  - No code smells

Consistency:
  - Follows codebase conventions
  - Naming patterns consistent
  - Error handling uniform
  - Style guide compliance
```

**Review Output Format:**

```yaml
Code Quality Review by refactorer:

✅ Strengths:
  • Clean separation of concerns in auth module
  • Consistent error handling with custom exceptions
  • Good use of dependency injection pattern
  • Function sizes appropriate (avg 25 lines)

⚠️ Suggestions:
  • Consider extracting UserValidator to separate class
  • Could simplify nested conditionals in authenticate()
  • Opportunity to cache user lookups for performance
  • Some variable names could be more descriptive (e.g., 'data' → 'user_data')

🚨 Required Fixes:
  • None

Complexity Metrics:
  • Average cyclomatic complexity: 3.2 (target: <5) ✅
  • Max function length: 42 lines (target: <50) ✅
  • Duplicate code: 0.8% (target: <2%) ✅
```

### Security Review (security)

**Review Focus:**

```yaml
Authentication:
  - Password storage secure (hashing)
  - Token validation robust
  - Session management safe
  - MFA properly implemented

Authorization:
  - Permission checks present
  - RBAC correctly implemented
  - Resource ownership validated
  - No privilege escalation

Input Validation:
  - All inputs sanitized
  - SQL injection prevented
  - XSS prevented
  - CSRF protection active

Data Protection:
  - Sensitive data encrypted
  - Secure communication (HTTPS)
  - No secrets in code
  - PII handling compliant

Vulnerabilities:
  - No known CVEs in deps
  - No hardcoded credentials
  - No insecure algorithms
  - No information leakage
```

**Review Output Format:**

```yaml
Security Review by security:

✅ Strengths:
  • Password hashing uses bcrypt with cost 12 (recommended)
  • JWT validation includes expiry, signature, and issuer checks
  • Input sanitization comprehensive across all endpoints
  • No hardcoded secrets or credentials found

⚠️ Suggestions:
  • Consider adding rate limiting to login endpoint (prevent brute force)
  • Add logging for failed authentication attempts (security monitoring)
  • Consider implementing password complexity requirements
  • Could add request signing for critical API operations

🚨 Required Fixes:
  • None - all critical security measures in place

Vulnerability Scan:
  • Dependencies: 0 critical, 0 high, 1 low (acceptable)
  • Code: No security vulnerabilities detected
  • Secrets: No hardcoded secrets found
```

### Test Coverage Review (qa)

**Review Focus:**

```yaml
Coverage Metrics:
  - Overall coverage ≥80%
  - Critical paths 100%
  - Edge cases covered
  - Error paths tested

Test Quality:
  - Assertions meaningful
  - Test names descriptive
  - Tests isolated
  - No flaky tests
  - Mocks appropriate

Test Types:
  - Unit tests for logic
  - Integration for flows
  - E2E for critical paths
  - Performance if needed

Test Organization:
  - Clear structure
  - Good fixtures
  - Helper functions
  - Easy to maintain
```

**Review Output Format:**

```yaml
Test Coverage Review by qa:

✅ Strengths:
  • Coverage at 87% (target: 80%) - exceeds requirement ✅
  • Critical auth paths 100% covered
  • Good edge case coverage (token expiry, invalid tokens, etc.)
  • Test names clear and descriptive
  • Tests properly isolated with fixtures

⚠️ Suggestions:
  • Could add tests for token refresh edge cases (concurrent requests)
  • Consider adding load tests for auth endpoints (performance validation)
  • Some assertions could be more specific (e.g., check exact error message)
  • Could add property-based tests for token generation

🚨 Required Fixes:
  • None

Coverage Breakdown:
  • src/auth/jwt.py: 92% (23/25 lines)
  • src/auth/service.py: 85% (34/40 lines)
  • src/auth/validators.py: 100% (15/15 lines)

Test Counts:
  • Unit tests: 38 passed
  • Integration tests: 12 passed
  • Security tests: 8 passed
  • Total: 58 tests, 0 failures
```

### Documentation Review (implementer)

**Review Focus:**

```yaml
API Documentation:
  - All endpoints documented
  - Parameters described
  - Responses documented
  - Examples provided

Code Documentation:
  - Functions have docstrings
  - Complex logic explained
  - Public APIs documented
  - Types annotated

Project Documentation:
  - README up to date
  - Setup instructions clear
  - Architecture documented
  - Examples working

Completeness:
  - No missing docs
  - Accurate and current
  - Easy to understand
  - Maintained with code
```

**Review Output Format:**

```yaml
Documentation Review by implementer:

✅ Strengths:
  • API documentation complete with OpenAPI specs
  • All public functions have clear docstrings
  • README updated with authentication section
  • Examples provided and tested

⚠️ Suggestions:
  • Could add more code examples for token refresh flow
  • Consider adding architecture diagram for auth flow
  • Some docstrings could include example usage
  • Could document error codes more explicitly

🚨 Required Fixes:
  • None

Documentation Coverage:
  • Public functions: 100% (all documented)
  • API endpoints: 100% (all in OpenAPI)
  • README: Up to date ✅
  • Examples: 3 working examples included
```

### Architecture Review (architect)

**When to Invoke:**

```yaml
Trigger Architecture Review:
  - New system components added
  - Major refactoring done
  - Cross-module dependencies changed
  - Database schema modified
  - API contract changes
  - Performance-critical features

Skip for:
  - Small bug fixes
  - Documentation updates
  - Minor refactoring
  - Single-file changes
```

**Review Focus:**

```yaml
Component Boundaries:
  - Clear separation of concerns
  - Dependencies flow correctly
  - No circular dependencies
  - Proper abstraction layers

Scalability:
  - Horizontal scaling supported
  - No obvious bottlenecks
  - Database queries optimized
  - Caching appropriate

Maintainability:
  - Easy to extend
  - Easy to test
  - Low coupling
  - High cohesion

Future-Proofing:
  - Flexible design
  - Easy to modify
  - Minimal technical debt
  - Clear upgrade path
```

**Review Output Format:**

```yaml
Architecture Review by architect:

✅ Strengths:
  • Clean layered architecture maintained
  • Auth module well-isolated from other concerns
  • JWT implementation abstracted (easy to swap if needed)
  • Good use of dependency injection for testability

⚠️ Suggestions:
  • Consider event-driven approach for audit logging (scalability)
  • Could abstract session storage interface (flexibility)
  • May want to add caching layer for user lookups (performance)
  • Consider adding rate limiting at architecture level

🚨 Required Fixes:
  • None

Architecture Health:
  • Coupling: Low ✅
  • Cohesion: High ✅
  • Complexity: Manageable ✅
  • Scalability: Good ✅
  • Technical debt: Low ✅
```

---

## Review Consolidation

### Collecting Agent Reviews

**Consolidation Strategy:**

```yaml
Step 1: Collect All Reviews
  - Wait for all agents to complete
  - Gather all review outputs
  - Organize by agent

Step 2: Identify Common Themes
  - Issues mentioned by multiple agents
  - Conflicting suggestions (rare)
  - Critical vs nice-to-have

Step 3: Prioritize Findings
  - 🚨 Required Fixes (blocking)
  - ⚠️ Suggestions (improvements)
  - ✅ Strengths (positive feedback)

Step 4: Generate Unified Summary
  - Overall assessment
  - Critical issues (if any)
  - Key improvements suggested
  - Ready-to-ship decision
```

### Unified Review Summary Template

```yaml
📊 Multi-Agent Review Summary

Code Quality (refactorer): ✅ EXCELLENT
  Strengths: [Top 3 strengths]
  Suggestions: [Top 2-3 suggestions]

Security (security): ✅ SECURE
  Strengths: [Top 3 strengths]
  Suggestions: [Top 2-3 suggestions]

Testing (qa): ✅ WELL-TESTED
  Strengths: [Coverage metrics + top strengths]
  Suggestions: [Top 2-3 suggestions]

Documentation (implementer): ✅ COMPLETE
  Strengths: [Documentation coverage]
  Suggestions: [Top 2-3 suggestions]

Architecture (architect): ✅ SOLID (if included)
  Strengths: [Architecture assessment]
  Suggestions: [Top 2-3 suggestions]

Overall Assessment: ✅ READY TO SHIP
  Critical Issues: [Count] (must be 0 to ship)
  Suggestions: [Count] (nice-to-have improvements)
  Quality Score: [Excellent/Good/Needs Work]

Recommendation: [Ship / Fix Critical Issues / Consider Suggestions]
```

### Example Consolidated Review

```yaml
📊 Multi-Agent Review Summary

Code Quality (refactorer): ✅ EXCELLENT
  Strengths:
    • Clean architecture with excellent separation of concerns
    • Consistent code style and naming conventions
    • Low complexity (avg 3.2, target <5)

  Suggestions:
    • Consider extracting UserValidator class
    • Simplify nested conditionals in authenticate()

Security (security): ✅ SECURE
  Strengths:
    • Robust bcrypt password hashing (cost 12)
    • Comprehensive JWT validation
    • No hardcoded secrets or credentials

  Suggestions:
    • Add rate limiting to prevent brute force
    • Add security event logging

Testing (qa): ✅ WELL-TESTED
  Strengths:
    • 87% coverage (exceeds 80% target)
    • All critical paths fully tested
    • Good edge case coverage

  Suggestions:
    • Add tests for concurrent token refresh
    • Consider load testing auth endpoints

Documentation (implementer): ✅ COMPLETE
  Strengths:
    • All APIs documented with OpenAPI
    • Clear docstrings on all functions
    • README updated with examples

  Suggestions:
    • Add architecture diagram
    • More code examples for token flow

Overall Assessment: ✅ READY TO SHIP
  Critical Issues: 0
  Suggestions: 8 nice-to-have improvements
  Quality Score: Excellent

Recommendation: SHIP - All quality gates passed. Consider addressing suggestions in future iteration.
```

---

## Agent Communication Best Practices

### Clear Context Handoff

**When Chaining Agents:**

```yaml
Good Context Handoff:
  Use the security agent to review authentication
    → Output: Security review with 3 suggestions

  Use the implementer agent to document security measures
    Context: Security review identified token expiry, hashing, validation
    Task: Document these security features in API docs

Bad Context Handoff:
  Use the security agent to review authentication
  Use the implementer agent to add docs
    Problem: implementer doesn't know what security found
```

### Explicit Review Boundaries

**Define What Each Agent Reviews:**

```yaml
Good Boundary Definition:
  Use the refactorer agent to review code quality:
    - Focus: Code structure, naming, patterns
    - Scope: src/auth/ directory only
    - Exclude: Security aspects (security agent will cover)

Bad Boundary Definition:
  Use the refactorer agent to review the code
    Problem: Unclear scope and focus
```

### Validation After Each Review

**Always Validate Agent Output:**

```yaml
Review Validation:
  After agent completes:
    1. Check review is comprehensive
    2. Verify findings are actionable
    3. Ensure no critical issues missed
    4. Validate suggestions are reasonable

  If issues:
    - Re-prompt agent with clarifications
    - Use different agent for second opinion
    - Escalate to user if uncertain
```

---

## Quality Checkpoint Triggers

### Automatic Agent Invocation

**Based on Code Metrics:**

```yaml
High Complexity Detected:
  If cyclomatic complexity >10:
    → Use the refactorer agent to:
      - Analyze complex functions
      - Suggest simplifications
      - Break into smaller functions

Security Patterns Found:
  If authentication/encryption code:
    → Use the security agent to:
      - Review security implementation
      - Validate secure patterns
      - Check for vulnerabilities

Low Test Coverage:
  If coverage <80%:
    → Use the qa agent to:
      - Identify untested code
      - Suggest test cases
      - Improve coverage

Missing Documentation:
  If docstring coverage <90%:
    → Use the implementer agent to:
      - Identify missing docs
      - Generate docstrings
      - Add examples

Circular Dependencies:
  If circular deps detected:
    → Use the architect agent to:
      - Analyze dependency structure
      - Suggest refactoring
      - Break circular references
```

---

## Multi-Agent Review Best Practices

### DO:

```yaml
✅ Best Practices:
  - ALWAYS use workflow-coordinator first
  - Use parallel reviews for speed when possible
  - Provide clear context to each agent
  - Validate each agent's output
  - Consolidate findings into unified summary
  - Focus agents on their expertise areas
  - Skip unnecessary agents for simple changes
  - Use sequential review for critical features
```

### DON'T:

```yaml
❌ Anti-Patterns:
  - Skip workflow-coordinator validation
  - Use all agents for every review (overkill)
  - Let agents review outside their expertise
  - Forget to consolidate findings
  - Accept reviews without validation
  - Chain agents without clear handoff
  - Run sequential when parallel would work
  - Use parallel when sequential needed
```

---

*Comprehensive multi-agent review strategies for quality assurance and code validation*