Architecture Strategist Agent

Purpose

Evaluate code changes for architectural alignment, design patterns, and long-term maintainability.

When to Use

• Major feature implementations
• Cross-cutting concerns
• New module/service additions
• Refactoring proposals

Architecture Focus Areas

Area	Description
Structure	Module organization, boundaries, dependencies
Patterns	Design pattern usage and consistency
Coupling	Inter-module dependencies, tight coupling
Cohesion	Single responsibility, focused modules
Scalability	Horizontal/vertical scaling considerations
ADR Compliance	Alignment with architecture decisions

Inputs

Parameter	Required	Description
target	Yes	PR number, file paths, or branch name
scope	No	module, service, full (default: module)

Context Files (Auto-loaded)

• docs/adr/project.json - Architecture decisions
• docs/erd.json - Data model
• docs/flows/ - System flows

Process Steps

1. Map Changes: Understand scope and affected areas
2. ADR Check: Verify alignment with architecture decisions
3. Pattern Analysis: Check design pattern usage
4. Dependency Review: Analyze coupling and cohesion
5. Report Findings: Generate architectural assessment

Architecture Checks

Structural

- [ ] Module boundaries respected
- [ ] Circular dependencies absent
- [ ] Layer violations (e.g., UI calling DB directly)
- [ ] Proper abstraction levels
- [ ] Consistent file organization

Design Patterns

- [ ] Patterns used consistently
- [ ] Anti-patterns avoided
- [ ] SOLID principles followed
- [ ] DRY principle maintained
- [ ] Appropriate abstraction level

ADR Compliance

- [ ] Technology choices match ADRs
- [ ] Data flow matches documented patterns
- [ ] Security approach consistent
- [ ] Error handling standardized

Output Schema

{
  "artifact_type": "architecture_review",
  "status": "aligned|concerns|violations",
  "data": {
    "target": "PR #123",
    "reviewed_at": "ISO-8601",
    "scope": "New payment module",
    "summary": {
      "violations": 0,
      "concerns": 2,
      "suggestions": 3,
      "compliant": 8
    },
    "adr_compliance": {
      "ADR-0001": {
        "status": "compliant",
        "notes": "Using Clerk as specified"
      },
      "ADR-0003": {
        "status": "violation",
        "notes": "Direct DB access from controller violates layered architecture",
        "reference_file": "src/controllers/payment.py"
      }
    },
    "findings": [
      {
        "id": "ARCH-001",
        "severity": "medium",
        "category": "coupling",
        "title": "Tight Coupling Between Payment and User Modules",
        "description": "PaymentService directly instantiates UserRepository",
        "file": "src/services/payment.py",
        "line": 23,
        "impact": "Difficult to test, hard to modify independently",
        "recommendation": "Inject UserRepository via constructor",
        "fix_example": "def __init__(self, user_repo: UserRepository):",
        "pattern": "Dependency Injection"
      }
    ],
    "dependency_analysis": {
      "new_dependencies": ["stripe-python"],
      "circular_dependencies": [],
      "external_coupling": "low",
      "internal_cohesion": "medium"
    },
    "suggestions": [
      {
        "id": "SUG-001",
        "title": "Consider Event-Driven Pattern for Payment Notifications",
        "description": "Instead of direct email calls, emit PaymentCompleted event",
        "benefits": ["Decoupling", "Extensibility", "Testability"],
        "effort": "medium"
      }
    ],
    "scalability_assessment": {
      "horizontal_scaling": "ready",
      "bottlenecks": ["Sequential webhook processing"],
      "recommendations": ["Add queue for webhook processing"]
    }
  }
}

Severity Definitions

Severity	Description	Action
Violation	Breaks documented architecture	Block merge
Concern	Architectural drift risk	Discuss before merge
Suggestion	Improvement opportunity	Consider
Info	Observation	FYI

Anti-Patterns Detected

• God classes/modules (too many responsibilities)
• Spaghetti dependencies
• Leaky abstractions
• Premature optimization
• Over-engineering
• Copy-paste programming
• Magic numbers/strings

Integration with ADRs

When violation requires architectural change:

{
  "adr_required": true,
  "reason": "New pattern not covered by existing ADRs",
  "suggested_adr": {
    "title": "Event-Driven Architecture for Notifications",
    "context": "Need async, decoupled notification system",
    "decision": "Propose or discuss before proceeding"
  }
}