From 5c2374c23b80a4ab71ba82cf2386bf9a39dddf5c Mon Sep 17 00:00:00 2001 From: "Paul.Kim" Date: Sun, 20 Jul 2025 22:56:18 +0900 Subject: [PATCH] =?UTF-8?q?docs:=20=EC=8B=9C=EC=8A=A4=ED=85=9C=20=EC=95=84?= =?UTF-8?q?=ED=82=A4=ED=85=8D=EC=B2=98=20=EB=B0=8F=20=EB=AA=85=EB=A0=B9?= =?UTF-8?q?=EC=96=B4=20=EB=AC=B8=EC=84=9C=20=EC=B6=94=EA=B0=80?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - COMMAND.md: 다양한 명령어와 설명 추가 - .claude/commands/design/1-system-architecture: 시스템 아키텍처 관련 문서 삭제 - .claude/commands/sc: 코드 분석, 빌드, 클린업, 설계, 문서화, 추정, 설명, Git 작업, 구현, 개선, 테스트, 문제 해결, 워크플로우 생성 등 다양한 명령어 문서 추가 --- .../1-create-architecture-framework.md | 524 -------- .../2-design-components.md | 785 ----------- .../3-integration-architecture.md | 1192 ----------------- .../4-generate-architecture-summary.md | 508 ------- .claude/commands/sc/analyze.md | 33 + .claude/commands/sc/build.md | 34 + .claude/commands/sc/cleanup.md | 34 + .claude/commands/sc/design.md | 33 + .claude/commands/sc/document.md | 33 + .claude/commands/sc/estimate.md | 33 + .claude/commands/sc/explain.md | 33 + .claude/commands/sc/git.md | 34 + .claude/commands/sc/implement.md | 54 + .claude/commands/sc/improve.md | 33 + .claude/commands/sc/index.md | 33 + .claude/commands/sc/load.md | 33 + .claude/commands/sc/spawn.md | 33 + .claude/commands/sc/task.md | 157 +++ .claude/commands/sc/test.md | 34 + .claude/commands/sc/troubleshoot.md | 33 + .claude/commands/sc/workflow.md | 303 +++++ COMMAND.md | 48 + 22 files changed, 1028 insertions(+), 3009 deletions(-) delete mode 100644 .claude/commands/design/1-system-architecture/1-create-architecture-framework.md delete mode 100644 .claude/commands/design/1-system-architecture/2-design-components.md delete mode 100644 .claude/commands/design/1-system-architecture/3-integration-architecture.md delete mode 100644 .claude/commands/design/1-system-architecture/4-generate-architecture-summary.md create mode 100644 .claude/commands/sc/analyze.md create mode 100644 .claude/commands/sc/build.md create mode 100644 .claude/commands/sc/cleanup.md create mode 100644 .claude/commands/sc/design.md create mode 100644 .claude/commands/sc/document.md create mode 100644 .claude/commands/sc/estimate.md create mode 100644 .claude/commands/sc/explain.md create mode 100644 .claude/commands/sc/git.md create mode 100644 .claude/commands/sc/implement.md create mode 100644 .claude/commands/sc/improve.md create mode 100644 .claude/commands/sc/index.md create mode 100644 .claude/commands/sc/load.md create mode 100644 .claude/commands/sc/spawn.md create mode 100644 .claude/commands/sc/task.md create mode 100644 .claude/commands/sc/test.md create mode 100644 .claude/commands/sc/troubleshoot.md create mode 100644 .claude/commands/sc/workflow.md create mode 100644 COMMAND.md diff --git a/.claude/commands/design/1-system-architecture/1-create-architecture-framework.md b/.claude/commands/design/1-system-architecture/1-create-architecture-framework.md deleted file mode 100644 index 28b5614..0000000 --- a/.claude/commands/design/1-system-architecture/1-create-architecture-framework.md +++ /dev/null @@ -1,524 +0,0 @@ ---- -allowed-tools: [Read, Write, Glob, TodoWrite] -description: Creates a comprehensive system architecture framework including domain separation, layered architecture, and component responsibility definitions. ---- - -# Create Architecture Framework - -## Context -- **User Request:** $ARGUMENTS -- **PRD Source:** Identified by `--prd` argument (PRD session name or index). -- **Source PRD:** Final PRD document from the specified PRD session directory. -- **Architecture Directory:** `.taskmaster/docs/design/architecture/` - -## Goal -To transform product requirements from a completed PRD into a comprehensive system architecture framework that defines domain boundaries, architectural layers, component responsibilities, and foundational patterns necessary for scalable and maintainable software development. - -## Process - -1. **Identify Source PRD Session:** - - Use the `--prd` argument to locate the correct PRD session directory (e.g., `.taskmaster/docs/prd/001-enterprise-expansion/`). - - Find the final PRD document (`product-requirements-document_*.md`) within the session directory. - -2. **Extract Architecture Requirements from PRD:** - - **Functional Requirements:** Core features and business capabilities - - **Non-Functional Requirements:** Performance, scalability, security, reliability - - **Technical Constraints:** Platform requirements, integration needs, compliance - - **User Experience Requirements:** Response time, availability, user load - - **Business Requirements:** Growth projections, market constraints, budget limitations - -3. **Determine Architecture Session Index:** - - Scan the `.taskmaster/docs/design/architecture/` directory to find the highest existing session index. - - Assign the next sequential number for the new architecture session. - -4. **Create Architecture Session Directory:** - - Create a new directory named `[index]-[prd_session_name]` inside `.taskmaster/docs/design/architecture/`. - - Example: `.taskmaster/docs/design/architecture/001-enterprise-expansion/` - -5. **Initialize Architecture Session State:** - - Create a `_session-state.json` file in the new architecture session directory. - - Initialize it with architecture session details: - ```json - { - "index": 1, - "name": "prd-session-name", - "type": "architecture", - "status": "initialized", - "created": "ISO datetime", - "lastUpdated": "ISO datetime", - "currentStep": "architecture_framework_creation", - "completedSteps": [], - "nextAction": "Generate comprehensive architecture framework", - "sourceType": "prd", - "sourceName": "prd-session-name", - "architectureScope": "system-wide|domain-specific|service-specific", - "architectureStyle": "layered|microservices|event-driven|hybrid", - "architectureResults": {} - } - ``` - -6. **Perform Domain Analysis:** - - **Domain Identification:** Identify business domains and bounded contexts from PRD features - - **Domain Modeling:** Create domain models and understand domain relationships - - **Bounded Context Mapping:** Define context boundaries and integration patterns - - **Domain Events:** Identify key domain events and workflows - - **Subdomain Classification:** Classify subdomains as core, supporting, or generic - -7. **Design Layered Architecture:** - - **Presentation Layer:** User interface, API endpoints, controllers - - **Application Layer:** Application services, use cases, workflow orchestration - - **Domain Layer:** Domain entities, value objects, domain services, aggregates - - **Infrastructure Layer:** Data access, external services, technical concerns - - **Cross-Cutting Concerns:** Logging, security, monitoring, configuration - -8. **Define Component Responsibilities:** - - **Component Identification:** Identify major system components and modules - - **Responsibility Assignment:** Define clear responsibilities for each component - - **Interface Design:** Design component interfaces and contracts - - **Dependency Management:** Establish dependency rules and patterns - - **Component Interaction:** Define communication patterns between components - -9. **Generate Architecture Framework Document:** - - Create the primary architecture document named `architecture-framework_[prd_session_name].md`. - - Structure content according to the architecture framework template. - - Include: - - **Architecture Overview:** High-level architecture vision and principles - - **Domain Architecture:** Domain boundaries and context mapping - - **Layered Architecture:** Layer definitions and responsibilities - - **Component Architecture:** Component design and interfaces - - **Architecture Patterns:** Key architectural patterns and decisions - - **Quality Attributes:** Architecture support for quality requirements - -10. **Update Session State:** - - Set `status` to `framework_complete`. - - Update `architectureResults` with architecture metrics and components. - - Record completion timestamp. - -11. **Notify User with Architecture Insights:** - - Inform the user that the architecture framework has been successfully generated. - - Provide the file path and key architectural highlights. - - **Suggest logical next steps based on framework outcomes:** - - "Your architecture framework is complete. Consider designing detailed components using `/design/system-architecture/2-design-components --name=[session_name]`" - - "Review the domain boundaries with your team to validate business alignment." - - "Use the layered architecture to guide development team organization and responsibilities." - -## Templates & Structures - -### Architecture Framework Template -```markdown -# System Architecture Framework: [PRD Session Name] - -**Created:** [Date] -**Source:** PRD Session: [PRD Session Name] -**Architecture Style:** [Layered/Microservices/Event-Driven/Hybrid] -**Target Scale:** [Small/Medium/Large/Enterprise] -**Last Updated:** [Date] - ---- - -## Architecture Overview - -### Architecture Vision -- **Vision Statement:** [Clear architectural vision aligned with business goals] -- **Architecture Principles:** [Fundamental principles guiding architectural decisions] -- **Design Philosophy:** [Overall approach to system design and evolution] -- **Success Criteria:** [How architectural success will be measured] - -### Architecture Drivers -- **Business Drivers:** [Key business requirements driving architecture] -- **Technical Drivers:** [Technical requirements and constraints] -- **Quality Drivers:** [Quality attributes and non-functional requirements] -- **Constraint Drivers:** [Platform, budget, time, and regulatory constraints] - -### Architecture Characteristics -- **Scalability:** [Horizontal and vertical scaling approach] -- **Reliability:** [Fault tolerance and resilience patterns] -- **Performance:** [Performance targets and optimization strategies] -- **Security:** [Security architecture and protection mechanisms] -- **Maintainability:** [Code organization and maintenance strategies] - ---- - -## Domain Architecture - -### Domain Identification -#### Core Domain: [Primary Business Domain] -- **Description:** [What this domain represents in the business] -- **Key Entities:** [Main business entities and concepts] -- **Business Rules:** [Critical business rules and constraints] -- **Value Proposition:** [How this domain creates business value] - -#### Supporting Domain: [Secondary Business Domain] -- **Description:** [What this domain represents in the business] -- **Key Entities:** [Main business entities and concepts] -- **Business Rules:** [Critical business rules and constraints] -- **Value Proposition:** [How this domain supports core business] - -#### Generic Domain: [Utility Domain] -- **Description:** [What this domain represents in the business] -- **Key Entities:** [Main business entities and concepts] -- **Business Rules:** [Critical business rules and constraints] -- **Value Proposition:** [How this domain provides utility] - -### Bounded Context Mapping -#### Context 1: [Context Name] -- **Responsibility:** [What this context is responsible for] -- **Boundaries:** [Clear boundaries and what's included/excluded] -- **Interfaces:** [How this context exposes its capabilities] -- **Dependencies:** [Other contexts this depends on] - -#### Context 2: [Context Name] -- **Responsibility:** [What this context is responsible for] -- **Boundaries:** [Clear boundaries and what's included/excluded] -- **Interfaces:** [How this context exposes its capabilities] -- **Dependencies:** [Other contexts this depends on] - -### Domain Events -- **Event 1:** [Event Name] - [When it occurs and what it represents] -- **Event 2:** [Event Name] - [When it occurs and what it represents] -- **Event 3:** [Event Name] - [When it occurs and what it represents] - -### Context Integration Patterns -- **Shared Kernel:** [Shared models and libraries between contexts] -- **Customer-Supplier:** [Upstream/downstream relationships] -- **Conformist:** [One context conforms to another's model] -- **Anti-Corruption Layer:** [Protection against external models] - ---- - -## Layered Architecture - -### Presentation Layer -#### Responsibility -- User interface components and user interaction handling -- API endpoints and request/response handling -- Input validation and output formatting -- User authentication and session management - -#### Components -- **Web Controllers:** [REST API controllers and request handlers] -- **UI Components:** [User interface components and views] -- **API Gateways:** [API gateway and routing logic] -- **Authentication Middleware:** [Authentication and authorization components] - -#### Design Patterns -- **MVC Pattern:** [Model-View-Controller for web interfaces] -- **API Gateway Pattern:** [Centralized API management] -- **Frontend-Backend Separation:** [Clear separation of concerns] - -### Application Layer -#### Responsibility -- Application services and use case orchestration -- Business workflow coordination -- Transaction management -- Application-specific business logic - -#### Components -- **Application Services:** [Use case implementations and workflow coordination] -- **Command Handlers:** [Command pattern implementations] -- **Query Handlers:** [Query pattern implementations] -- **Workflow Orchestrators:** [Business process coordination] - -#### Design Patterns -- **Command Query Responsibility Segregation (CQRS):** [Separate read/write operations] -- **Mediator Pattern:** [Request/response handling] -- **Unit of Work Pattern:** [Transaction management] - -### Domain Layer -#### Responsibility -- Core business logic and domain rules -- Domain entities and value objects -- Domain services and aggregates -- Business invariants and constraints - -#### Components -- **Domain Entities:** [Core business objects with identity] -- **Value Objects:** [Immutable objects representing concepts] -- **Domain Services:** [Business logic that doesn't belong to entities] -- **Aggregates:** [Consistency boundaries and transaction scopes] -- **Domain Events:** [Business events and event handlers] - -#### Design Patterns -- **Domain-Driven Design (DDD):** [Domain modeling and bounded contexts] -- **Repository Pattern:** [Data access abstraction] -- **Factory Pattern:** [Complex object creation] -- **Strategy Pattern:** [Business rule variations] - -### Infrastructure Layer -#### Responsibility -- Data persistence and external service integration -- Technical infrastructure and cross-cutting concerns -- Framework and technology-specific implementations -- System integration and communication - -#### Components -- **Data Access Layer:** [Database access and ORM implementations] -- **External Service Clients:** [Third-party service integrations] -- **Message Brokers:** [Asynchronous communication infrastructure] -- **Configuration Management:** [Application configuration and settings] - -#### Design Patterns -- **Repository Pattern:** [Data access abstraction] -- **Adapter Pattern:** [External service integration] -- **Decorator Pattern:** [Cross-cutting concerns] - ---- - -## Component Architecture - -### Component Identification -#### Component 1: [Component Name] -- **Purpose:** [What this component does and why it exists] -- **Responsibilities:** [Specific responsibilities and capabilities] -- **Interfaces:** [Public interfaces and contracts] -- **Dependencies:** [Other components this depends on] -- **Technology:** [Technology stack and frameworks] - -#### Component 2: [Component Name] -- **Purpose:** [What this component does and why it exists] -- **Responsibilities:** [Specific responsibilities and capabilities] -- **Interfaces:** [Public interfaces and contracts] -- **Dependencies:** [Other components this depends on] -- **Technology:** [Technology stack and frameworks] - -### Component Interaction Patterns -- **Synchronous Communication:** [REST APIs, direct method calls] -- **Asynchronous Communication:** [Message queues, event streams] -- **Data Sharing:** [Shared databases, data stores] -- **Service Discovery:** [How components find each other] - -### Component Deployment -- **Deployment Units:** [How components are packaged and deployed] -- **Scalability:** [How components scale independently] -- **Fault Isolation:** [How component failures are contained] -- **Monitoring:** [How components are monitored and observed] - ---- - -## Architecture Patterns - -### Architectural Style -- **Primary Style:** [Layered/Microservices/Event-Driven/Hybrid] -- **Style Rationale:** [Why this style was chosen] -- **Style Benefits:** [Benefits this style provides] -- **Style Trade-offs:** [Trade-offs and limitations] - -### Key Patterns -#### Pattern 1: [Pattern Name] -- **Problem:** [What problem this pattern solves] -- **Solution:** [How the pattern addresses the problem] -- **Implementation:** [How this pattern is implemented] -- **Benefits:** [Benefits of using this pattern] -- **Trade-offs:** [Costs and limitations] - -#### Pattern 2: [Pattern Name] -- **Problem:** [What problem this pattern solves] -- **Solution:** [How the pattern addresses the problem] -- **Implementation:** [How this pattern is implemented] -- **Benefits:** [Benefits of using this pattern] -- **Trade-offs:** [Costs and limitations] - -### Integration Patterns -- **API Gateway:** [Centralized API management and routing] -- **Service Mesh:** [Service-to-service communication] -- **Event Sourcing:** [Event-driven state management] -- **CQRS:** [Command Query Responsibility Segregation] - ---- - -## Quality Attributes - -### Performance Architecture -- **Response Time:** [Target response times and performance budgets] -- **Throughput:** [Expected transaction volumes and capacity] -- **Resource Usage:** [Memory, CPU, and storage considerations] -- **Caching Strategy:** [Caching layers and invalidation policies] - -### Scalability Architecture -- **Horizontal Scaling:** [Scale-out capabilities and patterns] -- **Vertical Scaling:** [Scale-up capabilities and limitations] -- **Auto-scaling:** [Automatic scaling triggers and policies] -- **Load Distribution:** [Load balancing and traffic distribution] - -### Reliability Architecture -- **Fault Tolerance:** [Failure handling and recovery patterns] -- **Resilience Patterns:** [Circuit breakers, retries, timeouts] -- **Backup and Recovery:** [Data backup and disaster recovery] -- **High Availability:** [Redundancy and failover mechanisms] - -### Security Architecture -- **Authentication:** [User authentication and identity management] -- **Authorization:** [Access control and permission management] -- **Data Protection:** [Encryption and data privacy] -- **Security Monitoring:** [Threat detection and response] - -### Maintainability Architecture -- **Code Organization:** [Module structure and dependency management] -- **Testing Strategy:** [Testing architecture and automation] -- **Documentation:** [Architecture documentation and knowledge management] -- **Evolution:** [Architecture evolution and refactoring strategies] - ---- - -## Architecture Decisions - -### Decision 1: [Decision Topic] -- **Context:** [Situation requiring a decision] -- **Decision:** [What was decided] -- **Rationale:** [Why this decision was made] -- **Consequences:** [Impact and implications] -- **Alternatives:** [Other options considered] - -### Decision 2: [Decision Topic] -- **Context:** [Situation requiring a decision] -- **Decision:** [What was decided] -- **Rationale:** [Why this decision was made] -- **Consequences:** [Impact and implications] -- **Alternatives:** [Other options considered] - ---- - -## Implementation Guidance - -### Development Approach -- **Development Methodology:** [Agile, incremental, iterative approach] -- **Team Organization:** [How teams align with architecture] -- **Technology Standards:** [Coding standards and technology guidelines] -- **Quality Practices:** [Code review, testing, and quality assurance] - -### Architecture Governance -- **Architecture Review:** [Architecture review process and criteria] -- **Change Management:** [How architecture changes are managed] -- **Compliance:** [Architecture compliance and enforcement] -- **Evolution:** [Architecture evolution and improvement] - -### Risk Management -- **Technical Risks:** [Key technical risks and mitigation strategies] -- **Architecture Risks:** [Architecture-specific risks and responses] -- **Integration Risks:** [Component integration and system risks] -- **Performance Risks:** [Performance and scalability risks] - ---- - -## Next Steps - -### Immediate Actions -1. **Component Design:** [Design detailed component specifications] -2. **Integration Planning:** [Plan component integration and communication] -3. **Technology Selection:** [Select specific technologies and frameworks] -4. **Prototype Development:** [Develop architecture proof-of-concept] - -### Architecture Validation -- **Architecture Review:** [Conduct formal architecture review] -- **Stakeholder Alignment:** [Ensure stakeholder agreement and buy-in] -- **Technical Validation:** [Validate technical feasibility and approach] -- **Risk Assessment:** [Assess and mitigate architecture risks] - -### Development Preparation -- **Team Preparation:** [Prepare development teams for implementation] -- **Environment Setup:** [Set up development and testing environments] -- **Tooling Selection:** [Select development tools and frameworks] -- **Documentation:** [Create detailed implementation documentation] - ---- - -## Appendices - -### A. PRD Requirements Analysis -[Summary of PRD requirements and their architectural implications] - -### B. Architecture Diagrams -[High-level architecture diagrams and component relationships] - -### C. Technology Evaluation -[Technology evaluation criteria and selection rationale] - -### D. Performance Modeling -[Performance projections and capacity planning] - -### E. Security Assessment -[Security requirements and threat modeling] -``` - -### Session State Structure -```json -{ - "index": 1, - "name": "prd-session-name", - "type": "architecture", - "status": "framework_complete", - "created": "ISO datetime", - "lastUpdated": "ISO datetime", - "currentStep": "framework_complete", - "completedSteps": ["architecture_framework_creation", "domain_analysis", "layer_design"], - "nextAction": "Ready for component design or integration architecture", - "sourceType": "prd", - "sourceName": "prd-session-name", - "architectureScope": "system-wide", - "architectureStyle": "layered", - "architectureResults": { - "domains": 3, - "layers": 4, - "components": 12, - "patterns": 8, - "qualityAttributes": 5, - "decisions": 6, - "createdDate": "ISO datetime" - } -} -``` - -## Best Practices - -### ✅ DO: Requirements-Driven Architecture -- **Start with PRD requirements** and ensure architecture serves business needs -- **Prioritize quality attributes** based on business priorities and user needs -- **Consider growth and evolution** when designing architectural foundations -- **Balance flexibility with simplicity** to avoid over-engineering - -**Why:** Requirements-driven architecture ensures that architectural decisions support business objectives and user value. - -### ✅ DO: Domain-Driven Design -- **Identify clear domain boundaries** and model business concepts accurately -- **Use ubiquitous language** that bridges business and technical teams -- **Separate core domains** from supporting and generic domains -- **Design for domain evolution** and changing business requirements - -**Why:** Domain-driven design creates architecture that reflects business reality and can evolve with business needs. - -### ✅ DO: Layered Responsibility -- **Maintain clear layer separation** with well-defined responsibilities -- **Follow dependency rules** to ensure proper architectural flow -- **Avoid layer violations** and maintain architectural integrity -- **Design clean interfaces** between layers and components - -**Why:** Layered responsibility creates maintainable, testable, and evolvable architecture. - -### ❌ DON'T: Technology-First Architecture -- **Don't start with technology choices** before understanding requirements -- **Don't let technology constraints** drive architectural decisions -- **Don't ignore business requirements** in favor of technical preferences -- **Don't create architecture** that serves technology rather than business - -**Why:** Technology-first architecture often results in solutions that don't meet business needs or user requirements. - -### ❌ DON'T: Premature Optimization -- **Don't optimize for performance** before understanding actual requirements -- **Don't add complexity** for theoretical future needs -- **Don't over-engineer** solutions beyond current requirements -- **Don't ignore simplicity** in favor of sophisticated patterns - -**Why:** Premature optimization creates unnecessary complexity and can hinder business agility and development velocity. - -## Output -- **Format:** Comprehensive architecture framework with domain and layer design -- **Location:** `.taskmaster/docs/design/architecture/[index]-[prd_session_name]/` -- **Primary Files:** - - `architecture-framework_[prd_session_name].md` - Main architecture framework - - `_session-state.json` - Session tracking and metadata - -## Example Usage -- **Create architecture framework from PRD:** - `/design/system-architecture/1-create-architecture-framework --prd="enterprise-expansion"` -- **Create by PRD index:** - `/design/system-architecture/1-create-architecture-framework --prd="1"` \ No newline at end of file diff --git a/.claude/commands/design/1-system-architecture/2-design-components.md b/.claude/commands/design/1-system-architecture/2-design-components.md deleted file mode 100644 index 404006b..0000000 --- a/.claude/commands/design/1-system-architecture/2-design-components.md +++ /dev/null @@ -1,785 +0,0 @@ ---- -allowed-tools: [Read, Write, Glob, TodoWrite] -description: Designs detailed system components with specifications, interfaces, and implementation guidelines based on architecture framework. ---- - -# Design Components - -## Context -- **User Request:** $ARGUMENTS -- **Architecture Session:** Identified by `--name` argument (architecture session name or index). -- **Source Architecture:** Architecture framework document from the specified architecture session directory. -- **Component Selection:** Optional `--components` argument to focus on specific components. -- **Design Directory:** `.taskmaster/docs/design/architecture/` - -## Goal -To transform the high-level architecture framework into detailed component specifications that define interfaces, responsibilities, implementation patterns, and integration contracts necessary for development teams to build robust, maintainable software components. - -## 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 the architecture framework document (`architecture-framework_*.md`) within the session directory. - -2. **Extract Component Requirements from Architecture:** - - **Component Identification:** Components identified in the architecture framework - - **Layer Assignments:** Which architectural layer each component belongs to - - **Domain Boundaries:** Domain context and bounded context for each component - - **Quality Attributes:** Performance, security, scalability requirements per component - - **Integration Points:** How components interact with each other - -3. **Process Component Selection (if specified):** - - If `--components` argument is provided, focus on specific components only - - Parse comma-separated component names or indices - - Validate that specified components exist in the architecture framework - -4. **Perform Component Analysis:** - - **Responsibility Definition:** Clear definition of what each component does - - **Interface Design:** Public APIs, contracts, and communication protocols - - **Dependency Analysis:** Dependencies on other components and external systems - - **Data Flow Analysis:** How data flows through and between components - - **Error Handling:** Error handling strategies and fault tolerance patterns - -5. **Design Component Specifications:** - - **Component Architecture:** Internal structure and sub-components - - **Interface Contracts:** Detailed API specifications and data models - - **Implementation Patterns:** Recommended design patterns and practices - - **Technology Guidelines:** Technology stack and framework recommendations - - **Testing Strategy:** Unit, integration, and contract testing approaches - -6. **Generate Component Design Document:** - - Create the component design document named `component-design_[architecture_session_name].md`. - - Structure content according to the component design template. - - Include: - - **Component Overview:** High-level component landscape and relationships - - **Component Specifications:** Detailed specifications for each component - - **Interface Definitions:** API contracts and communication protocols - - **Implementation Guidelines:** Development patterns and best practices - - **Integration Patterns:** Component interaction and communication patterns - - **Quality Assurance:** Testing and validation approaches - -7. **Create Component Interface Specifications:** - - Generate individual interface specification files for complex components - - Create API documentation and contract definitions - - Define data models and schema specifications - - Document error handling and exception patterns - -8. **Update Architecture Session State:** - - Update the existing `_session-state.json` file in the architecture session directory. - - Add component design completion status and results. - - Update `completedSteps` and `nextAction` fields. - -9. **Notify User with Component Insights:** - - Inform the user that the component design has been successfully generated. - - Provide file paths and key component highlights. - - **Suggest logical next steps based on component design:** - - "Your component design is complete. Consider defining integration architecture using `/design/system-architecture/3-integration-architecture --name=[session_name]`" - - "Review the component interfaces with your development teams to ensure implementation feasibility." - - "Use the component specifications to create detailed development tasks and sprint planning." - -## Templates & Structures - -### Component Design Template -```markdown -# Component Design: [Architecture Session Name] - -**Created:** [Date] -**Source:** Architecture Framework: [Architecture Session Name] -**Component Scope:** [All Components / Specific Components] -**Target Components:** [List of components if specific scope] -**Last Updated:** [Date] - ---- - -## Component Overview - -### System Component Landscape -- **Total Components:** [Number of components in the system] -- **Layer Distribution:** [Number of components per architectural layer] -- **Domain Distribution:** [Number of components per domain] -- **Integration Complexity:** [Assessment of component integration complexity] - -### Component Relationships -- **Core Components:** [Components that are central to system functionality] -- **Supporting Components:** [Components that support core functionality] -- **Infrastructure Components:** [Components that provide technical infrastructure] -- **Integration Components:** [Components that handle external integrations] - -### Component Dependencies -- **High-Level Dependencies:** [Major dependency relationships between components] -- **Circular Dependencies:** [Any circular dependencies and resolution strategies] -- **External Dependencies:** [Dependencies on external systems and services] - ---- - -## Component Specifications - -### Presentation Layer Components - -#### Component 1: [Component Name] -**Layer:** Presentation -**Domain:** [Domain Context] -**Responsibility:** [Primary responsibility and purpose] - -##### Architecture -- **Component Type:** [Controller/Gateway/UI Component/API Handler] -- **Deployment Unit:** [How this component is deployed] -- **Scalability:** [Horizontal/Vertical scaling characteristics] -- **State Management:** [Stateless/Stateful and state handling approach] - -##### Responsibilities -- **Primary Responsibility:** [Main function of this component] -- **Secondary Responsibilities:** [Additional functions and capabilities] -- **Business Rules:** [Business logic handled by this component] -- **Data Transformation:** [Data processing and transformation responsibilities] - -##### Interface Definition -```typescript -// Public Interface -interface ComponentName { - // Core Methods - methodName(request: RequestType): Promise; - - // Event Handlers - onEvent(event: EventType): void; - - // Lifecycle Methods - initialize(): Promise; - shutdown(): Promise; -} - -// Request/Response Types -interface RequestType { - // Request structure -} - -interface ResponseType { - // Response structure -} -``` - -##### Dependencies -- **Required Dependencies:** [Components this depends on] -- **Optional Dependencies:** [Components this can optionally use] -- **External Dependencies:** [External services and systems] -- **Infrastructure Dependencies:** [Databases, message queues, etc.] - -##### Data Flow -- **Input Data:** [Data received from other components or external sources] -- **Output Data:** [Data produced and sent to other components] -- **Data Transformation:** [How data is processed and transformed] -- **Data Validation:** [Input validation and sanitization] - -##### Error Handling -- **Error Types:** [Types of errors this component can encounter] -- **Error Handling Strategy:** [How errors are handled and propagated] -- **Retry Logic:** [Retry mechanisms and policies] -- **Fallback Mechanisms:** [Fallback strategies for failures] - -##### Quality Attributes -- **Performance:** [Performance requirements and optimization strategies] -- **Security:** [Security requirements and implementation approach] -- **Reliability:** [Reliability requirements and fault tolerance] -- **Maintainability:** [Code organization and maintenance considerations] - -##### Testing Strategy -- **Unit Testing:** [Unit testing approach and coverage] -- **Integration Testing:** [Integration testing strategy] -- **Contract Testing:** [API contract testing approach] -- **Performance Testing:** [Performance testing requirements] - -##### Implementation Guidelines -- **Design Patterns:** [Recommended design patterns] -- **Technology Stack:** [Recommended technologies and frameworks] -- **Code Organization:** [Code structure and organization guidelines] -- **Configuration:** [Configuration management approach] - -### Application Layer Components - -#### Component 2: [Component Name] -**Layer:** Application -**Domain:** [Domain Context] -**Responsibility:** [Primary responsibility and purpose] - -##### Architecture -- **Component Type:** [Application Service/Command Handler/Query Handler/Orchestrator] -- **Deployment Unit:** [How this component is deployed] -- **Scalability:** [Horizontal/Vertical scaling characteristics] -- **State Management:** [Stateless/Stateful and state handling approach] - -##### Responsibilities -- **Primary Responsibility:** [Main function of this component] -- **Secondary Responsibilities:** [Additional functions and capabilities] -- **Business Rules:** [Business logic handled by this component] -- **Workflow Coordination:** [Business process coordination responsibilities] - -##### Interface Definition -```typescript -// Application Service Interface -interface ApplicationService { - // Use Case Methods - executeUseCase(command: CommandType): Promise; - - // Query Methods - handleQuery(query: QueryType): Promise; - - // Workflow Methods - coordinateWorkflow(workflow: WorkflowType): Promise; -} - -// Command/Query Types -interface CommandType { - // Command structure -} - -interface QueryType { - // Query structure -} -``` - -##### Dependencies -- **Domain Dependencies:** [Domain services and repositories] -- **Infrastructure Dependencies:** [Data access and external services] -- **Cross-Cutting Dependencies:** [Logging, monitoring, configuration] - -##### Data Flow -- **Command Processing:** [How commands are processed] -- **Query Processing:** [How queries are handled] -- **Event Publishing:** [Events published by this component] -- **Data Persistence:** [Data storage and retrieval patterns] - -##### Error Handling -- **Business Rule Violations:** [How business rule violations are handled] -- **Infrastructure Failures:** [How infrastructure failures are managed] -- **Transaction Management:** [Transaction handling and rollback strategies] -- **Compensation Patterns:** [Compensation actions for failures] - -##### Quality Attributes -- **Performance:** [Performance requirements and optimization strategies] -- **Security:** [Security requirements and implementation approach] -- **Reliability:** [Reliability requirements and fault tolerance] -- **Maintainability:** [Code organization and maintenance considerations] - -##### Testing Strategy -- **Unit Testing:** [Unit testing approach and coverage] -- **Integration Testing:** [Integration testing strategy] -- **Business Logic Testing:** [Business rule testing approach] -- **End-to-End Testing:** [End-to-end testing requirements] - -##### Implementation Guidelines -- **Design Patterns:** [CQRS, Mediator, Unit of Work, etc.] -- **Technology Stack:** [Recommended technologies and frameworks] -- **Code Organization:** [Code structure and organization guidelines] -- **Transaction Management:** [Transaction handling guidelines] - -### Domain Layer Components - -#### Component 3: [Component Name] -**Layer:** Domain -**Domain:** [Domain Context] -**Responsibility:** [Primary responsibility and purpose] - -##### Architecture -- **Component Type:** [Domain Service/Entity/Value Object/Aggregate] -- **Deployment Unit:** [How this component is deployed] -- **Scalability:** [Horizontal/Vertical scaling characteristics] -- **State Management:** [State handling and persistence approach] - -##### Responsibilities -- **Primary Responsibility:** [Main function of this component] -- **Business Rules:** [Core business rules and invariants] -- **Domain Logic:** [Domain-specific business logic] -- **Data Integrity:** [Data consistency and validation responsibilities] - -##### Interface Definition -```typescript -// Domain Service Interface -interface DomainService { - // Business Logic Methods - performBusinessOperation(params: BusinessParams): BusinessResult; - - // Validation Methods - validateBusinessRules(entity: EntityType): ValidationResult; - - // Calculation Methods - calculateBusinessValue(input: InputType): CalculationResult; -} - -// Domain Types -interface BusinessParams { - // Business parameter structure -} - -interface BusinessResult { - // Business result structure -} -``` - -##### Dependencies -- **Domain Dependencies:** [Other domain services and entities] -- **Infrastructure Dependencies:** [Repository interfaces] -- **External Dependencies:** [External domain services if any] - -##### Data Flow -- **Entity Lifecycle:** [How entities are created, modified, and destroyed] -- **Business Events:** [Domain events generated by this component] -- **Validation Flow:** [How business rules are validated] -- **State Transitions:** [Valid state transitions and constraints] - -##### Error Handling -- **Business Rule Violations:** [How business invariants are enforced] -- **Domain Exceptions:** [Domain-specific exceptions and handling] -- **Validation Failures:** [How validation failures are communicated] -- **Consistency Enforcement:** [How data consistency is maintained] - -##### Quality Attributes -- **Performance:** [Performance requirements and optimization strategies] -- **Security:** [Security requirements and implementation approach] -- **Reliability:** [Reliability requirements and fault tolerance] -- **Maintainability:** [Code organization and maintenance considerations] - -##### Testing Strategy -- **Unit Testing:** [Unit testing approach and coverage] -- **Domain Testing:** [Domain logic testing strategy] -- **Business Rule Testing:** [Business rule validation testing] -- **Integration Testing:** [Integration testing with repositories] - -##### Implementation Guidelines -- **Design Patterns:** [Domain-Driven Design patterns] -- **Technology Stack:** [Recommended technologies and frameworks] -- **Code Organization:** [Code structure and organization guidelines] -- **Business Rule Implementation:** [How to implement business rules] - -### Infrastructure Layer Components - -#### Component 4: [Component Name] -**Layer:** Infrastructure -**Domain:** [Domain Context] -**Responsibility:** [Primary responsibility and purpose] - -##### Architecture -- **Component Type:** [Repository/External Service Client/Message Handler/Data Access] -- **Deployment Unit:** [How this component is deployed] -- **Scalability:** [Horizontal/Vertical scaling characteristics] -- **State Management:** [Connection and resource management approach] - -##### Responsibilities -- **Primary Responsibility:** [Main function of this component] -- **Data Access:** [Data persistence and retrieval responsibilities] -- **External Integration:** [External service integration responsibilities] -- **Technical Concerns:** [Cross-cutting technical concerns] - -##### Interface Definition -```typescript -// Repository Interface -interface Repository { - // CRUD Operations - create(entity: T): Promise; - findById(id: string): Promise; - update(entity: T): Promise; - delete(id: string): Promise; - - // Query Operations - findBy(criteria: QueryCriteria): Promise; - exists(criteria: QueryCriteria): Promise; -} - -// External Service Interface -interface ExternalServiceClient { - // Service Operations - callService(request: ServiceRequest): Promise; - - // Health Check - healthCheck(): Promise; -} -``` - -##### Dependencies -- **Database Dependencies:** [Database systems and drivers] -- **External Service Dependencies:** [Third-party services and APIs] -- **Infrastructure Dependencies:** [Message queues, caches, etc.] -- **Configuration Dependencies:** [Configuration and secrets management] - -##### Data Flow -- **Data Access Patterns:** [How data is accessed and manipulated] -- **Connection Management:** [Database connection and pooling] -- **Error Handling:** [Database and service error handling] -- **Performance Optimization:** [Caching and optimization strategies] - -##### Error Handling -- **Database Errors:** [Database connection and query error handling] -- **External Service Errors:** [External service failure handling] -- **Network Errors:** [Network connectivity and timeout handling] -- **Resource Errors:** [Resource exhaustion and cleanup] - -##### Quality Attributes -- **Performance:** [Performance requirements and optimization strategies] -- **Security:** [Security requirements and implementation approach] -- **Reliability:** [Reliability requirements and fault tolerance] -- **Maintainability:** [Code organization and maintenance considerations] - -##### Testing Strategy -- **Unit Testing:** [Unit testing approach and coverage] -- **Integration Testing:** [Integration testing strategy] -- **Database Testing:** [Database testing approach] -- **External Service Testing:** [Service integration testing] - -##### Implementation Guidelines -- **Design Patterns:** [Repository, Adapter, Circuit Breaker, etc.] -- **Technology Stack:** [Recommended technologies and frameworks] -- **Code Organization:** [Code structure and organization guidelines] -- **Resource Management:** [Connection and resource management] - ---- - -## Interface Definitions - -### API Contracts - -#### REST API Specification -```yaml -# OpenAPI 3.0 Specification -openapi: 3.0.0 -info: - title: Component API - version: 1.0.0 - description: API specification for component interfaces - -paths: - /api/resource: - get: - summary: Get resource - parameters: - - name: id - in: query - required: true - schema: - type: string - responses: - '200': - description: Resource found - content: - application/json: - schema: - $ref: '#/components/schemas/Resource' - '404': - description: Resource not found - post: - summary: Create resource - requestBody: - required: true - content: - application/json: - schema: - $ref: '#/components/schemas/CreateResourceRequest' - responses: - '201': - description: Resource created - content: - application/json: - schema: - $ref: '#/components/schemas/Resource' - -components: - schemas: - Resource: - type: object - properties: - id: - type: string - name: - type: string - status: - type: string - enum: [active, inactive] - - CreateResourceRequest: - type: object - required: - - name - properties: - name: - type: string - description: - type: string -``` - -#### Message Contracts -```typescript -// Event Message Contracts -interface DomainEvent { - eventId: string; - eventType: string; - aggregateId: string; - aggregateType: string; - eventData: any; - timestamp: Date; - version: number; -} - -// Command Message Contracts -interface Command { - commandId: string; - commandType: string; - payload: any; - timestamp: Date; - userId: string; -} - -// Query Message Contracts -interface Query { - queryId: string; - queryType: string; - parameters: any; - timestamp: Date; - userId: string; -} -``` - -### Integration Protocols - -#### Synchronous Communication -- **HTTP/REST:** [RESTful API patterns and conventions] -- **gRPC:** [gRPC service definitions and protocols] -- **GraphQL:** [GraphQL schema and query patterns] - -#### Asynchronous Communication -- **Message Queues:** [Message queue patterns and protocols] -- **Event Streams:** [Event streaming patterns and schemas] -- **Publish-Subscribe:** [Pub/sub patterns and topic structures] - -#### Data Formats -- **JSON:** [JSON schema definitions and conventions] -- **Protocol Buffers:** [Protobuf definitions and usage] -- **Avro:** [Avro schema definitions and evolution] - ---- - -## Implementation Guidelines - -### Development Patterns - -#### Design Patterns by Layer -##### Presentation Layer -- **MVC Pattern:** [Model-View-Controller implementation] -- **API Gateway Pattern:** [Centralized API management] -- **Backend for Frontend (BFF):** [Client-specific backends] - -##### Application Layer -- **Command Query Responsibility Segregation (CQRS):** [Separate read/write operations] -- **Mediator Pattern:** [Request/response handling] -- **Unit of Work Pattern:** [Transaction management] - -##### Domain Layer -- **Domain-Driven Design (DDD):** [Domain modeling patterns] -- **Repository Pattern:** [Data access abstraction] -- **Factory Pattern:** [Complex object creation] -- **Strategy Pattern:** [Business rule variations] - -##### Infrastructure Layer -- **Repository Pattern:** [Data access implementation] -- **Adapter Pattern:** [External service integration] -- **Circuit Breaker Pattern:** [Fault tolerance] -- **Decorator Pattern:** [Cross-cutting concerns] - -### Technology Guidelines - -#### Programming Languages -- **Primary Language:** [Main programming language and rationale] -- **Secondary Languages:** [Additional languages for specific components] -- **Language Standards:** [Coding standards and conventions] - -#### Frameworks and Libraries -- **Web Framework:** [Web framework selection and configuration] -- **ORM Framework:** [Object-relational mapping framework] -- **Testing Framework:** [Testing framework and tools] -- **Logging Framework:** [Logging and monitoring framework] - -#### Development Tools -- **IDE Configuration:** [Development environment setup] -- **Build Tools:** [Build automation and dependency management] -- **Code Quality Tools:** [Static analysis and quality tools] -- **Version Control:** [Version control practices and branching] - -### Quality Assurance - -#### Testing Strategy -- **Unit Testing:** [Component-level testing approach] -- **Integration Testing:** [Component integration testing] -- **Contract Testing:** [API contract testing] -- **End-to-End Testing:** [System-level testing] - -#### Code Quality -- **Code Reviews:** [Code review process and standards] -- **Static Analysis:** [Static code analysis tools and rules] -- **Documentation:** [Code documentation standards] -- **Refactoring:** [Refactoring guidelines and practices] - -#### Performance -- **Performance Testing:** [Performance testing approach] -- **Profiling:** [Performance profiling and optimization] -- **Monitoring:** [Runtime monitoring and alerting] -- **Optimization:** [Performance optimization strategies] - ---- - -## Integration Patterns - -### Component Communication - -#### Synchronous Patterns -- **Direct Method Calls:** [In-process component communication] -- **HTTP APIs:** [RESTful API communication] -- **RPC Calls:** [Remote procedure call patterns] - -#### Asynchronous Patterns -- **Message Queues:** [Queue-based communication] -- **Event Streams:** [Event-driven communication] -- **Publish-Subscribe:** [Pub/sub communication patterns] - -#### Hybrid Patterns -- **Request-Response with Events:** [Combined synchronous/asynchronous] -- **Saga Pattern:** [Distributed transaction coordination] -- **Event Sourcing:** [Event-based state management] - -### Data Consistency - -#### Consistency Patterns -- **Strong Consistency:** [ACID transaction patterns] -- **Eventual Consistency:** [BASE transaction patterns] -- **Causal Consistency:** [Causal ordering patterns] - -#### Conflict Resolution -- **Last Write Wins:** [Conflict resolution strategy] -- **Merge Strategies:** [Data merge and conflict resolution] -- **Compensating Actions:** [Compensation patterns for failures] - ---- - -## Next Steps - -### Component Implementation -1. **Development Planning:** [Plan component development order and dependencies] -2. **Team Assignment:** [Assign development teams to components] -3. **Interface Implementation:** [Implement component interfaces first] -4. **Component Development:** [Develop component implementations] - -### Integration Planning -1. **Integration Architecture:** [Design component integration approach] -2. **Communication Protocols:** [Implement communication mechanisms] -3. **Data Flow Testing:** [Test data flow between components] -4. **End-to-End Testing:** [Test complete system integration] - -### Quality Assurance -1. **Testing Implementation:** [Implement testing strategy] -2. **Code Quality Setup:** [Set up code quality tools] -3. **Performance Testing:** [Implement performance testing] -4. **Security Testing:** [Implement security testing] - ---- - -## Appendices - -### A. Component Mapping Matrix -[Matrix showing component relationships and dependencies] - -### B. Interface Specifications -[Detailed interface specifications for each component] - -### C. Implementation Examples -[Code examples and implementation patterns] - -### D. Testing Examples -[Testing examples and test case specifications] - -### E. Performance Considerations -[Performance analysis and optimization guidelines] -``` - -### Updated Session State Structure -```json -{ - "index": 1, - "name": "architecture-session-name", - "type": "architecture", - "status": "component_design_complete", - "created": "ISO datetime", - "lastUpdated": "ISO datetime", - "currentStep": "component_design", - "completedSteps": ["architecture_framework_creation", "domain_analysis", "layer_design", "component_design"], - "nextAction": "Ready for integration architecture or summary generation", - "sourceType": "prd", - "sourceName": "prd-session-name", - "architectureScope": "system-wide", - "architectureStyle": "layered", - "architectureResults": { - "domains": 3, - "layers": 4, - "components": 12, - "componentSpecs": 12, - "interfaces": 24, - "patterns": 8, - "qualityAttributes": 5, - "decisions": 6, - "createdDate": "ISO datetime", - "componentDesignDate": "ISO datetime" - } -} -``` - -## Best Practices - -### ✅ DO: Interface-First Design -- **Define clear interfaces** before implementing component internals -- **Use contract-first approach** for API and message design -- **Maintain interface stability** and versioning strategies -- **Document interface contracts** comprehensively - -**Why:** Interface-first design enables parallel development, reduces integration issues, and improves system maintainability. - -### ✅ DO: Responsibility-Driven Design -- **Assign single responsibility** to each component -- **Define clear boundaries** between component responsibilities -- **Minimize coupling** between components -- **Maximize cohesion** within components - -**Why:** Responsibility-driven design creates maintainable, testable, and evolvable components. - -### ✅ DO: Quality-Driven Implementation -- **Define quality requirements** for each component -- **Implement appropriate patterns** for quality attributes -- **Plan for testing** and quality assurance -- **Consider operational requirements** from the start - -**Why:** Quality-driven implementation ensures that components meet production requirements and performance expectations. - -### ❌ DON'T: Premature Implementation Details -- **Don't specify implementation details** too early in the design process -- **Don't couple components** to specific technologies unnecessarily -- **Don't ignore testing** and quality requirements -- **Don't forget operational concerns** like monitoring and deployment - -**Why:** Premature implementation details can constrain development flexibility and complicate system evolution. - -### ❌ DON'T: Monolithic Component Design -- **Don't create components** that are too large or complex -- **Don't mix concerns** within a single component -- **Don't ignore separation** of business and technical concerns -- **Don't create tight coupling** between unrelated components - -**Why:** Monolithic component design reduces maintainability, testability, and team productivity. - -## Output -- **Format:** Detailed component specifications with interfaces and guidelines -- **Location:** `.taskmaster/docs/design/architecture/[index]-[architecture_session_name]/` -- **Primary Files:** - - `component-design_[architecture_session_name].md` - Main component design document - - `_session-state.json` - Updated session state - -## Example Usage -- **Design all components from architecture:** - `/design/system-architecture/2-design-components --name="enterprise-expansion"` -- **Design specific components:** - `/design/system-architecture/2-design-components --name="enterprise-expansion" --components="UserService,PaymentService"` -- **Design by architecture index:** - `/design/system-architecture/2-design-components --name="1"` \ No newline at end of file diff --git a/.claude/commands/design/1-system-architecture/3-integration-architecture.md b/.claude/commands/design/1-system-architecture/3-integration-architecture.md deleted file mode 100644 index 31e3156..0000000 --- a/.claude/commands/design/1-system-architecture/3-integration-architecture.md +++ /dev/null @@ -1,1192 +0,0 @@ ---- -allowed-tools: [Read, Write, Glob, TodoWrite] -description: Designs system integration architecture including communication protocols, data flow, and service integration patterns. ---- - -# Integration Architecture - -## Context -- **User Request:** $ARGUMENTS -- **Architecture Session:** Identified by `--name` argument (architecture session name or index). -- **Source Documents:** Architecture framework and component design documents from the session directory. -- **Integration Scope:** Optional `--scope` argument to focus on specific integration areas. -- **Design Directory:** `.taskmaster/docs/design/architecture/` - -## Goal -To design comprehensive integration architecture that defines how system components communicate, share data, and coordinate operations, ensuring reliable, scalable, and maintainable inter-component and external system integration. - -## 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 the architecture framework document (`architecture-framework_*.md`) and component design document (`component-design_*.md`). - -2. **Extract Integration Requirements:** - - **Component Dependencies:** Component interaction patterns and dependencies - - **Data Flow Requirements:** Data sharing and synchronization needs - - **External Integrations:** Third-party services and system integrations - - **Communication Patterns:** Synchronous vs asynchronous communication needs - - **Quality Attributes:** Performance, reliability, and security requirements for integrations - -3. **Process Integration Scope (if specified):** - - If `--scope` argument is provided, focus on specific integration areas - - Supported scopes: `internal`, `external`, `data`, `messaging`, `api` - - Parse and validate scope parameters - -4. **Analyze Integration Patterns:** - - **Communication Analysis:** Identify optimal communication patterns for each interaction - - **Data Flow Analysis:** Design data flow and transformation patterns - - **Transaction Analysis:** Determine transaction boundaries and coordination patterns - - **Error Handling Analysis:** Design error propagation and recovery patterns - - **Security Analysis:** Define security requirements for each integration point - -5. **Design Integration Architecture:** - - **Communication Protocols:** Define protocols for component communication - - **API Design:** Design REST APIs, GraphQL schemas, and RPC interfaces - - **Messaging Architecture:** Design message queues, event streams, and pub/sub patterns - - **Data Integration:** Design data synchronization, ETL, and data flow patterns - - **Service Integration:** Design service discovery, load balancing, and circuit breaker patterns - -6. **Define Integration Contracts:** - - **API Contracts:** Define API specifications and data models - - **Message Contracts:** Define message formats and event schemas - - **Data Contracts:** Define data formats and transformation rules - - **Service Contracts:** Define service level agreements and quality metrics - -7. **Generate Integration Architecture Document:** - - Create the integration architecture document named `integration-architecture_[architecture_session_name].md`. - - Structure content according to the integration architecture template. - - Include: - - **Integration Overview:** High-level integration strategy and patterns - - **Communication Architecture:** Communication protocols and patterns - - **Data Integration Architecture:** Data flow and synchronization patterns - - **Service Integration Architecture:** Service discovery and coordination patterns - - **Security Architecture:** Security patterns and access control - - **Monitoring and Observability:** Integration monitoring and troubleshooting - -8. **Create Integration Specifications:** - - Generate detailed API specifications and documentation - - Create message schema definitions and event catalogs - - Define data transformation and mapping specifications - - Document integration testing and validation approaches - -9. **Update Architecture Session State:** - - Update the existing `_session-state.json` file in the architecture session directory. - - Add integration architecture completion status and results. - - Update `completedSteps` and `nextAction` fields. - -10. **Notify User with Integration Insights:** - - Inform the user that the integration architecture has been successfully generated. - - Provide file paths and key integration highlights. - - **Suggest logical next steps based on integration architecture:** - - "Your integration architecture is complete. Consider generating a comprehensive architecture summary using `/design/system-architecture/4-generate-architecture-summary --name=[session_name]`" - - "Review the integration patterns with your development teams to ensure implementation feasibility." - - "Use the API specifications to begin contract-first development and testing." - -## Templates & Structures - -### Integration Architecture Template -```markdown -# Integration Architecture: [Architecture Session Name] - -**Created:** [Date] -**Source:** Architecture Framework and Component Design: [Architecture Session Name] -**Integration Scope:** [Full System / Internal / External / Data / Messaging / API] -**Target Integrations:** [List of specific integrations if scoped] -**Last Updated:** [Date] - ---- - -## Integration Overview - -### Integration Strategy -- **Integration Philosophy:** [Overall approach to system integration] -- **Communication Strategy:** [Synchronous vs asynchronous communication strategy] -- **Data Strategy:** [Data sharing and consistency approach] -- **Service Strategy:** [Service discovery and coordination approach] - -### Integration Patterns -- **Primary Patterns:** [Main integration patterns used in the system] -- **Secondary Patterns:** [Supporting integration patterns] -- **Anti-Patterns:** [Patterns to avoid and why] -- **Pattern Selection Criteria:** [How to choose appropriate patterns] - -### Integration Architecture Principles -- **Loose Coupling:** [Minimize dependencies between components] -- **High Cohesion:** [Keep related functionality together] -- **Fault Tolerance:** [Handle failures gracefully] -- **Scalability:** [Support system growth and load] -- **Security:** [Protect data and communications] - -### Integration Landscape -- **Internal Integrations:** [Component-to-component communications] -- **External Integrations:** [Third-party service integrations] -- **Data Integrations:** [Database and data store integrations] -- **User Integrations:** [User interface and client integrations] - ---- - -## Communication Architecture - -### Synchronous Communication - -#### HTTP/REST API Communication -##### Design Principles -- **RESTful Design:** [RESTful API design principles and conventions] -- **Resource Modeling:** [How resources are modeled and exposed] -- **HTTP Methods:** [Proper use of HTTP methods and status codes] -- **Content Negotiation:** [Support for multiple content types] - -##### API Gateway Pattern -- **Gateway Responsibility:** [API gateway roles and responsibilities] -- **Routing:** [Request routing and load balancing] -- **Authentication:** [Centralized authentication and authorization] -- **Rate Limiting:** [Request throttling and quota management] -- **Monitoring:** [API usage monitoring and analytics] - -##### API Specification -```yaml -# OpenAPI 3.0 Specification for Service Integration -openapi: 3.0.0 -info: - title: System Integration API - version: 1.0.0 - description: API for system component integration - -servers: - - url: https://api.example.com/v1 - description: Production server - - url: https://staging-api.example.com/v1 - description: Staging server - -paths: - /components/{componentId}/status: - get: - summary: Get component status - parameters: - - name: componentId - in: path - required: true - schema: - type: string - description: Component identifier - responses: - '200': - description: Component status retrieved successfully - content: - application/json: - schema: - $ref: '#/components/schemas/ComponentStatus' - '404': - description: Component not found - '500': - description: Internal server error - - /components/{componentId}/health: - get: - summary: Get component health - parameters: - - name: componentId - in: path - required: true - schema: - type: string - responses: - '200': - description: Component health retrieved successfully - content: - application/json: - schema: - $ref: '#/components/schemas/HealthStatus' - -components: - schemas: - ComponentStatus: - type: object - properties: - componentId: - type: string - status: - type: string - enum: [running, stopped, error] - timestamp: - type: string - format: date-time - version: - type: string - - HealthStatus: - type: object - properties: - healthy: - type: boolean - checks: - type: array - items: - $ref: '#/components/schemas/HealthCheck' - - HealthCheck: - type: object - properties: - name: - type: string - status: - type: string - enum: [pass, fail, warn] - details: - type: string - - securitySchemes: - BearerAuth: - type: http - scheme: bearer - bearerFormat: JWT - -security: - - BearerAuth: [] -``` - -#### gRPC Communication -##### Service Definition -```protobuf -// Component Service Definition -syntax = "proto3"; - -package component.v1; - -service ComponentService { - rpc GetStatus(GetStatusRequest) returns (GetStatusResponse); - rpc HealthCheck(HealthCheckRequest) returns (HealthCheckResponse); - rpc ProcessCommand(ProcessCommandRequest) returns (ProcessCommandResponse); -} - -message GetStatusRequest { - string component_id = 1; -} - -message GetStatusResponse { - string component_id = 1; - ComponentStatus status = 2; - string version = 3; - int64 timestamp = 4; -} - -message HealthCheckRequest { - string component_id = 1; -} - -message HealthCheckResponse { - bool healthy = 1; - repeated HealthCheck checks = 2; -} - -message ProcessCommandRequest { - string component_id = 1; - string command = 2; - map parameters = 3; -} - -message ProcessCommandResponse { - bool success = 1; - string result = 2; - string error_message = 3; -} - -enum ComponentStatus { - UNKNOWN = 0; - RUNNING = 1; - STOPPED = 2; - ERROR = 3; -} - -message HealthCheck { - string name = 1; - HealthStatus status = 2; - string details = 3; -} - -enum HealthStatus { - PASS = 0; - FAIL = 1; - WARN = 2; -} -``` - -### Asynchronous Communication - -#### Message Queue Architecture -##### Message Broker Selection -- **Technology Choice:** [RabbitMQ/Apache Kafka/Amazon SQS selection criteria] -- **Topology:** [Message routing and queue topology] -- **Durability:** [Message persistence and reliability guarantees] -- **Scalability:** [Horizontal scaling and partitioning strategy] - -##### Message Patterns -- **Point-to-Point:** [Direct message passing between components] -- **Publish-Subscribe:** [Event broadcasting to multiple subscribers] -- **Request-Reply:** [Asynchronous request-response patterns] -- **Message Routing:** [Content-based and topic-based routing] - -##### Message Schema -```json -{ - "$schema": "http://json-schema.org/draft-07/schema#", - "title": "System Event Message", - "type": "object", - "properties": { - "messageId": { - "type": "string", - "format": "uuid", - "description": "Unique message identifier" - }, - "eventType": { - "type": "string", - "description": "Type of event being communicated" - }, - "source": { - "type": "string", - "description": "Source component that generated the event" - }, - "timestamp": { - "type": "string", - "format": "date-time", - "description": "When the event occurred" - }, - "correlationId": { - "type": "string", - "description": "Correlation ID for tracking related events" - }, - "payload": { - "type": "object", - "description": "Event-specific data payload" - }, - "metadata": { - "type": "object", - "properties": { - "version": { - "type": "string", - "description": "Message schema version" - }, - "priority": { - "type": "string", - "enum": ["low", "normal", "high", "critical"] - }, - "retryCount": { - "type": "integer", - "minimum": 0 - } - } - } - }, - "required": ["messageId", "eventType", "source", "timestamp", "payload"] -} -``` - -#### Event Streaming Architecture -##### Event Store Design -- **Event Schema:** [Event structure and versioning strategy] -- **Event Ordering:** [Event ordering and sequence guarantees] -- **Event Replay:** [Event replay and reprocessing capabilities] -- **Event Retention:** [Event storage and retention policies] - -##### Event Processing -- **Stream Processing:** [Real-time event stream processing] -- **Event Sourcing:** [Event-driven state reconstruction] -- **CQRS Integration:** [Command Query Responsibility Segregation] -- **Event Projection:** [Event-to-read-model projections] - ---- - -## Data Integration Architecture - -### Data Flow Patterns - -#### Data Synchronization -##### Master Data Management -- **Master Data Domains:** [Identification of master data entities] -- **Data Ownership:** [Clear ownership and responsibility for data] -- **Data Quality:** [Data validation and quality assurance] -- **Data Governance:** [Data lifecycle and change management] - -##### Data Consistency Patterns -- **Strong Consistency:** [ACID transactions and immediate consistency] -- **Eventual Consistency:** [BASE transactions and eventual consistency] -- **Causal Consistency:** [Causal ordering and dependencies] -- **Session Consistency:** [Per-session consistency guarantees] - -#### Data Transformation -##### ETL/ELT Patterns -- **Extract:** [Data extraction from source systems] -- **Transform:** [Data transformation and enrichment] -- **Load:** [Data loading into target systems] -- **Orchestration:** [Data pipeline orchestration and scheduling] - -##### Data Pipeline Architecture -```yaml -# Data Pipeline Configuration -apiVersion: v1 -kind: ConfigMap -metadata: - name: data-pipeline-config -data: - pipeline.yaml: | - name: customer-data-pipeline - description: Customer data synchronization pipeline - - sources: - - name: customer-db - type: postgresql - connection: ${CUSTOMER_DB_CONNECTION} - query: | - SELECT customer_id, name, email, created_at, updated_at - FROM customers - WHERE updated_at > ${LAST_SYNC_TIME} - - transformations: - - name: data-validation - type: validation - rules: - - field: email - rule: email_format - - field: name - rule: not_empty - - - name: data-enrichment - type: enrichment - enrichments: - - field: customer_segment - source: customer-segmentation-service - key: customer_id - - destinations: - - name: customer-warehouse - type: bigquery - table: analytics.customers - mode: upsert - key: customer_id - - - name: customer-cache - type: redis - key_pattern: customer:${customer_id} - ttl: 3600 - - schedule: - type: cron - expression: "0 */15 * * * *" - - monitoring: - success_rate_threshold: 0.95 - latency_threshold: 300 - alert_channels: - - email: data-team@company.com - - slack: #data-alerts -``` - -### Database Integration - -#### Multi-Database Architecture -##### Database per Service -- **Database Ownership:** [Each service owns its database] -- **Data Isolation:** [Strong data boundaries between services] -- **Technology Choice:** [Service-specific database selection] -- **Schema Evolution:** [Independent schema evolution] - -##### Shared Database Challenges -- **Schema Coupling:** [Managing shared schema changes] -- **Performance Impact:** [Handling concurrent access] -- **Data Consistency:** [Maintaining consistency across services] -- **Migration Strategy:** [Transitioning from shared to service databases] - -#### Database Synchronization -##### Change Data Capture (CDC) -- **CDC Technology:** [Debezium/AWS DMS/Custom CDC selection] -- **Change Events:** [Database change event processing] -- **Event Ordering:** [Maintaining change order and consistency] -- **Failure Recovery:** [Handling CDC failures and recovery] - -##### Database Replication -- **Replication Strategy:** [Master-slave/Master-master replication] -- **Consistency Model:** [Strong/Eventual consistency guarantees] -- **Conflict Resolution:** [Handling replication conflicts] -- **Performance Impact:** [Replication overhead and optimization] - ---- - -## Service Integration Architecture - -### Service Discovery - -#### Service Registry Pattern -##### Registry Technology -- **Registry Choice:** [Consul/Eureka/Kubernetes DNS selection] -- **Service Registration:** [Automatic vs manual service registration] -- **Health Checking:** [Service health monitoring and reporting] -- **Load Balancing:** [Service discovery integration with load balancers] - -##### Service Discovery Flow -```mermaid -graph LR - A[Service Instance] -->|Register| B[Service Registry] - C[Client Service] -->|Discover| B - B -->|Return Endpoints| C - C -->|Call Service| D[Target Service] - D -->|Health Check| B -``` - -#### Circuit Breaker Pattern -##### Circuit Breaker Implementation -- **Failure Threshold:** [Failure rate threshold for circuit opening] -- **Timeout Configuration:** [Request timeout and circuit timeout] -- **Fallback Strategy:** [Fallback behavior when circuit is open] -- **Recovery Strategy:** [Circuit recovery and half-open state] - -##### Circuit Breaker Configuration -```yaml -# Circuit Breaker Configuration -circuitBreaker: - services: - - name: payment-service - failureThreshold: 5 - timeoutMillis: 5000 - resetTimeoutMillis: 30000 - fallback: - type: cached_response - cache_ttl: 300 - - - name: user-service - failureThreshold: 3 - timeoutMillis: 3000 - resetTimeoutMillis: 60000 - fallback: - type: default_response - response: | - { - "error": "User service temporarily unavailable", - "code": "SERVICE_UNAVAILABLE" - } -``` - -### Load Balancing - -#### Load Balancing Strategies -##### Client-Side Load Balancing -- **Load Balancer Libraries:** [Client-side load balancing libraries] -- **Load Balancing Algorithms:** [Round-robin/Weighted/Least connections] -- **Health Awareness:** [Health-aware load balancing] -- **Sticky Sessions:** [Session affinity and stickiness] - -##### Server-Side Load Balancing -- **Load Balancer Technology:** [HAProxy/NGINX/AWS ALB selection] -- **Traffic Distribution:** [Traffic routing and distribution rules] -- **SSL Termination:** [SSL/TLS termination and encryption] -- **Geographic Routing:** [Geographic traffic routing] - -#### API Gateway Integration -##### Gateway Responsibilities -- **Request Routing:** [Route requests to appropriate services] -- **Authentication:** [Centralized authentication and token validation] -- **Rate Limiting:** [Request throttling and quota management] -- **Request/Response Transformation:** [Data transformation and enrichment] -- **Monitoring:** [Request monitoring and analytics] - -##### Gateway Configuration -```yaml -# API Gateway Configuration -apiVersion: networking.istio.io/v1beta1 -kind: Gateway -metadata: - name: system-gateway -spec: - selector: - istio: ingressgateway - servers: - - port: - number: 443 - name: https - protocol: HTTPS - tls: - mode: SIMPLE - credentialName: system-tls-cert - hosts: - - api.example.com - ---- -apiVersion: networking.istio.io/v1beta1 -kind: VirtualService -metadata: - name: system-virtual-service -spec: - hosts: - - api.example.com - gateways: - - system-gateway - http: - - match: - - uri: - prefix: /api/v1/users - route: - - destination: - host: user-service - port: - number: 8080 - fault: - delay: - percentage: - value: 0.1 - fixedDelay: 5s - retries: - attempts: 3 - perTryTimeout: 2s - - - match: - - uri: - prefix: /api/v1/orders - route: - - destination: - host: order-service - port: - number: 8080 - timeout: 10s -``` - ---- - -## Security Architecture - -### Authentication and Authorization - -#### Identity and Access Management -##### Authentication Flow -- **Authentication Methods:** [JWT/OAuth2/SAML authentication] -- **Token Management:** [Token generation, validation, and refresh] -- **Multi-Factor Authentication:** [MFA implementation and enforcement] -- **Session Management:** [Session creation, maintenance, and termination] - -##### Authorization Patterns -- **Role-Based Access Control (RBAC):** [Role and permission management] -- **Attribute-Based Access Control (ABAC):** [Attribute-based permissions] -- **Policy-Based Access Control:** [Policy engine and rule evaluation] -- **Resource-Based Access Control:** [Resource-level permissions] - -#### Security Communication -##### Transport Security -- **TLS/SSL Configuration:** [Transport layer security configuration] -- **Certificate Management:** [Certificate lifecycle and rotation] -- **Mutual TLS (mTLS):** [Service-to-service authentication] -- **Certificate Pinning:** [Certificate pinning for enhanced security] - -##### Message Security -- **Message Encryption:** [End-to-end message encryption] -- **Message Signing:** [Message integrity and authenticity] -- **Key Management:** [Encryption key lifecycle and rotation] -- **Secure Headers:** [HTTP security headers and CORS] - -### Data Protection - -#### Data Encryption -##### Encryption at Rest -- **Database Encryption:** [Database-level encryption] -- **File System Encryption:** [File system and storage encryption] -- **Key Management Service:** [Centralized key management] -- **Encryption Standards:** [Encryption algorithms and key sizes] - -##### Encryption in Transit -- **Network Encryption:** [Network-level encryption protocols] -- **Application Encryption:** [Application-level encryption] -- **API Encryption:** [API payload encryption] -- **Message Encryption:** [Message queue encryption] - -#### Data Privacy -##### Privacy Controls -- **Data Minimization:** [Collect and process only necessary data] -- **Data Anonymization:** [Data anonymization and pseudonymization] -- **Consent Management:** [User consent tracking and management] -- **Data Retention:** [Data retention and deletion policies] - -##### Compliance Requirements -- **GDPR Compliance:** [European data protection regulation compliance] -- **CCPA Compliance:** [California consumer privacy act compliance] -- **Industry Standards:** [Industry-specific compliance requirements] -- **Audit Trails:** [Comprehensive audit logging and monitoring] - ---- - -## Monitoring and Observability - -### Integration Monitoring - -#### Metrics Collection -##### System Metrics -- **Performance Metrics:** [Response time, throughput, error rates] -- **Resource Metrics:** [CPU, memory, disk, network utilization] -- **Application Metrics:** [Business-specific metrics and KPIs] -- **Integration Metrics:** [Service dependencies and communication metrics] - -##### Monitoring Stack -```yaml -# Monitoring Configuration -monitoring: - prometheus: - enabled: true - retention: 15d - storage: 100Gi - - targets: - - job_name: 'system-services' - static_configs: - - targets: ['user-service:8080', 'order-service:8080'] - metrics_path: '/metrics' - scrape_interval: 15s - - - job_name: 'api-gateway' - static_configs: - - targets: ['api-gateway:9090'] - metrics_path: '/actuator/prometheus' - scrape_interval: 10s - - grafana: - enabled: true - dashboards: - - name: 'System Overview' - panels: - - title: 'Request Rate' - type: graph - targets: - - expr: 'rate(http_requests_total[5m])' - - title: 'Error Rate' - type: graph - targets: - - expr: 'rate(http_requests_total{status=~"5.."}[5m])' - - title: 'Response Time' - type: graph - targets: - - expr: 'histogram_quantile(0.95, rate(http_request_duration_seconds_bucket[5m]))' - - alerting: - rules: - - alert: HighErrorRate - expr: rate(http_requests_total{status=~"5.."}[5m]) > 0.1 - for: 5m - labels: - severity: warning - annotations: - summary: "High error rate detected" - description: "Error rate is above 10% for 5 minutes" - - - alert: ServiceDown - expr: up == 0 - for: 1m - labels: - severity: critical - annotations: - summary: "Service is down" - description: "Service {{ $labels.instance }} is down" -``` - -#### Distributed Tracing -##### Tracing Implementation -- **Tracing Technology:** [Jaeger/Zipkin/OpenTelemetry selection] -- **Trace Sampling:** [Sampling strategies and configuration] -- **Span Correlation:** [Request correlation across services] -- **Trace Analysis:** [Trace analysis and performance insights] - -##### Tracing Configuration -```yaml -# OpenTelemetry Configuration -apiVersion: v1 -kind: ConfigMap -metadata: - name: otel-config -data: - config.yaml: | - receivers: - otlp: - protocols: - grpc: - endpoint: 0.0.0.0:4317 - http: - endpoint: 0.0.0.0:4318 - - processors: - batch: - timeout: 1s - send_batch_size: 1024 - - resource: - attributes: - - key: service.name - value: system-service - action: upsert - - exporters: - jaeger: - endpoint: jaeger-collector:14250 - tls: - insecure: true - - prometheus: - endpoint: "0.0.0.0:8889" - - service: - pipelines: - traces: - receivers: [otlp] - processors: [resource, batch] - exporters: [jaeger] - - metrics: - receivers: [otlp] - processors: [resource, batch] - exporters: [prometheus] -``` - -### Logging and Auditing - -#### Centralized Logging -##### Log Aggregation -- **Logging Technology:** [ELK Stack/Fluentd/Splunk selection] -- **Log Structure:** [Structured logging and log format standards] -- **Log Correlation:** [Log correlation across services] -- **Log Retention:** [Log retention and archival policies] - -##### Logging Configuration -```yaml -# Logging Configuration -logging: - level: INFO - - appenders: - - name: console - type: console - layout: - type: json - fields: - - timestamp - - level - - logger - - message - - mdc - - exception - - - name: file - type: file - file: /var/log/application.log - layout: - type: json - fields: - - timestamp - - level - - logger - - message - - mdc - - exception - - - name: elasticsearch - type: elasticsearch - hosts: - - elasticsearch:9200 - index: application-logs - layout: - type: json - - loggers: - - name: com.example.integration - level: DEBUG - appenders: [console, file, elasticsearch] - - - name: com.example.security - level: INFO - appenders: [console, file, elasticsearch] - - correlation: - enabled: true - header_names: - - X-Correlation-ID - - X-Request-ID -``` - -#### Audit Logging -##### Audit Requirements -- **Audit Events:** [Security, data access, and system events] -- **Audit Data:** [User, timestamp, action, and resource information] -- **Audit Storage:** [Secure audit log storage and retention] -- **Audit Reporting:** [Audit analysis and compliance reporting] - ---- - -## Performance and Scalability - -### Performance Optimization - -#### Caching Strategies -##### Multi-Level Caching -- **L1 Cache:** [In-memory application caching] -- **L2 Cache:** [Distributed caching (Redis/Memcached)] -- **L3 Cache:** [Database query result caching] -- **CDN Cache:** [Content delivery network caching] - -##### Cache Management -- **Cache Invalidation:** [Cache invalidation strategies and policies] -- **Cache Warming:** [Proactive cache population] -- **Cache Monitoring:** [Cache hit rates and performance monitoring] -- **Cache Consistency:** [Cache consistency and synchronization] - -#### Database Performance -##### Query Optimization -- **Index Strategy:** [Database indexing and optimization] -- **Query Patterns:** [Efficient query design and execution] -- **Connection Pooling:** [Database connection management] -- **Read Replicas:** [Read scaling with database replicas] - -##### Database Scaling -- **Horizontal Scaling:** [Database sharding and partitioning] -- **Vertical Scaling:** [Database resource scaling] -- **Multi-Region:** [Multi-region database deployment] -- **Failover:** [Database failover and disaster recovery] - -### Scalability Architecture - -#### Horizontal Scaling -##### Auto-Scaling -- **Scaling Triggers:** [CPU, memory, and custom metric triggers] -- **Scaling Policies:** [Scale-up and scale-down policies] -- **Load Testing:** [Performance testing and capacity planning] -- **Resource Limits:** [Resource quotas and limits] - -##### Container Orchestration -```yaml -# Kubernetes Deployment with Auto-Scaling -apiVersion: apps/v1 -kind: Deployment -metadata: - name: user-service -spec: - replicas: 3 - selector: - matchLabels: - app: user-service - template: - metadata: - labels: - app: user-service - spec: - containers: - - name: user-service - image: user-service:latest - ports: - - containerPort: 8080 - resources: - requests: - cpu: 100m - memory: 128Mi - limits: - cpu: 500m - memory: 512Mi - livenessProbe: - httpGet: - path: /health - port: 8080 - initialDelaySeconds: 30 - periodSeconds: 10 - readinessProbe: - httpGet: - path: /ready - port: 8080 - initialDelaySeconds: 5 - periodSeconds: 5 - ---- -apiVersion: autoscaling/v2 -kind: HorizontalPodAutoscaler -metadata: - name: user-service-hpa -spec: - scaleTargetRef: - apiVersion: apps/v1 - kind: Deployment - name: user-service - minReplicas: 3 - maxReplicas: 10 - metrics: - - type: Resource - resource: - name: cpu - target: - type: Utilization - averageUtilization: 70 - - type: Resource - resource: - name: memory - target: - type: Utilization - averageUtilization: 80 -``` - ---- - -## Disaster Recovery and Business Continuity - -### Backup and Recovery - -#### Data Backup Strategy -##### Backup Types -- **Full Backup:** [Complete data backup procedures] -- **Incremental Backup:** [Incremental change backup] -- **Differential Backup:** [Differential change backup] -- **Continuous Backup:** [Real-time backup and replication] - -##### Recovery Procedures -- **Recovery Time Objective (RTO):** [Maximum acceptable downtime] -- **Recovery Point Objective (RPO):** [Maximum acceptable data loss] -- **Backup Testing:** [Regular backup validation and testing] -- **Recovery Automation:** [Automated recovery procedures] - -#### High Availability -##### Redundancy Patterns -- **Active-Active:** [Active-active deployment pattern] -- **Active-Passive:** [Active-passive deployment pattern] -- **Multi-Region:** [Multi-region deployment strategy] -- **Failover:** [Automated failover mechanisms] - -##### Health Monitoring -- **Health Checks:** [Comprehensive health monitoring] -- **Failure Detection:** [Automated failure detection] -- **Alert Systems:** [Incident notification and escalation] -- **Recovery Automation:** [Automated recovery procedures] - ---- - -## Next Steps - -### Implementation Planning -1. **Integration Development:** [Plan integration implementation order] -2. **API Development:** [Implement API contracts and specifications] -3. **Message Infrastructure:** [Set up messaging and event infrastructure] -4. **Security Implementation:** [Implement security and authentication] - -### Testing and Validation -1. **Integration Testing:** [Test component integration patterns] -2. **Performance Testing:** [Validate performance requirements] -3. **Security Testing:** [Test security implementations] -4. **Disaster Recovery Testing:** [Test backup and recovery procedures] - -### Operations Preparation -1. **Monitoring Setup:** [Implement monitoring and observability] -2. **Deployment Automation:** [Set up CI/CD and deployment automation] -3. **Documentation:** [Create operational documentation] -4. **Training:** [Train teams on integration patterns and operations] - ---- - -## Appendices - -### A. Integration Patterns Catalog -[Comprehensive catalog of integration patterns with implementation guidance] - -### B. API Specifications -[Complete API specifications and documentation] - -### C. Message Schema Registry -[Message schema definitions and versioning] - -### D. Performance Benchmarks -[Performance testing results and benchmarks] - -### E. Security Assessment -[Security analysis and threat modeling results] - -### F. Operational Runbooks -[Operational procedures and troubleshooting guides] -``` - -### Updated Session State Structure -```json -{ - "index": 1, - "name": "architecture-session-name", - "type": "architecture", - "status": "integration_architecture_complete", - "created": "ISO datetime", - "lastUpdated": "ISO datetime", - "currentStep": "integration_architecture", - "completedSteps": ["architecture_framework_creation", "domain_analysis", "layer_design", "component_design", "integration_architecture"], - "nextAction": "Ready for architecture summary generation", - "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, - "createdDate": "ISO datetime", - "componentDesignDate": "ISO datetime", - "integrationArchitectureDate": "ISO datetime" - } -} -``` - -## Best Practices - -### ✅ DO: Integration-First Design -- **Design integration patterns** before implementing individual components -- **Use contract-first approach** for all service interactions -- **Plan for failure scenarios** and implement resilience patterns -- **Consider operational requirements** from the design phase - -**Why:** Integration-first design prevents integration problems and ensures system reliability and maintainability. - -### ✅ DO: Observability by Design -- **Build in monitoring** and logging from the beginning -- **Use distributed tracing** for end-to-end visibility -- **Implement comprehensive health checks** for all services -- **Plan for troubleshooting** and debugging scenarios - -**Why:** Observability by design enables effective monitoring, debugging, and maintenance of complex distributed systems. - -### ✅ DO: Security by Design -- **Implement security** at every integration point -- **Use defense in depth** with multiple security layers -- **Follow principle of least privilege** for all access controls -- **Plan for security incident response** and recovery - -**Why:** Security by design prevents security vulnerabilities and ensures compliance with security requirements. - -### ❌ DON'T: Ignore Network Realities -- **Don't assume network reliability** - plan for network failures -- **Don't ignore latency** - consider network latency in design -- **Don't forget about bandwidth** - plan for data transfer costs -- **Don't ignore security** - secure all network communications - -**Why:** Ignoring network realities leads to unreliable systems that fail under real-world conditions. - -### ❌ DON'T: Create Tight Coupling -- **Don't create direct dependencies** between unrelated components -- **Don't share databases** across service boundaries -- **Don't use shared libraries** for business logic -- **Don't ignore service boundaries** when designing integrations - -**Why:** Tight coupling reduces system flexibility, increases complexity, and makes systems harder to maintain and evolve. - -## Output -- **Format:** Comprehensive integration architecture with communication protocols and patterns -- **Location:** `.taskmaster/docs/design/architecture/[index]-[architecture_session_name]/` -- **Primary Files:** - - `integration-architecture_[architecture_session_name].md` - Main integration architecture document - - `_session-state.json` - Updated session state - -## Example Usage -- **Design full integration architecture:** - `/design/system-architecture/3-integration-architecture --name="enterprise-expansion"` -- **Design specific integration scope:** - `/design/system-architecture/3-integration-architecture --name="enterprise-expansion" --scope="external"` -- **Design by architecture index:** - `/design/system-architecture/3-integration-architecture --name="1" --scope="api"` \ No newline at end of file diff --git a/.claude/commands/design/1-system-architecture/4-generate-architecture-summary.md b/.claude/commands/design/1-system-architecture/4-generate-architecture-summary.md deleted file mode 100644 index a462afa..0000000 --- a/.claude/commands/design/1-system-architecture/4-generate-architecture-summary.md +++ /dev/null @@ -1,508 +0,0 @@ ---- -allowed-tools: [Read, Write, Glob, TodoWrite] -description: 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 -```markdown -# 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 -```json -{ - "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"` \ No newline at end of file diff --git a/.claude/commands/sc/analyze.md b/.claude/commands/sc/analyze.md new file mode 100644 index 0000000..f8b16f1 --- /dev/null +++ b/.claude/commands/sc/analyze.md @@ -0,0 +1,33 @@ +--- +allowed-tools: [Read, Grep, Glob, Bash, TodoWrite] +description: "Analyze code quality, security, performance, and architecture" +--- + +# /sc:analyze - Code Analysis + +## Purpose +Execute comprehensive code analysis across quality, security, performance, and architecture domains. + +## Usage +``` +/sc:analyze [target] [--focus quality|security|performance|architecture] [--depth quick|deep] +``` + +## Arguments +- `target` - Files, directories, or project to analyze +- `--focus` - Analysis focus area (quality, security, performance, architecture) +- `--depth` - Analysis depth (quick, deep) +- `--format` - Output format (text, json, report) + +## Execution +1. Discover and categorize files for analysis +2. Apply appropriate analysis tools and techniques +3. Generate findings with severity ratings +4. Create actionable recommendations with priorities +5. Present comprehensive analysis report + +## Claude Code Integration +- Uses Glob for systematic file discovery +- Leverages Grep for pattern-based analysis +- Applies Read for deep code inspection +- Maintains structured analysis reporting \ No newline at end of file diff --git a/.claude/commands/sc/build.md b/.claude/commands/sc/build.md new file mode 100644 index 0000000..67fc634 --- /dev/null +++ b/.claude/commands/sc/build.md @@ -0,0 +1,34 @@ +--- +allowed-tools: [Read, Bash, Glob, TodoWrite, Edit] +description: "Build, compile, and package projects with error handling and optimization" +--- + +# /sc:build - Project Building + +## Purpose +Build, compile, and package projects with comprehensive error handling and optimization. + +## Usage +``` +/sc:build [target] [--type dev|prod|test] [--clean] [--optimize] +``` + +## Arguments +- `target` - Project or specific component to build +- `--type` - Build type (dev, prod, test) +- `--clean` - Clean build artifacts before building +- `--optimize` - Enable build optimizations +- `--verbose` - Enable detailed build output + +## Execution +1. Analyze project structure and build configuration +2. Validate dependencies and environment setup +3. Execute build process with error monitoring +4. Handle build errors and provide diagnostic information +5. Optimize build output and report results + +## Claude Code Integration +- Uses Bash for build command execution +- Leverages Read for build configuration analysis +- Applies TodoWrite for build progress tracking +- Maintains comprehensive error handling and reporting \ No newline at end of file diff --git a/.claude/commands/sc/cleanup.md b/.claude/commands/sc/cleanup.md new file mode 100644 index 0000000..6f9999e --- /dev/null +++ b/.claude/commands/sc/cleanup.md @@ -0,0 +1,34 @@ +--- +allowed-tools: [Read, Grep, Glob, Bash, Edit, MultiEdit] +description: "Clean up code, remove dead code, and optimize project structure" +--- + +# /sc:cleanup - Code and Project Cleanup + +## Purpose +Systematically clean up code, remove dead code, optimize imports, and improve project structure. + +## Usage +``` +/sc:cleanup [target] [--type code|imports|files|all] [--safe|--aggressive] +``` + +## Arguments +- `target` - Files, directories, or entire project to clean +- `--type` - Cleanup type (code, imports, files, all) +- `--safe` - Conservative cleanup (default) +- `--aggressive` - More thorough cleanup with higher risk +- `--dry-run` - Preview changes without applying them + +## Execution +1. Analyze target for cleanup opportunities +2. Identify dead code, unused imports, and redundant files +3. Create cleanup plan with risk assessment +4. Execute cleanup operations with appropriate safety measures +5. Validate changes and report cleanup results + +## Claude Code Integration +- Uses Glob for systematic file discovery +- Leverages Grep for dead code detection +- Applies MultiEdit for batch cleanup operations +- Maintains backup and rollback capabilities \ No newline at end of file diff --git a/.claude/commands/sc/design.md b/.claude/commands/sc/design.md new file mode 100644 index 0000000..04fe8af --- /dev/null +++ b/.claude/commands/sc/design.md @@ -0,0 +1,33 @@ +--- +allowed-tools: [Read, Grep, Glob, Write, Edit, TodoWrite] +description: "Design system architecture, APIs, and component interfaces" +--- + +# /sc:design - System and Component Design + +## Purpose +Design system architecture, APIs, component interfaces, and technical specifications. + +## Usage +``` +/sc:design [target] [--type architecture|api|component|database] [--format diagram|spec|code] +``` + +## Arguments +- `target` - System, component, or feature to design +- `--type` - Design type (architecture, api, component, database) +- `--format` - Output format (diagram, spec, code) +- `--iterative` - Enable iterative design refinement + +## Execution +1. Analyze requirements and design constraints +2. Create initial design concepts and alternatives +3. Develop detailed design specifications +4. Validate design against requirements and best practices +5. Generate design documentation and implementation guides + +## Claude Code Integration +- Uses Read for requirement analysis +- Leverages Write for design documentation +- Applies TodoWrite for design task tracking +- Maintains consistency with architectural patterns \ No newline at end of file diff --git a/.claude/commands/sc/document.md b/.claude/commands/sc/document.md new file mode 100644 index 0000000..e714f84 --- /dev/null +++ b/.claude/commands/sc/document.md @@ -0,0 +1,33 @@ +--- +allowed-tools: [Read, Grep, Glob, Write, Edit] +description: "Create focused documentation for specific components or features" +--- + +# /sc:document - Focused Documentation + +## Purpose +Generate precise, focused documentation for specific components, functions, or features. + +## Usage +``` +/sc:document [target] [--type inline|external|api|guide] [--style brief|detailed] +``` + +## Arguments +- `target` - Specific file, function, or component to document +- `--type` - Documentation type (inline, external, api, guide) +- `--style` - Documentation style (brief, detailed) +- `--template` - Use specific documentation template + +## Execution +1. Analyze target component and extract key information +2. Identify documentation requirements and audience +3. Generate appropriate documentation based on type and style +4. Apply consistent formatting and structure +5. Integrate with existing documentation ecosystem + +## Claude Code Integration +- Uses Read for deep component analysis +- Leverages Edit for inline documentation updates +- Applies Write for external documentation creation +- Maintains documentation standards and conventions \ No newline at end of file diff --git a/.claude/commands/sc/estimate.md b/.claude/commands/sc/estimate.md new file mode 100644 index 0000000..7555d86 --- /dev/null +++ b/.claude/commands/sc/estimate.md @@ -0,0 +1,33 @@ +--- +allowed-tools: [Read, Grep, Glob, Bash] +description: "Provide development estimates for tasks, features, or projects" +--- + +# /sc:estimate - Development Estimation + +## Purpose +Generate accurate development estimates for tasks, features, or projects based on complexity analysis. + +## Usage +``` +/sc:estimate [target] [--type time|effort|complexity|cost] [--unit hours|days|weeks] +``` + +## Arguments +- `target` - Task, feature, or project to estimate +- `--type` - Estimation type (time, effort, complexity, cost) +- `--unit` - Time unit for estimates (hours, days, weeks) +- `--breakdown` - Provide detailed breakdown of estimates + +## Execution +1. Analyze scope and requirements of target +2. Identify complexity factors and dependencies +3. Apply estimation methodologies and historical data +4. Generate estimates with confidence intervals +5. Present detailed breakdown with risk factors + +## Claude Code Integration +- Uses Read for requirement analysis +- Leverages Glob for codebase complexity assessment +- Applies Grep for pattern-based estimation +- Maintains structured estimation documentation \ No newline at end of file diff --git a/.claude/commands/sc/explain.md b/.claude/commands/sc/explain.md new file mode 100644 index 0000000..0c085a1 --- /dev/null +++ b/.claude/commands/sc/explain.md @@ -0,0 +1,33 @@ +--- +allowed-tools: [Read, Grep, Glob, Bash] +description: "Provide clear explanations of code, concepts, or system behavior" +--- + +# /sc:explain - Code and Concept Explanation + +## Purpose +Deliver clear, comprehensive explanations of code functionality, concepts, or system behavior. + +## Usage +``` +/sc:explain [target] [--level basic|intermediate|advanced] [--format text|diagram|examples] +``` + +## Arguments +- `target` - Code file, function, concept, or system to explain +- `--level` - Explanation complexity (basic, intermediate, advanced) +- `--format` - Output format (text, diagram, examples) +- `--context` - Additional context for explanation + +## Execution +1. Analyze target code or concept thoroughly +2. Identify key components and relationships +3. Structure explanation based on complexity level +4. Provide relevant examples and use cases +5. Present clear, accessible explanation with proper formatting + +## Claude Code Integration +- Uses Read for comprehensive code analysis +- Leverages Grep for pattern identification +- Applies Bash for runtime behavior analysis +- Maintains clear, educational communication style \ No newline at end of file diff --git a/.claude/commands/sc/git.md b/.claude/commands/sc/git.md new file mode 100644 index 0000000..ebffeb2 --- /dev/null +++ b/.claude/commands/sc/git.md @@ -0,0 +1,34 @@ +--- +allowed-tools: [Bash, Read, Glob, TodoWrite, Edit] +description: "Git operations with intelligent commit messages and branch management" +--- + +# /sc:git - Git Operations + +## Purpose +Execute Git operations with intelligent commit messages, branch management, and workflow optimization. + +## Usage +``` +/sc:git [operation] [args] [--smart-commit] [--branch-strategy] +``` + +## Arguments +- `operation` - Git operation (add, commit, push, pull, merge, branch, status) +- `args` - Operation-specific arguments +- `--smart-commit` - Generate intelligent commit messages +- `--branch-strategy` - Apply branch naming conventions +- `--interactive` - Interactive mode for complex operations + +## Execution +1. Analyze current Git state and repository context +2. Execute requested Git operations with validation +3. Apply intelligent commit message generation +4. Handle merge conflicts and branch management +5. Provide clear feedback and next steps + +## Claude Code Integration +- Uses Bash for Git command execution +- Leverages Read for repository analysis +- Applies TodoWrite for operation tracking +- Maintains Git best practices and conventions \ No newline at end of file diff --git a/.claude/commands/sc/implement.md b/.claude/commands/sc/implement.md new file mode 100644 index 0000000..45b478f --- /dev/null +++ b/.claude/commands/sc/implement.md @@ -0,0 +1,54 @@ +--- +allowed-tools: [Read, Write, Edit, MultiEdit, Bash, Glob, TodoWrite, Task] +description: "Feature and code implementation with intelligent persona activation and MCP integration" +--- + +# /sc:implement - Feature Implementation + +## Purpose +Implement features, components, and code functionality with intelligent expert activation and comprehensive development support. + +## Usage +``` +/sc:implement [feature-description] [--type component|api|service|feature] [--framework react|vue|express|etc] [--safe] +``` + +## Arguments +- `feature-description` - Description of what to implement +- `--type` - Implementation type (component, api, service, feature, module) +- `--framework` - Target framework or technology stack +- `--safe` - Use conservative implementation approach +- `--iterative` - Enable iterative development with validation steps +- `--with-tests` - Include test implementation +- `--documentation` - Generate documentation alongside implementation + +## Execution +1. Analyze implementation requirements and detect technology context +2. Auto-activate relevant personas (frontend, backend, security, etc.) +3. Coordinate with MCP servers (Magic for UI, Context7 for patterns, Sequential for complex logic) +4. Generate implementation code with best practices +5. Apply security and quality validation +6. Provide testing recommendations and next steps + +## Claude Code Integration +- Uses Write/Edit/MultiEdit for code generation and modification +- Leverages Read and Glob for codebase analysis and context understanding +- Applies TodoWrite for implementation progress tracking +- Integrates Task tool for complex multi-step implementations +- Coordinates with MCP servers for specialized functionality +- Auto-activates appropriate personas based on implementation type + +## Auto-Activation Patterns +- **Frontend**: UI components, React/Vue/Angular development +- **Backend**: APIs, services, database integration +- **Security**: Authentication, authorization, data protection +- **Architecture**: System design, module structure +- **Performance**: Optimization, scalability considerations + +## Examples +``` +/sc:implement user authentication system --type feature --with-tests +/sc:implement dashboard component --type component --framework react +/sc:implement REST API for user management --type api --safe +/sc:implement payment processing service --type service --iterative +``` \ No newline at end of file diff --git a/.claude/commands/sc/improve.md b/.claude/commands/sc/improve.md new file mode 100644 index 0000000..6521423 --- /dev/null +++ b/.claude/commands/sc/improve.md @@ -0,0 +1,33 @@ +--- +allowed-tools: [Read, Grep, Glob, Edit, MultiEdit, TodoWrite] +description: "Apply systematic improvements to code quality, performance, and maintainability" +--- + +# /sc:improve - Code Improvement + +## Purpose +Apply systematic improvements to code quality, performance, maintainability, and best practices. + +## Usage +``` +/sc:improve [target] [--type quality|performance|maintainability|style] [--safe] +``` + +## Arguments +- `target` - Files, directories, or project to improve +- `--type` - Improvement type (quality, performance, maintainability, style) +- `--safe` - Apply only safe, low-risk improvements +- `--preview` - Show improvements without applying them + +## Execution +1. Analyze code for improvement opportunities +2. Identify specific improvement patterns and techniques +3. Create improvement plan with risk assessment +4. Apply improvements with appropriate validation +5. Verify improvements and report changes + +## Claude Code Integration +- Uses Read for comprehensive code analysis +- Leverages MultiEdit for batch improvements +- Applies TodoWrite for improvement tracking +- Maintains safety and validation mechanisms \ No newline at end of file diff --git a/.claude/commands/sc/index.md b/.claude/commands/sc/index.md new file mode 100644 index 0000000..e2e2838 --- /dev/null +++ b/.claude/commands/sc/index.md @@ -0,0 +1,33 @@ +--- +allowed-tools: [Read, Grep, Glob, Bash, Write] +description: "Generate comprehensive project documentation and knowledge base" +--- + +# /sc:index - Project Documentation + +## Purpose +Create and maintain comprehensive project documentation, indexes, and knowledge bases. + +## Usage +``` +/sc:index [target] [--type docs|api|structure|readme] [--format md|json|yaml] +``` + +## Arguments +- `target` - Project directory or specific component to document +- `--type` - Documentation type (docs, api, structure, readme) +- `--format` - Output format (md, json, yaml) +- `--update` - Update existing documentation + +## Execution +1. Analyze project structure and identify key components +2. Extract documentation from code comments and README files +3. Generate comprehensive documentation based on type +4. Create navigation structure and cross-references +5. Output formatted documentation with proper organization + +## Claude Code Integration +- Uses Glob for systematic file discovery +- Leverages Grep for extracting documentation patterns +- Applies Write for creating structured documentation +- Maintains consistency with project conventions \ No newline at end of file diff --git a/.claude/commands/sc/load.md b/.claude/commands/sc/load.md new file mode 100644 index 0000000..5b1055b --- /dev/null +++ b/.claude/commands/sc/load.md @@ -0,0 +1,33 @@ +--- +allowed-tools: [Read, Grep, Glob, Bash, Write] +description: "Load and analyze project context, configurations, and dependencies" +--- + +# /sc:load - Project Context Loading + +## Purpose +Load and analyze project context, configurations, dependencies, and environment setup. + +## Usage +``` +/sc:load [target] [--type project|config|deps|env] [--cache] +``` + +## Arguments +- `target` - Project directory or specific configuration to load +- `--type` - Loading type (project, config, deps, env) +- `--cache` - Cache loaded context for faster subsequent access +- `--refresh` - Force refresh of cached context + +## Execution +1. Discover and analyze project structure and configuration files +2. Load dependencies, environment variables, and settings +3. Parse and validate configuration consistency +4. Create comprehensive project context map +5. Cache context for efficient future access + +## Claude Code Integration +- Uses Glob for comprehensive project discovery +- Leverages Read for configuration analysis +- Applies Bash for environment validation +- Maintains efficient context caching mechanisms \ No newline at end of file diff --git a/.claude/commands/sc/spawn.md b/.claude/commands/sc/spawn.md new file mode 100644 index 0000000..6e53a62 --- /dev/null +++ b/.claude/commands/sc/spawn.md @@ -0,0 +1,33 @@ +--- +allowed-tools: [Read, Grep, Glob, Bash, TodoWrite, Edit, MultiEdit, Write] +description: "Break complex tasks into coordinated subtasks with efficient execution" +--- + +# /sc:spawn - Task Orchestration + +## Purpose +Decompose complex requests into manageable subtasks and coordinate their execution. + +## Usage +``` +/sc:spawn [task] [--sequential|--parallel] [--validate] +``` + +## Arguments +- `task` - Complex task or project to orchestrate +- `--sequential` - Execute tasks in dependency order (default) +- `--parallel` - Execute independent tasks concurrently +- `--validate` - Enable quality checkpoints between tasks + +## Execution +1. Parse request and create hierarchical task breakdown +2. Map dependencies between subtasks +3. Choose optimal execution strategy (sequential/parallel) +4. Execute subtasks with progress monitoring +5. Integrate results and validate completion + +## Claude Code Integration +- Uses TodoWrite for task breakdown and tracking +- Leverages file operations for coordinated changes +- Applies efficient batching for related operations +- Maintains clear dependency management \ No newline at end of file diff --git a/.claude/commands/sc/task.md b/.claude/commands/sc/task.md new file mode 100644 index 0000000..491bcaa --- /dev/null +++ b/.claude/commands/sc/task.md @@ -0,0 +1,157 @@ +--- +allowed-tools: [Read, Glob, Grep, TodoWrite, Task, mcp__sequential-thinking__sequentialthinking] +description: "Execute complex tasks with intelligent workflow management and cross-session persistence" +wave-enabled: true +complexity-threshold: 0.7 +performance-profile: complex +personas: [architect, analyzer, project-manager] +mcp-servers: [sequential, context7] +--- + +# /sc:task - Enhanced Task Management + +## Purpose +Execute complex tasks with intelligent workflow management, cross-session persistence, hierarchical task organization, and advanced orchestration capabilities. + +## Usage +``` +/sc:task [action] [target] [--strategy systematic|agile|enterprise] [--persist] [--hierarchy] [--delegate] +``` + +## Actions +- `create` - Create new project-level task hierarchy +- `execute` - Execute task with intelligent orchestration +- `status` - View task status across sessions +- `analytics` - Task performance and analytics dashboard +- `optimize` - Optimize task execution strategies +- `delegate` - Delegate tasks across multiple agents +- `validate` - Validate task completion with evidence + +## Arguments +- `target` - Task description, project scope, or existing task ID +- `--strategy` - Execution strategy (systematic, agile, enterprise) +- `--persist` - Enable cross-session task persistence +- `--hierarchy` - Create hierarchical task breakdown +- `--delegate` - Enable multi-agent task delegation +- `--wave-mode` - Enable wave-based execution +- `--validate` - Enforce quality gates and validation +- `--mcp-routing` - Enable intelligent MCP server routing + +## Execution Modes + +### Systematic Strategy +1. **Discovery Phase**: Comprehensive project analysis and scope definition +2. **Planning Phase**: Hierarchical task breakdown with dependency mapping +3. **Execution Phase**: Sequential execution with validation gates +4. **Validation Phase**: Evidence collection and quality assurance +5. **Optimization Phase**: Performance analysis and improvement recommendations + +### Agile Strategy +1. **Sprint Planning**: Priority-based task organization +2. **Iterative Execution**: Short cycles with continuous feedback +3. **Adaptive Planning**: Dynamic task adjustment based on outcomes +4. **Continuous Integration**: Real-time validation and testing +5. **Retrospective Analysis**: Learning and process improvement + +### Enterprise Strategy +1. **Stakeholder Analysis**: Multi-domain impact assessment +2. **Resource Allocation**: Optimal resource distribution across tasks +3. **Risk Management**: Comprehensive risk assessment and mitigation +4. **Compliance Validation**: Regulatory and policy compliance checks +5. **Governance Reporting**: Detailed progress and compliance reporting + +## Advanced Features + +### Task Hierarchy Management +- **Epic Level**: Large-scale project objectives (weeks to months) +- **Story Level**: Feature-specific implementations (days to weeks) +- **Task Level**: Specific actionable items (hours to days) +- **Subtask Level**: Granular implementation steps (minutes to hours) + +### Intelligent Task Orchestration +- **Dependency Resolution**: Automatic dependency detection and sequencing +- **Parallel Execution**: Independent task parallelization +- **Resource Optimization**: Intelligent resource allocation and scheduling +- **Context Sharing**: Cross-task context and knowledge sharing + +### Cross-Session Persistence +- **Task State Management**: Persistent task states across sessions +- **Context Continuity**: Preserved context and progress tracking +- **Historical Analytics**: Task execution history and learning +- **Recovery Mechanisms**: Automatic recovery from interruptions + +### Quality Gates and Validation +- **Evidence Collection**: Systematic evidence gathering during execution +- **Validation Criteria**: Customizable completion criteria +- **Quality Metrics**: Comprehensive quality assessment +- **Compliance Checks**: Automated compliance validation + +## Integration Points + +### Wave System Integration +- **Wave Coordination**: Multi-wave task execution strategies +- **Context Accumulation**: Progressive context building across waves +- **Performance Monitoring**: Real-time performance tracking and optimization +- **Error Recovery**: Graceful error handling and recovery mechanisms + +### MCP Server Coordination +- **Context7**: Framework patterns and library documentation +- **Sequential**: Complex analysis and multi-step reasoning +- **Magic**: UI component generation and design systems +- **Playwright**: End-to-end testing and performance validation + +### Persona Integration +- **Architect**: System design and architectural decisions +- **Analyzer**: Code analysis and quality assessment +- **Project Manager**: Resource allocation and progress tracking +- **Domain Experts**: Specialized expertise for specific task types + +## Performance Optimization + +### Execution Efficiency +- **Batch Operations**: Grouped execution for related tasks +- **Parallel Processing**: Independent task parallelization +- **Context Caching**: Reusable context and analysis results +- **Resource Pooling**: Shared resource utilization + +### Intelligence Features +- **Predictive Planning**: AI-driven task estimation and planning +- **Adaptive Execution**: Dynamic strategy adjustment based on progress +- **Learning Systems**: Continuous improvement from execution patterns +- **Optimization Recommendations**: Data-driven improvement suggestions + +## Usage Examples + +### Create Project-Level Task Hierarchy +``` +/sc:task create "Implement user authentication system" --hierarchy --persist --strategy systematic +``` + +### Execute with Multi-Agent Delegation +``` +/sc:task execute AUTH-001 --delegate --wave-mode --validate +``` + +### Analytics and Optimization +``` +/sc:task analytics --project AUTH --optimization-recommendations +``` + +### Cross-Session Task Management +``` +/sc:task status --all-sessions --detailed-breakdown +``` + +## Claude Code Integration +- **TodoWrite Integration**: Seamless session-level task coordination +- **Wave System**: Advanced multi-stage execution orchestration +- **Hook System**: Real-time task monitoring and optimization +- **MCP Coordination**: Intelligent server routing and resource utilization +- **Performance Monitoring**: Sub-100ms execution targets with comprehensive metrics + +## Success Criteria +- **Task Completion Rate**: >95% successful task completion +- **Performance Targets**: <100ms hook execution, <5s task creation +- **Quality Metrics**: >90% validation success rate +- **Cross-Session Continuity**: 100% task state preservation +- **Intelligence Effectiveness**: >80% accurate predictive planning \ No newline at end of file diff --git a/.claude/commands/sc/test.md b/.claude/commands/sc/test.md new file mode 100644 index 0000000..a049cfa --- /dev/null +++ b/.claude/commands/sc/test.md @@ -0,0 +1,34 @@ +--- +allowed-tools: [Read, Bash, Glob, TodoWrite, Edit, Write] +description: "Execute tests, generate test reports, and maintain test coverage" +--- + +# /sc:test - Testing and Quality Assurance + +## Purpose +Execute tests, generate comprehensive test reports, and maintain test coverage standards. + +## Usage +``` +/sc:test [target] [--type unit|integration|e2e|all] [--coverage] [--watch] +``` + +## Arguments +- `target` - Specific tests, files, or entire test suite +- `--type` - Test type (unit, integration, e2e, all) +- `--coverage` - Generate coverage reports +- `--watch` - Run tests in watch mode +- `--fix` - Automatically fix failing tests when possible + +## Execution +1. Discover and categorize available tests +2. Execute tests with appropriate configuration +3. Monitor test results and collect metrics +4. Generate comprehensive test reports +5. Provide recommendations for test improvements + +## Claude Code Integration +- Uses Bash for test execution and monitoring +- Leverages Glob for test discovery +- Applies TodoWrite for test result tracking +- Maintains structured test reporting and coverage analysis \ No newline at end of file diff --git a/.claude/commands/sc/troubleshoot.md b/.claude/commands/sc/troubleshoot.md new file mode 100644 index 0000000..2a8587b --- /dev/null +++ b/.claude/commands/sc/troubleshoot.md @@ -0,0 +1,33 @@ +--- +allowed-tools: [Read, Grep, Glob, Bash, TodoWrite] +description: "Diagnose and resolve issues in code, builds, or system behavior" +--- + +# /sc:troubleshoot - Issue Diagnosis and Resolution + +## Purpose +Systematically diagnose and resolve issues in code, builds, deployments, or system behavior. + +## Usage +``` +/sc:troubleshoot [issue] [--type bug|build|performance|deployment] [--trace] +``` + +## Arguments +- `issue` - Description of the problem or error message +- `--type` - Issue category (bug, build, performance, deployment) +- `--trace` - Enable detailed tracing and logging +- `--fix` - Automatically apply fixes when safe + +## Execution +1. Analyze issue description and gather initial context +2. Identify potential root causes and investigation paths +3. Execute systematic debugging and diagnosis +4. Propose and validate solution approaches +5. Apply fixes and verify resolution + +## Claude Code Integration +- Uses Read for error log analysis +- Leverages Bash for runtime diagnostics +- Applies Grep for pattern-based issue detection +- Maintains structured troubleshooting documentation \ No newline at end of file diff --git a/.claude/commands/sc/workflow.md b/.claude/commands/sc/workflow.md new file mode 100644 index 0000000..1e37de2 --- /dev/null +++ b/.claude/commands/sc/workflow.md @@ -0,0 +1,303 @@ +--- +allowed-tools: [Read, Write, Edit, Glob, Grep, TodoWrite, Task, mcp__sequential-thinking__sequentialthinking, mcp__context7__context7] +description: "Generate structured implementation workflows from PRDs and feature requirements with expert guidance" +wave-enabled: true +complexity-threshold: 0.6 +performance-profile: complex +personas: [architect, analyzer, frontend, backend, security, devops, project-manager] +mcp-servers: [sequential, context7, magic] +--- + +# /sc:workflow - Implementation Workflow Generator + +## Purpose +Analyze Product Requirements Documents (PRDs) and feature specifications to generate comprehensive, step-by-step implementation workflows with expert guidance, dependency mapping, and automated task orchestration. + +## Usage +``` +/sc:workflow [prd-file|feature-description] [--persona expert] [--c7] [--sequential] [--strategy systematic|agile|mvp] [--output roadmap|tasks|detailed] +``` + +## Arguments +- `prd-file|feature-description` - Path to PRD file or direct feature description +- `--persona` - Force specific expert persona (architect, frontend, backend, security, devops, etc.) +- `--strategy` - Workflow strategy (systematic, agile, mvp) +- `--output` - Output format (roadmap, tasks, detailed) +- `--estimate` - Include time and complexity estimates +- `--dependencies` - Map external dependencies and integrations +- `--risks` - Include risk assessment and mitigation strategies +- `--parallel` - Identify parallelizable work streams +- `--milestones` - Create milestone-based project phases + +## MCP Integration Flags +- `--c7` / `--context7` - Enable Context7 for framework patterns and best practices +- `--sequential` - Enable Sequential thinking for complex multi-step analysis +- `--magic` - Enable Magic for UI component workflow planning +- `--all-mcp` - Enable all MCP servers for comprehensive workflow generation + +## Workflow Strategies + +### Systematic Strategy (Default) +1. **Requirements Analysis** - Deep dive into PRD structure and acceptance criteria +2. **Architecture Planning** - System design and component architecture +3. **Dependency Mapping** - Identify all internal and external dependencies +4. **Implementation Phases** - Sequential phases with clear deliverables +5. **Testing Strategy** - Comprehensive testing approach at each phase +6. **Deployment Planning** - Production rollout and monitoring strategy + +### Agile Strategy +1. **Epic Breakdown** - Convert PRD into user stories and epics +2. **Sprint Planning** - Organize work into iterative sprints +3. **MVP Definition** - Identify minimum viable product scope +4. **Iterative Development** - Plan for continuous delivery and feedback +5. **Stakeholder Engagement** - Regular review and adjustment cycles +6. **Retrospective Planning** - Built-in improvement and learning cycles + +### MVP Strategy +1. **Core Feature Identification** - Strip down to essential functionality +2. **Rapid Prototyping** - Focus on quick validation and feedback +3. **Technical Debt Planning** - Identify shortcuts and future improvements +4. **Validation Metrics** - Define success criteria and measurement +5. **Scaling Roadmap** - Plan for post-MVP feature expansion +6. **User Feedback Integration** - Structured approach to user input + +## Expert Persona Auto-Activation + +### Frontend Workflow (`--persona frontend` or auto-detected) +- **UI/UX Analysis** - Design system integration and component planning +- **State Management** - Data flow and state architecture +- **Performance Optimization** - Bundle optimization and lazy loading +- **Accessibility Compliance** - WCAG guidelines and inclusive design +- **Browser Compatibility** - Cross-browser testing strategy +- **Mobile Responsiveness** - Responsive design implementation plan + +### Backend Workflow (`--persona backend` or auto-detected) +- **API Design** - RESTful/GraphQL endpoint planning +- **Database Schema** - Data modeling and migration strategy +- **Security Implementation** - Authentication, authorization, and data protection +- **Performance Scaling** - Caching, optimization, and load handling +- **Service Integration** - Third-party APIs and microservices +- **Monitoring & Logging** - Observability and debugging infrastructure + +### Architecture Workflow (`--persona architect` or auto-detected) +- **System Design** - High-level architecture and service boundaries +- **Technology Stack** - Framework and tool selection rationale +- **Scalability Planning** - Growth considerations and bottleneck prevention +- **Security Architecture** - Comprehensive security strategy +- **Integration Patterns** - Service communication and data flow +- **DevOps Strategy** - CI/CD pipeline and infrastructure as code + +### Security Workflow (`--persona security` or auto-detected) +- **Threat Modeling** - Security risk assessment and attack vectors +- **Data Protection** - Encryption, privacy, and compliance requirements +- **Authentication Strategy** - User identity and access management +- **Security Testing** - Penetration testing and vulnerability assessment +- **Compliance Validation** - Regulatory requirements (GDPR, HIPAA, etc.) +- **Incident Response** - Security monitoring and breach protocols + +### DevOps Workflow (`--persona devops` or auto-detected) +- **Infrastructure Planning** - Cloud architecture and resource allocation +- **CI/CD Pipeline** - Automated testing, building, and deployment +- **Environment Management** - Development, staging, and production environments +- **Monitoring Strategy** - Application and infrastructure monitoring +- **Backup & Recovery** - Data protection and disaster recovery planning +- **Performance Monitoring** - APM tools and performance optimization + +## Output Formats + +### Roadmap Format (`--output roadmap`) +``` +# Feature Implementation Roadmap +## Phase 1: Foundation (Week 1-2) +- [ ] Architecture design and technology selection +- [ ] Database schema design and setup +- [ ] Basic project structure and CI/CD pipeline + +## Phase 2: Core Implementation (Week 3-6) +- [ ] API development and authentication +- [ ] Frontend components and user interface +- [ ] Integration testing and security validation + +## Phase 3: Enhancement & Launch (Week 7-8) +- [ ] Performance optimization and load testing +- [ ] User acceptance testing and bug fixes +- [ ] Production deployment and monitoring setup +``` + +### Tasks Format (`--output tasks`) +``` +# Implementation Tasks +## Epic: User Authentication System +### Story: User Registration +- [ ] Design registration form UI components +- [ ] Implement backend registration API +- [ ] Add email verification workflow +- [ ] Create user onboarding flow + +### Story: User Login +- [ ] Design login interface +- [ ] Implement JWT authentication +- [ ] Add password reset functionality +- [ ] Set up session management +``` + +### Detailed Format (`--output detailed`) +``` +# Detailed Implementation Workflow +## Task: Implement User Registration API +**Persona**: Backend Developer +**Estimated Time**: 8 hours +**Dependencies**: Database schema, authentication service +**MCP Context**: Express.js patterns, security best practices + +### Implementation Steps: +1. **Setup API endpoint** (1 hour) + - Create POST /api/register route + - Add input validation middleware + +2. **Database integration** (2 hours) + - Implement user model + - Add password hashing + +3. **Security measures** (3 hours) + - Rate limiting implementation + - Input sanitization + - SQL injection prevention + +4. **Testing** (2 hours) + - Unit tests for registration logic + - Integration tests for API endpoint + +### Acceptance Criteria: +- [ ] User can register with email and password +- [ ] Passwords are properly hashed +- [ ] Email validation is enforced +- [ ] Rate limiting prevents abuse +``` + +## Advanced Features + +### Dependency Analysis +- **Internal Dependencies** - Identify coupling between components and features +- **External Dependencies** - Map third-party services and APIs +- **Technical Dependencies** - Framework versions, database requirements +- **Team Dependencies** - Cross-team coordination requirements +- **Infrastructure Dependencies** - Cloud services, deployment requirements + +### Risk Assessment & Mitigation +- **Technical Risks** - Complexity, performance, and scalability concerns +- **Timeline Risks** - Dependency bottlenecks and resource constraints +- **Security Risks** - Data protection and compliance vulnerabilities +- **Business Risks** - Market changes and requirement evolution +- **Mitigation Strategies** - Fallback plans and alternative approaches + +### Parallel Work Stream Identification +- **Independent Components** - Features that can be developed simultaneously +- **Shared Dependencies** - Common components requiring coordination +- **Critical Path Analysis** - Bottlenecks that block other work +- **Resource Allocation** - Team capacity and skill distribution +- **Communication Protocols** - Coordination between parallel streams + +## Integration with SuperClaude Ecosystem + +### TodoWrite Integration +- Automatically creates session tasks for immediate next steps +- Provides progress tracking throughout workflow execution +- Links workflow phases to actionable development tasks + +### Task Command Integration +- Converts workflow into hierarchical project tasks (`/sc:task`) +- Enables cross-session persistence and progress tracking +- Supports complex orchestration with `/sc:spawn` + +### Implementation Command Integration +- Seamlessly connects to `/sc:implement` for feature development +- Provides context-aware implementation guidance +- Auto-activates appropriate personas for each workflow phase + +### Analysis Command Integration +- Leverages `/sc:analyze` for codebase assessment +- Integrates existing code patterns into workflow planning +- Identifies refactoring opportunities and technical debt + +## Usage Examples + +### Generate Workflow from PRD File +``` +/sc:workflow docs/feature-100-prd.md --strategy systematic --c7 --sequential --estimate +``` + +### Create Frontend-Focused Workflow +``` +/sc:workflow "User dashboard with real-time analytics" --persona frontend --magic --output detailed +``` + +### MVP Planning with Risk Assessment +``` +/sc:workflow user-authentication-system --strategy mvp --risks --parallel --milestones +``` + +### Backend API Workflow with Dependencies +``` +/sc:workflow payment-processing-api --persona backend --dependencies --c7 --output tasks +``` + +### Full-Stack Feature Workflow +``` +/sc:workflow social-media-integration --all-mcp --sequential --parallel --estimate --output roadmap +``` + +## Quality Gates and Validation + +### Workflow Completeness Check +- **Requirements Coverage** - Ensure all PRD requirements are addressed +- **Acceptance Criteria** - Validate testable success criteria +- **Technical Feasibility** - Assess implementation complexity and risks +- **Resource Alignment** - Match workflow to team capabilities and timeline + +### Best Practices Validation +- **Architecture Patterns** - Ensure adherence to established patterns +- **Security Standards** - Validate security considerations at each phase +- **Performance Requirements** - Include performance targets and monitoring +- **Maintainability** - Plan for long-term code maintenance and updates + +### Stakeholder Alignment +- **Business Requirements** - Ensure business value is clearly defined +- **Technical Requirements** - Validate technical specifications and constraints +- **Timeline Expectations** - Realistic estimation and milestone planning +- **Success Metrics** - Define measurable outcomes and KPIs + +## Performance Optimization + +### Workflow Generation Speed +- **PRD Parsing** - Efficient document analysis and requirement extraction +- **Pattern Recognition** - Rapid identification of common implementation patterns +- **Template Application** - Reusable workflow templates for common scenarios +- **Incremental Generation** - Progressive workflow refinement and optimization + +### Context Management +- **Memory Efficiency** - Optimal context usage for large PRDs +- **Caching Strategy** - Reuse analysis results across similar workflows +- **Progressive Loading** - Load workflow details on-demand +- **Compression** - Efficient storage and retrieval of workflow data + +## Success Metrics + +### Workflow Quality +- **Implementation Success Rate** - >90% successful feature completion following workflows +- **Timeline Accuracy** - <20% variance from estimated timelines +- **Requirement Coverage** - 100% PRD requirement mapping to workflow tasks +- **Stakeholder Satisfaction** - >85% satisfaction with workflow clarity and completeness + +### Performance Targets +- **Workflow Generation** - <30 seconds for standard PRDs +- **Dependency Analysis** - <60 seconds for complex systems +- **Risk Assessment** - <45 seconds for comprehensive evaluation +- **Context Integration** - <10 seconds for MCP server coordination + +## Claude Code Integration +- **Multi-Tool Orchestration** - Coordinates Read, Write, Edit, Glob, Grep for comprehensive analysis +- **Progressive Task Creation** - Uses TodoWrite for immediate next steps and Task for long-term planning +- **MCP Server Coordination** - Intelligent routing to Context7, Sequential, and Magic based on workflow needs +- **Cross-Command Integration** - Seamless handoff to implement, analyze, design, and other SuperClaude commands +- **Evidence-Based Planning** - Maintains audit trail of decisions and rationale throughout workflow generation \ No newline at end of file diff --git a/COMMAND.md b/COMMAND.md new file mode 100644 index 0000000..b955554 --- /dev/null +++ b/COMMAND.md @@ -0,0 +1,48 @@ +# Claude Code Command List + +| Command | Description | Category | +| ----------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------- | +| /canvas/create_from_dir | Analyzes markdown files in a specified directory, groups related content, and generates a JSON Canvas with nodes and edges. | Canvas | +| /debug | Debug process guidelines for identifying and fixing issues. | Debug | +| /design/system-architecture/1-create-architecture-framework | Creates a comprehensive system architecture framework including domain separation, layered architecture, and component responsibility definitions. | Design - System Architecture | +| /design/system-architecture/2-design-components | Designs detailed system components with specifications, interfaces, and implementation guidelines based on architecture framework. | Design - System Architecture | +| /design/system-architecture/3-integration-architecture | Designs system integration architecture including communication protocols, data flow, and service integration patterns. | Design - System Architecture | +| /design/system-architecture/4-generate-architecture-summary | Generates a comprehensive architecture summary that consolidates all system architecture components into a unified documentation package. | Design - System Architecture | +| /planning/mrd/1-start-session | Starts a new or updated MRD (Market Requirements Document) research session. | Planning - MRD | +| /planning/mrd/2-analyze-research-data | Analyzes user-submitted research data, provides insights, and suggests the next research step. | Planning - MRD | +| /planning/mrd/3-generate-mrd-document | Generates the final MRD document by consolidating all research and analysis from a session. | Planning - MRD | +| /planning/mrd/4-compare-mrd-versions | Compares two MRD documents and generates a detailed comparison report. | Planning - MRD | +| /planning/brainstorm/1-start-brainstorm | Starts a new brainstorming session or continues an existing one. | Planning - Brainstorm | +| /planning/brainstorm/2-analyze-ideas | Analyzes ideas from the brainstorming session and generates insights. | Planning - Brainstorm | +| /planning/brainstorm/3-generate-brainstorm-summary | Generates a comprehensive brainstorm summary from all analyzed ideas. | Planning - Brainstorm | +| /planning/roadmap/1-create-from-mrd | Creates a product roadmap based on an MRD document. | Planning - Roadmap | +| /planning/roadmap/2-create-from-brainstorm | Creates a product roadmap based on a brainstorm summary. | Planning - Roadmap | +| /planning/create-app-design | Creates a comprehensive app design document based on user requirements. | Planning | +| /planning/create-doc | Creates a new documentation file based on user request. | Planning | +| /planning/create-prd-interactive | Interactively creates a Product Requirements Document (PRD) through guided questions. | Planning | +| /planning/create-prd | Creates a Product Requirements Document (PRD) based on user input. | Planning | +| /planning/create-rule | Creates a new coding rule file based on user description. | Planning | +| /planning/create-tech-stack | Creates a comprehensive tech stack recommendation based on project requirements. | Planning | +| /planning/parse-prd | Parses a PRD file and generates tasks. | Planning | +| /planning/update-app-design | Updates an existing app design document based on new requirements. | Planning | +| /planning/update-project-structure | Updates the project structure based on changes. | Planning | +| /planning/update-rule | Updates an existing coding rule file based on user input. | Planning | +| /planning/update-tech-stack | Updates an existing tech stack recommendation based on new requirements. | Planning | +| /research/architecture | Performs research on architecture topics. | Research | +| /research/security | Performs research on security topics. | Research | +| /research/task | Performs research on specific tasks. | Research | +| /research/tech | Performs research on technology topics. | Research | +| /snippets/create-snippet | Creates a code snippet based on user request. | Snippets | +| /task/add | Add one or more tasks to the current tag. | Task | +| /task/add-interactive | Interactively adds a task through guided questions. | Task | +| /task/done | Marks a task as done. | Task | +| /task/expand | Expands a task into subtasks. | Task | +| /task/generate | Generates task files. | Task | +| /task/list | Lists tasks in the current tag. | Task | +| /task/move | Moves tasks between tags or positions. | Task | +| /task/next | Shows the next task to work on. | Task | +| /task/research | Performs research related to a task. | Task | +| /task/show | Shows details of a specific task. | Task | +| /task/spec | Displays task specifications. | Task | +| /task/update-task-interactive | Interactively updates a task. | Task | +| /task/update-task | Updates a specific task. | Task |