---
name: system-architect
description: Generate or update system-architect/analysis.md addressing guidance-specification discussion points for system architecture perspective
argument-hint: "optional topic - uses existing framework if available"
allowed-tools: Task(conceptual-planning-agent), TodoWrite(*), Read(*), Write(*)
---

## 🏗️ **System Architect Analysis Generator**

### Purpose
**Specialized command for generating system-architect/analysis.md** that addresses guidance-specification.md discussion points from system architecture perspective. Creates or updates role-specific analysis with framework references.

### Core Function
- **Framework-based Analysis**: Address each discussion point in guidance-specification.md
- **Architecture Focus**: Technical architecture, scalability, and system design perspective
- **Update Mechanism**: Create new or update existing analysis.md
- **Agent Delegation**: Use conceptual-planning-agent for analysis generation

### Analysis Scope
- **Technical Architecture**: Scalable and maintainable system design
- **Technology Selection**: Stack evaluation and architectural decisions
- **Performance & Scalability**: Capacity planning and optimization strategies
- **Integration Patterns**: System communication and data flow design

### Role Boundaries & Responsibilities

#### **What This Role OWNS (Macro-Architecture)**
- **System-Level Architecture**: Service boundaries, deployment topology, and system composition
- **Cross-Service Communication Patterns**: Choosing between microservices/monolithic, event-driven/request-response, sync/async patterns
- **Technology Stack Decisions**: Language, framework, database, and infrastructure choices
- **Non-Functional Requirements**: Scalability, performance, availability, disaster recovery, and monitoring strategies
- **Integration Planning**: How systems and services connect at the macro level (not specific API contracts)

#### **What This Role DOES NOT Own (Defers to Other Roles)**
- **API Contract Details**: Specific endpoint definitions, URL structures, HTTP methods → Defers to **API Designer**
- **Data Schemas**: Detailed data model design and entity relationships → Defers to **Data Architect**
- **UI/UX Design**: Interface design and user experience → Defers to **UX Expert** and **UI Designer**

#### **Handoff Points**
- **TO API Designer**: Provides architectural constraints (REST vs GraphQL, sync vs async) that define the API design space
- **TO Data Architect**: Provides system-level data flow requirements and integration patterns
- **FROM Data Architect**: Receives canonical data model to inform system integration design

## ⚙️ **Execution Protocol**

### Phase 1: Session & Framework Detection
```bash
# Check active session and framework
CHECK: find .workflow/active/ -name "WFS-*" -type d
IF active_session EXISTS:
    session_id = get_active_session()
    brainstorm_dir = .workflow/active/WFS-{session}/.brainstorming/

    CHECK: brainstorm_dir/guidance-specification.md
    IF EXISTS:
        framework_mode = true
        load_framework = true
    ELSE:
        IF topic_provided:
            framework_mode = false  # Create analysis without framework
        ELSE:
            ERROR: "No framework found and no topic provided"
```

### Phase 2: Analysis Mode Detection
```bash
# Check existing analysis
CHECK: brainstorm_dir/system-architect/analysis.md
IF EXISTS:
    SHOW existing analysis summary
    ASK: "Analysis exists. Do you want to:"
    OPTIONS:
      1. "Update with new insights" → Update existing
      2. "Replace completely" → Generate new
      3. "Cancel" → Exit without changes
ELSE:
    CREATE new analysis
```

### Phase 3: Agent Task Generation
**Framework-Based Analysis** (when guidance-specification.md exists):
```bash
Task(subagent_type="conceptual-planning-agent",
     run_in_background=false,
     prompt="Generate system architect analysis addressing topic framework

     ## Framework Integration Required
     **MANDATORY**: Load and address guidance-specification.md discussion points
     **Framework Reference**: @{session.brainstorm_dir}/guidance-specification.md
     **Output Location**: {session.brainstorm_dir}/system-architect/analysis.md

     ## Analysis Requirements
     1. **Load Topic Framework**: Read guidance-specification.md completely
     2. **Address Each Discussion Point**: Respond to all 5 framework sections from system architecture perspective
     3. **Include Framework Reference**: Start analysis.md with @../guidance-specification.md
     4. **Technical Focus**: Emphasize scalability, architecture patterns, technology decisions
     5. **Structured Response**: Use framework structure for analysis organization

     ## Framework Sections to Address
     - Core Requirements (from architecture perspective)
     - Technical Considerations (detailed architectural analysis)
     - User Experience Factors (technical UX considerations)
     - Implementation Challenges (architecture risks and solutions)
     - Success Metrics (technical metrics and monitoring)

     ## Output Structure Required
     ```markdown
     # System Architect Analysis: [Topic]

     **Framework Reference**: @../guidance-specification.md
     **Role Focus**: System Architecture and Technical Design

     ## Core Requirements Analysis
     [Address framework requirements from architecture perspective]

     ## Technical Considerations
     [Detailed architectural analysis]

     ## User Experience Factors
     [Technical aspects of UX implementation]

     ## Implementation Challenges
     [Architecture risks and mitigation strategies]

     ## Success Metrics
     [Technical metrics and system monitoring]

     ## Architecture-Specific Recommendations
     [Detailed technical recommendations]
     ```",
     description="Generate system architect framework-based analysis")
```

### Phase 4: Update Mechanism
**Analysis Update Process**:
```bash
# For existing analysis updates
IF update_mode = "incremental":
    Task(subagent_type="conceptual-planning-agent",
         run_in_background=false,
         prompt="Update existing system architect analysis

         ## Current Analysis Context
         **Existing Analysis**: @{session.brainstorm_dir}/system-architect/analysis.md
         **Framework Reference**: @{session.brainstorm_dir}/guidance-specification.md

         ## Update Requirements
         1. **Preserve Structure**: Maintain existing analysis structure
         2. **Add New Insights**: Integrate new technical insights and recommendations
         3. **Framework Alignment**: Ensure continued alignment with topic framework
         4. **Technical Updates**: Add new architecture patterns, technology considerations
         5. **Maintain References**: Keep @../guidance-specification.md reference

         ## Update Instructions
         - Read existing analysis completely
         - Identify areas for enhancement or new insights
         - Add technical depth while preserving original structure
         - Update recommendations with new architectural approaches
         - Maintain framework discussion point addressing",
         description="Update system architect analysis incrementally")
```

## Document Structure

### Output Files
```
.workflow/active/WFS-[topic]/.brainstorming/
├── guidance-specification.md          # Input: Framework (if exists)
└── system-architect/
    └── analysis.md            # ★ OUTPUT: Framework-based analysis
```

### Analysis Structure
**Required Elements**:
- **Framework Reference**: @../guidance-specification.md (if framework exists)
- **Role Focus**: System Architecture and Technical Design perspective
- **5 Framework Sections**: Address each framework discussion point
- **Technical Recommendations**: Architecture-specific insights and solutions
- How should we design APIs and manage versioning?

**4. Performance and Scalability**
- Where are the current system performance bottlenecks?
- How should we handle traffic growth and scaling demands?
- What database scaling and optimization strategies are needed?

## ⚡ **Two-Step Execution Flow**

### ⚠️ Session Management - FIRST STEP
Session detection and selection:
```bash
# Check for existing sessions
existing_sessions=$(find .workflow/active/ -name "WFS-*" -type d 2>/dev/null)
if [ multiple_sessions ]; then
  prompt_user_to_select_session()
else
  use_existing_or_create_new()
fi
```

### Step 1: Context Gathering Phase
**System Architect Perspective Questioning**

Before agent assignment, gather comprehensive system architecture context:

#### 📋 Role-Specific Questions
1. **Scale & Performance Requirements**
   - Expected user load and traffic patterns?
   - Performance requirements (latency, throughput)?
   - Data volume and growth projections?

2. **Technical Constraints & Environment**
   - Existing technology stack and constraints?
   - Integration requirements with external systems?
   - Infrastructure and deployment environment?

3. **Architecture Complexity & Patterns**
   - Microservices vs monolithic considerations?
   - Data consistency and transaction requirements?
   - Event-driven vs request-response patterns?

4. **Non-Functional Requirements**
   - High availability and disaster recovery needs?
   - Security and compliance requirements?
   - Monitoring and observability expectations?

#### Context Validation
- **Minimum Response**: Each answer must be ≥50 characters
- **Re-prompting**: Insufficient detail triggers follow-up questions
- **Context Storage**: Save responses to `.brainstorming/system-architect-context.md`

### Step 2: Agent Assignment with Flow Control
**Dedicated Agent Execution**

```bash
Task(conceptual-planning-agent): "
[FLOW_CONTROL]

Execute dedicated system-architect conceptual analysis for: {topic}

ASSIGNED_ROLE: system-architect
OUTPUT_LOCATION: .brainstorming/system-architect/
USER_CONTEXT: {validated_responses_from_context_gathering}

Flow Control Steps:
[
  {
    \"step\": \"load_role_template\",
    \"action\": \"Load system-architect planning template\",
    \"command\": \"bash($(cat ~/.claude/workflows/cli-templates/planning-roles/system-architect.md))\",
    \"output_to\": \"role_template\"
  }
]

Conceptual Analysis Requirements:
- Apply system-architect perspective to topic analysis
- Focus on architectural patterns, scalability, and integration points
- Use loaded role template framework for analysis structure
- Generate role-specific deliverables in designated output location
- Address all user context from questioning phase

Deliverables:
- analysis.md: Main system architecture analysis
- recommendations.md: Architecture recommendations
- deliverables/: Architecture-specific outputs as defined in role template

Embody system-architect role expertise for comprehensive conceptual planning."
```

### Progress Tracking
TodoWrite tracking for two-step process:
```json
[
  {"content": "Gather system architect context through role-specific questioning", "status": "in_progress", "activeForm": "Gathering context"},
  {"content": "Validate context responses and save to system-architect-context.md", "status": "pending", "activeForm": "Validating context"},
  {"content": "Load system-architect planning template via flow control", "status": "pending", "activeForm": "Loading template"},
  {"content": "Execute dedicated conceptual-planning-agent for system-architect role", "status": "pending", "activeForm": "Executing agent"}
]
```

## 📊 **Output Specification**

### Output Location
```
.workflow/active/WFS-{topic-slug}/.brainstorming/system-architect/
├── analysis.md                 # Primary architecture analysis
├── architecture-design.md      # Detailed system design and diagrams
├── technology-stack.md         # Technology stack recommendations and justifications
└── integration-plan.md         # System integration and API strategies
```

### Document Templates

#### analysis.md Structure
```markdown
# System Architecture Analysis: {Topic}
*Generated: {timestamp}*

## Executive Summary
[Key architectural findings and recommendations overview]

## Current State Assessment
### Existing Architecture Overview
### Technical Stack Analysis
### Performance Bottlenecks
### Technical Debt Assessment

## Requirements Analysis
### Functional Requirements
### Non-Functional Requirements
- Performance: [Response time, throughput requirements]
- Scalability: [User growth, data volume expectations]
- Availability: [Uptime requirements]
- Security: [Security requirements]

## Proposed Architecture
### High-Level Architecture Design
### Component Breakdown
### Data Flow Diagrams
### Technology Stack Recommendations

## Implementation Strategy
### Migration Planning
### Risk Mitigation
### Performance Optimization
### Security Considerations

## Scalability and Maintenance
### Horizontal Scaling Strategy
### Monitoring and Observability
### Deployment Strategy
### Long-term Maintenance Plan
```

## 🔄 **Session Integration**

### Status Synchronization
Upon completion, update `workflow-session.json`:
```json
{
  "phases": {
    "BRAINSTORM": {
      "system_architect": {
        "status": "completed",
        "completed_at": "timestamp",
        "output_directory": ".workflow/active/WFS-{topic}/.brainstorming/system-architect/",
        "key_insights": ["scalability_bottleneck", "architecture_pattern", "technology_recommendation"]
      }
    }
  }
}
```

### Cross-Role Collaboration
System architect perspective provides:
- **Technical Constraints and Possibilities** → Product Manager
- **Architecture Requirements and Limitations** → UI Designer
- **Data Architecture Requirements** → Data Architect
- **Security Architecture Framework** → Security Expert
- **Technical Implementation Framework** → Feature Planner

## ✅ **Quality Assurance**

### Required Analysis Elements
- [ ] Clear architecture diagrams and component designs
- [ ] Detailed technology stack evaluation and recommendations
- [ ] Scalability and performance analysis with metrics
- [ ] System integration and API design specifications
- [ ] Comprehensive risk assessment and mitigation strategies

### Architecture Design Principles
- [ ] **Scalability**: System can handle growth in users and data
- [ ] **Maintainability**: Clear code structure, easy to modify and extend
- [ ] **Reliability**: Built-in fault tolerance and recovery mechanisms
- [ ] **Security**: Integrated security controls and protection measures
- [ ] **Performance**: Meets response time and throughput requirements

### Technical Decision Validation
- [ ] Technology choices have thorough justification and comparison analysis
- [ ] Architectural patterns align with business requirements and constraints
- [ ] Integration solutions consider compatibility and maintenance costs
- [ ] Deployment strategies are feasible with acceptable risk levels
- [ ] Monitoring and operations strategies are comprehensive and actionable

### Implementation Readiness
- [ ] **Technical Feasibility**: All proposed solutions are technically achievable
- [ ] **Resource Planning**: Resource requirements clearly defined and realistic
- [ ] **Risk Management**: Technical risks identified with mitigation plans
- [ ] **Performance Validation**: Architecture can meet performance requirements
- [ ] **Evolution Strategy**: Design allows for future growth and changes
