tpl-superclaude/.claude/commands/design/1-system-architecture/4-generate-architecture-summary.md

allowed-tools, description

allowed-tools	description
Read Write Glob TodoWrite	Generates a comprehensive architecture summary that consolidates all system architecture components into a unified documentation package.

Generate Architecture Summary

Context

• User Request: $ARGUMENTS
• Architecture Session: Identified by --name argument (architecture session name or index).
• Source Documents: All architecture documents from the specified architecture session directory.
• Output Format: Optional --format argument (markdown, pdf, html, confluence).
• Summary Scope: Optional --scope argument to focus on specific architecture areas.
• Design Directory: .taskmaster/docs/design/architecture/

Goal

To create a comprehensive architecture summary that consolidates the architecture framework, component design, and integration architecture into a unified, stakeholder-ready documentation package that provides clear guidance for development teams and technical decision-makers.

Process

1. Identify Source Architecture Session:

   • Use the --name argument to locate the correct architecture session directory (e.g., .taskmaster/docs/design/architecture/001-enterprise-expansion/).
   • Find all architecture documents within the session directory:
     • architecture-framework_*.md
     • component-design_*.md
     • integration-architecture_*.md
     • _session-state.json

2. Extract Architecture Content:

   • Architecture Framework: High-level architecture vision, domain boundaries, and layer design
   • Component Design: Detailed component specifications, interfaces, and implementation guidelines
   • Integration Architecture: Communication protocols, data flow, and service integration patterns
   • Session Metadata: Architecture session status, metrics, and completion details

3. Process Summary Scope (if specified):

   • If --scope argument is provided, focus on specific architecture areas
   • Supported scopes: executive, technical, implementation, operations
   • Parse and validate scope parameters

4. Analyze Architecture Completeness:

   • Completeness Assessment: Verify all architecture components are defined
   • Consistency Analysis: Check for consistency across architecture documents
   • Gap Analysis: Identify missing components or incomplete specifications
   • Quality Assessment: Evaluate architecture quality and adherence to best practices

5. Generate Executive Summary:

   • Architecture Overview: High-level architecture vision and business alignment
   • Key Decisions: Critical architectural decisions and their rationale
   • Risk Assessment: Architecture risks and mitigation strategies
   • Implementation Roadmap: Recommended implementation approach and timeline

6. Create Technical Summary:

   • System Architecture: Consolidated view of system structure and components
   • Integration Patterns: Summary of communication and integration approaches
   • Quality Attributes: Architecture support for performance, security, and scalability
   • Technology Stack: Recommended technologies and frameworks

7. Generate Implementation Guide:

   • Development Approach: Recommended development methodology and team organization
   • Component Implementation: Priority and sequence for component development
   • Integration Strategy: Approach for component integration and testing
   • Quality Assurance: Testing strategy and quality gates

8. Create Operations Guide:

   • Deployment Architecture: Deployment patterns and infrastructure requirements
   • Monitoring Strategy: Observability and monitoring approach
   • Maintenance Guidelines: Architecture evolution and maintenance procedures
   • Troubleshooting Guide: Common issues and resolution approaches

9. Generate Architecture Summary Document:

   • Create the architecture summary document named architecture-summary_[architecture_session_name].md.
   • Structure content according to the architecture summary template.
   • Include:
     • Executive Summary: High-level overview for stakeholders
     • Technical Architecture: Detailed technical specifications
     • Implementation Guide: Development and integration guidance
     • Operations Guide: Deployment and maintenance procedures
     • Appendices: Supporting documentation and references

10. Create Supporting Documentation:

    • Generate architecture diagrams and visual representations
    • Create component dependency matrices and relationship diagrams
    • Generate API documentation and interface specifications
    • Create implementation checklists and quality gates

11. Process Output Format (if specified):

    • If --format argument is provided, generate additional formats
    • Supported formats: pdf, html, confluence
    • Maintain consistent content across all formats

12. Update Architecture Session State:

    • Update the existing _session-state.json file in the architecture session directory.
    • Set status to architecture_complete and update completion metrics.
    • Add architecture summary generation status and results.

13. Notify User with Architecture Summary:

    • Inform the user that the architecture summary has been successfully generated.
    • Provide file paths and key architectural highlights.
    • Suggest logical next steps based on architecture completion:
      • "Your architecture summary is complete. Consider beginning UI/UX design using /design/ui-ux/1-design-system --name=[session_name]"
      • "Review the architecture summary with your stakeholders for approval and feedback."
      • "Use the implementation guide to create detailed development tasks and sprint planning."

Templates & Structures

Architecture Summary Template

# Architecture Summary: [Architecture Session Name]

**Created:** [Date]  
**Architecture Session:** [Architecture Session Name]  
**Architecture Style:** [Layered/Microservices/Event-Driven/Hybrid]  
**Completeness:** [Complete/Partial]  
**Review Status:** [Pending/Approved/Needs Changes]  
**Last Updated:** [Date]

---

## Executive Summary

### Business Context
- **Project Vision:** [High-level project vision and business objectives]
- **Business Drivers:** [Key business requirements driving this architecture]
- **Success Criteria:** [How architectural success will be measured]
- **Stakeholder Alignment:** [Key stakeholders and their concerns addressed]

### Architecture Overview
- **Architecture Style:** [Primary architectural style and rationale]
- **System Scale:** [Expected system scale and capacity requirements]
- **Key Components:** [Number and types of major system components]
- **Integration Complexity:** [Assessment of integration complexity and challenges]

### Key Architectural Decisions
#### Decision 1: [Decision Topic]
- **Decision:** [What was decided]
- **Rationale:** [Why this decision was made]
- **Impact:** [Business and technical impact]
- **Risks:** [Associated risks and mitigation strategies]

#### Decision 2: [Decision Topic]
- **Decision:** [What was decided]
- **Rationale:** [Why this decision was made]
- **Impact:** [Business and technical impact]
- **Risks:** [Associated risks and mitigation strategies]

### Risk Assessment
- **High Risk:** [Critical risks requiring immediate attention]
- **Medium Risk:** [Important risks requiring monitoring]
- **Low Risk:** [Minor risks with acceptable impact]
- **Risk Mitigation:** [Overall risk mitigation strategy]

### Implementation Roadmap
- **Phase 1:** [Initial implementation phase and timeline]
- **Phase 2:** [Subsequent phases and milestones]
- **Critical Path:** [Dependencies and critical path items]
- **Resource Requirements:** [Team size, skills, and infrastructure needs]

---

## Technical Architecture

### System Architecture Overview
- **Domain Architecture:** [Number of domains and their relationships]
- **Layer Architecture:** [Architectural layers and their responsibilities]
- **Component Architecture:** [Major components and their interactions]
- **Integration Architecture:** [Communication patterns and integration approaches]

### Domain Architecture
#### Domain 1: [Domain Name]
- **Purpose:** [What this domain represents in the business]
- **Key Components:** [Major components within this domain]
- **Boundaries:** [Clear domain boundaries and responsibilities]
- **Integration Points:** [How this domain integrates with others]

#### Domain 2: [Domain Name]
- **Purpose:** [What this domain represents in the business]
- **Key Components:** [Major components within this domain]
- **Boundaries:** [Clear domain boundaries and responsibilities]
- **Integration Points:** [How this domain integrates with others]

### Component Architecture
#### Component Summary
- **Total Components:** [Number of components in the system]
- **Layer Distribution:** [Components by architectural layer]
- **Component Types:** [Distribution of component types]
- **Integration Complexity:** [Assessment of component integration]

#### Key Components
##### Component 1: [Component Name]
- **Layer:** [Architectural layer]
- **Purpose:** [Primary responsibility]
- **Interfaces:** [Key interfaces and contracts]
- **Dependencies:** [Major dependencies]
- **Technology:** [Recommended technology stack]

##### Component 2: [Component Name]
- **Layer:** [Architectural layer]
- **Purpose:** [Primary responsibility]
- **Interfaces:** [Key interfaces and contracts]
- **Dependencies:** [Major dependencies]
- **Technology:** [Recommended technology stack]

### Integration Architecture
#### Communication Patterns
- **Synchronous:** [REST APIs, gRPC, direct calls]
- **Asynchronous:** [Message queues, event streams, pub/sub]
- **Data Integration:** [Database integration and data sharing]
- **External Integration:** [Third-party service integration]

#### Integration Protocols
- **API Standards:** [REST, GraphQL, gRPC specifications]
- **Message Formats:** [JSON, Protocol Buffers, Avro schemas]
- **Security Protocols:** [Authentication, authorization, encryption]
- **Error Handling:** [Error handling and retry patterns]

### Quality Attributes
- **Performance:** [Response time, throughput, resource usage targets]
- **Scalability:** [Horizontal and vertical scaling approaches]
- **Reliability:** [Fault tolerance and resilience patterns]
- **Security:** [Security architecture and protection mechanisms]
- **Maintainability:** [Code organization and evolution strategies]

### Technology Stack
- **Programming Languages:** [Primary and secondary languages]
- **Frameworks:** [Web, application, and infrastructure frameworks]
- **Databases:** [Database technologies and data stores]
- **Infrastructure:** [Cloud platforms, containers, orchestration]
- **Tools:** [Development, testing, and operational tools]

---

## Implementation Guide

### Development Approach
- **Methodology:** [Agile, iterative, or other development approach]
- **Team Organization:** [Team structure and responsibilities]
- **Development Standards:** [Coding standards and best practices]
- **Quality Practices:** [Code review, testing, and quality assurance]

### Component Implementation Priority
#### Phase 1: Foundation Components
- **Priority Components:** [Most critical components to implement first]
- **Implementation Order:** [Recommended sequence of implementation]
- **Dependencies:** [Key dependencies and blocking factors]
- **Timeline:** [Estimated implementation timeline]

#### Phase 2: Core Features
- **Feature Components:** [Core business functionality components]
- **Integration Points:** [Key integration points to establish]
- **Testing Strategy:** [Testing approach for this phase]
- **Risk Management:** [Phase-specific risks and mitigation]

#### Phase 3: Advanced Features
- **Enhancement Components:** [Advanced features and optimizations]
- **Performance Optimization:** [Performance tuning and optimization]
- **Monitoring Integration:** [Observability and monitoring setup]
- **Security Hardening:** [Security enhancements and hardening]

### Integration Strategy
- **Integration Testing:** [Approach for testing component integration]
- **Contract Testing:** [API contract testing and validation]
- **End-to-End Testing:** [System-level testing strategy]
- **Performance Testing:** [Performance and load testing approach]

### Quality Assurance
- **Testing Framework:** [Testing tools and frameworks]
- **Code Quality:** [Static analysis and code quality tools]
- **Security Testing:** [Security testing and vulnerability scanning]
- **Performance Monitoring:** [Performance monitoring and optimization]

### Development Environment
- **Local Development:** [Local development setup and tools]
- **CI/CD Pipeline:** [Continuous integration and deployment]
- **Environment Management:** [Development, staging, and production environments]
- **Configuration Management:** [Configuration and secrets management]

---

## Operations Guide

### Deployment Architecture
- **Deployment Strategy:** [Blue-green, canary, rolling deployments]
- **Infrastructure Requirements:** [Hardware, network, and storage requirements]
- **Scalability Configuration:** [Auto-scaling and load balancing setup]
- **Environment Management:** [Multiple environment configuration]

### Monitoring and Observability
- **Metrics Collection:** [System and application metrics]
- **Logging Strategy:** [Centralized logging and log management]
- **Distributed Tracing:** [Request tracing and performance monitoring]
- **Alerting:** [Alert rules and notification channels]

### Maintenance and Evolution
- **Architecture Evolution:** [How architecture will evolve over time]
- **Component Lifecycle:** [Component upgrade and retirement process]
- **Technology Updates:** [Framework and library update strategy]
- **Legacy Migration:** [Migration from legacy systems]

### Troubleshooting Guide
- **Common Issues:** [Frequent problems and their solutions]
- **Diagnostic Tools:** [Tools and techniques for problem diagnosis]
- **Performance Troubleshooting:** [Performance issue investigation]
- **Security Incident Response:** [Security incident handling procedures]

### Backup and Recovery
- **Backup Strategy:** [Data backup and recovery procedures]
- **Disaster Recovery:** [Disaster recovery planning and testing]
- **Business Continuity:** [Business continuity planning]
- **Recovery Testing:** [Regular recovery testing and validation]

---

## Architecture Validation

### Completeness Assessment
- **Architecture Coverage:** [Percentage of requirements covered by architecture]
- **Component Completeness:** [All required components defined]
- **Integration Completeness:** [All integrations designed and documented]
- **Quality Attribute Coverage:** [All quality requirements addressed]

### Consistency Analysis
- **Cross-Document Consistency:** [Consistency between architecture documents]
- **Interface Consistency:** [Consistent interface definitions]
- **Pattern Consistency:** [Consistent use of architectural patterns]
- **Naming Consistency:** [Consistent naming conventions]

### Gap Analysis
- **Missing Components:** [Components not yet defined or designed]
- **Incomplete Specifications:** [Specifications requiring additional detail]
- **Unaddressed Requirements:** [Requirements not covered by architecture]
- **Integration Gaps:** [Missing integration points or specifications]

### Quality Assessment
- **Architecture Quality:** [Overall architecture quality assessment]
- **Best Practices Adherence:** [Adherence to architectural best practices]
- **Pattern Usage:** [Appropriate use of architectural patterns]
- **Documentation Quality:** [Quality and completeness of documentation]

---

## Recommendations

### Immediate Actions
1. **Architecture Review:** [Conduct formal architecture review with stakeholders]
2. **Gap Resolution:** [Address identified gaps and incomplete specifications]
3. **Stakeholder Approval:** [Obtain stakeholder approval for architecture]
4. **Implementation Planning:** [Create detailed implementation plan]

### Implementation Priorities
1. **Critical Path:** [Focus on critical path components first]
2. **Risk Mitigation:** [Prioritize high-risk components for early validation]
3. **Value Delivery:** [Prioritize components that deliver early business value]
4. **Foundation First:** [Build foundational components before advanced features]

### Long-term Considerations
1. **Architecture Evolution:** [Plan for architecture evolution and growth]
2. **Technology Refresh:** [Consider technology refresh cycles]
3. **Team Growth:** [Plan for team growth and knowledge transfer]
4. **Market Changes:** [Adapt architecture to changing market conditions]

---

## Appendices

### A. Architecture Diagrams
[Comprehensive architecture diagrams and visual representations]

### B. Component Dependency Matrix
[Matrix showing component relationships and dependencies]

### C. API Specifications
[Detailed API specifications and documentation]

### D. Implementation Checklists
[Checklists for component implementation and integration]

### E. Quality Gates
[Quality gates and acceptance criteria for architecture phases]

### F. Reference Architecture
[Links to reference architectures and best practices]

### G. Glossary
[Architectural terms and definitions]

---

## Document Control

### Version History
- **Version 1.0:** [Initial architecture summary creation]
- **Version 1.1:** [First review and updates]
- **Version 1.2:** [Stakeholder feedback incorporation]

### Review and Approval
- **Technical Review:** [Technical review status and comments]
- **Stakeholder Review:** [Stakeholder review and approval status]
- **Architecture Board:** [Architecture board review and approval]

### Distribution
- **Primary Audience:** [Development teams, architects, technical leads]
- **Secondary Audience:** [Product managers, project managers, stakeholders]
- **Distribution Method:** [Document sharing and notification approach]

### Maintenance
- **Update Frequency:** [Regular update schedule and triggers]
- **Change Management:** [Process for architecture changes]
- **Version Control:** [Document version control and management]

Updated Session State Structure

{
  "index": 1,
  "name": "architecture-session-name",
  "type": "architecture",
  "status": "architecture_complete",
  "created": "ISO datetime",
  "lastUpdated": "ISO datetime",
  "currentStep": "architecture_summary",
  "completedSteps": ["architecture_framework_creation", "domain_analysis", "layer_design", "component_design", "integration_architecture", "architecture_summary"],
  "nextAction": "Ready for UI/UX design or implementation planning",
  "sourceType": "prd",
  "sourceName": "prd-session-name",
  "architectureScope": "system-wide",
  "architectureStyle": "layered",
  "architectureResults": {
    "domains": 3,
    "layers": 4,
    "components": 12,
    "componentSpecs": 12,
    "interfaces": 24,
    "integrationPatterns": 15,
    "apiSpecs": 8,
    "messageSchemas": 6,
    "patterns": 8,
    "qualityAttributes": 5,
    "decisions": 6,
    "completeness": 95,
    "consistency": 92,
    "quality": 88,
    "createdDate": "ISO datetime",
    "componentDesignDate": "ISO datetime",
    "integrationArchitectureDate": "ISO datetime",
    "architectureSummaryDate": "ISO datetime"
  }
}

Best Practices

✅ DO: Comprehensive Documentation

• Include all architecture components in the summary for complete coverage
• Maintain consistency across all architecture documents and references
• Use stakeholder-appropriate language for different audience sections
• Provide actionable guidance for implementation teams

Why: Comprehensive documentation ensures all stakeholders have the information they need to make informed decisions and take appropriate actions.

✅ DO: Multi-Audience Approach

• Create executive summaries for business stakeholders and decision-makers
• Provide technical details for architects and development teams
• Include implementation guidance for project managers and team leads
• Offer operational procedures for DevOps and operations teams

Why: Multi-audience approach ensures the architecture summary serves all stakeholders effectively and supports different decision-making needs.

✅ DO: Quality Assessment

• Assess architecture completeness and identify gaps or missing components
• Evaluate consistency across architecture documents and specifications
• Validate quality attributes and ensure requirements are met
• Provide recommendations for improvement and optimization

Why: Quality assessment ensures the architecture meets standards and provides a foundation for successful implementation.

❌ DON'T: Information Overload

• Don't include excessive technical details in executive summaries
• Don't create monolithic documents that are difficult to navigate
• Don't ignore stakeholder needs when structuring content
• Don't forget to highlight key decisions and their rationale

Why: Information overload reduces the effectiveness of the architecture summary and makes it harder for stakeholders to extract relevant information.

❌ DON'T: Inconsistent Information

• Don't allow inconsistencies between architecture documents
• Don't use different terminologies for the same concepts
• Don't omit important decisions or their rationale
• Don't ignore gaps or incomplete specifications

Why: Inconsistent information creates confusion and can lead to implementation problems and misaligned expectations.

Output

• Format: Comprehensive architecture summary with multiple stakeholder perspectives
• Location: .taskmaster/docs/design/architecture/[index]-[architecture_session_name]/
• Primary Files:
  • architecture-summary_[architecture_session_name].md - Main architecture summary document
  • _session-state.json - Updated session state with completion status
• Additional Formats: PDF, HTML, Confluence (if requested)

Example Usage

• Generate complete architecture summary: /design/system-architecture/4-generate-architecture-summary --name="enterprise-expansion"
• Generate executive summary only: /design/system-architecture/4-generate-architecture-summary --name="enterprise-expansion" --scope="executive"
• Generate with PDF output: /design/system-architecture/4-generate-architecture-summary --name="enterprise-expansion" --format="pdf"
• Generate by architecture index: /design/system-architecture/4-generate-architecture-summary --name="1"