arch-review

Architecture Review (RFC Pattern)

Orchestrate a 5-agent team for RFC-style technical decision reviews. Agents review independently, then debate trade-offs in structured discussion.

Workflow

1. Parse Target

Extract the proposal from $ARGUMENTS. This could be:

• Path to an RFC document (e.g., .claude/rfcs/001-new-api.md)
• Path to a design document or ADR
• Inline description of the proposed change
• GitHub issue/PR number containing the proposal

If a path is provided, read the file. If it's a description, use it directly. If it's an issue/PR, fetch it with gh.

2. Spawn Review Team

Use the Teammate tool with operation spawnTeam to create the review team:

team_name: arch-review
description: RFC review for [proposal-name]

Then spawn 5 teammates using the Task tool, one for each agent type:

Team composition:

1. tech-lead: Overall architecture, team impact, maintainability
2. security-auditor: Security implications, threat model, attack surface
3. performance-analyst: Scalability, efficiency, resource usage
4. reliability-engineer: Failure modes, observability, operational complexity
5. devils-advocate: Necessity, simpler alternatives, hidden assumptions

3. Independent Review Phase

Create 5 tasks (one per agent) using TaskCreate. Each task should have:

subject: Review [proposal] as [agent-role] description: Full proposal context + agent-specific review checklist (see REFERENCE.md) activeForm: Reviewing as [agent-role]

Assign each task to the corresponding agent using TaskUpdate with owner field.

CRITICAL: Include the full proposal text in each task description. Agents don't share context, so each needs complete information.

4. Collect Independent Reviews

Wait for all 5 agents to complete their reviews. Each agent should produce:

## [Agent Role] Review

### Assessment
[Overall judgment: Approve / Approve with conditions / Reject]

### Key Concerns
- [Prioritized list of concerns]

### Trade-offs Identified
- [Trade-offs specific to this lens]

### Questions for Team
- [Questions to raise in debate]

### Recommendation
[What this agent thinks should happen and why]

As agents complete, use TaskList to track progress and read their outputs.

5. Facilitate Structured Debate

Once all reviews are in, create a debate task. This can be a broadcast message or a new task assigned to tech-lead to facilitate.

Debate structure:

1. Opening round: Each agent states their key concern (1 min each)
2. Trade-off discussion: Focus on the top 3 conflicts identified across reviews
   • Example: security-auditor wants more encryption, performance-analyst warns of latency cost
3. Alternative exploration: devils-advocate presents simpler alternatives, team responds
4. Consensus building: What do we agree on? What remains contentious?
5. Final positions: Each agent gives final recommendation (Approve/Conditional/Reject)

Facilitate this by sending targeted messages:

• Ask agents to respond to each other's concerns
• Highlight conflicts that need resolution
• Push for concrete recommendations, not just analysis

6. Synthesize Decision Document

Consolidate findings into an RFC-style decision document:

# Architecture Review: [Proposal Name]

**Date**: [current date]
**Reviewers**: tech-lead, security-auditor, performance-analyst, reliability-engineer, devils-advocate
**Proposal**: [one-line summary]

## Executive Summary

[2-3 sentences: What's being proposed, overall recommendation, biggest trade-off]

## Recommendation

**Decision**: [Approve / Approve with conditions / Reject / Need more information]

**Confidence**: [High / Medium / Low]

**Conditions** (if applicable):
1. [Must-have changes before approval]
2. [...]

## Review Summary

### Consensus Points
- [Things all agents agreed on]

### Key Trade-offs

#### [Trade-off 1: e.g., Security vs Performance]
- **security-auditor**: [position]
- **performance-analyst**: [position]
- **Resolution**: [recommended approach]

#### [Trade-off 2]
- **[agent]**: [position]
- **[agent]**: [position]
- **Resolution**: [recommended approach]

### Dissenting Opinions

**[Agent role]** disagrees because:
- [Key concern]
- [Recommended alternative]

### Questions Requiring Clarification
1. [Unresolved questions from the review]
2. [...]

## Detailed Findings

### Architecture (tech-lead)
[Summary of tech-lead's assessment]

### Security (security-auditor)
[Summary of security concerns and mitigations]

### Performance (performance-analyst)
[Summary of performance implications]

### Reliability (reliability-engineer)
[Summary of operational concerns]

### Simplicity (devils-advocate)
[Summary of complexity concerns and alternatives]

## Action Items

### Before Approval
1. [Must-do items]

### Post-Approval
1. [Follow-up work if approved]

### If Rejected
1. [What to do instead]

## Appendix: Individual Reviews

[Include full reviews from each agent for reference]

7. Cleanup

After synthesizing the decision document, gracefully shut down all teammates using SendMessage with type: "shutdown_request" for each agent.

Then use the Teammate tool with operation: "cleanup" to clean up team resources.

Output Guidelines

• Be decisive: The team should converge on a clear recommendation, not "it depends"
• Highlight conflicts: Disagreements between agents are valuable signals
• Preserve dissent: If one agent strongly disagrees, document their reasoning
• Actionable: Conditions for approval should be concrete and testable
• Time-boxed: If debate stalls after 3 rounds, call for final votes

Notes

• Agents may update their positions during debate — capture both initial and final stances
• The tech-lead doesn't override other agents; they're peers in the discussion
• If all 5 agents agree (rare), document why and check for groupthink
• Include the decision document in .claude/decisions/ or docs/adr/ if appropriate

Related Files

• REFERENCE.md: Detailed review checklists for each agent role