ai-playbook 1.0.0

package/skills/architecture/README.md

@@ -0,0 +1,198 @@
+# Architecture Skill
+
+## Overview
+
+The Architecture skill provides the ability to design, analyze, and evolve complex systems with clear separation of concerns, scalability, and maintainability. It encompasses system-level design patterns, component relationships, data flows, integration strategies, and architectural decision-making that balance technical requirements with business constraints. This skill is essential for building systems that can grow, adapt, and be understood by teams at any scale.
+
+---
+
+## Goals
+
+- **Design Scalable Systems**: Create architectures that grow efficiently as requirements evolve and load increases
+- **Minimize Coupling**: Reduce dependencies between components to enable independent development and deployment
+- **Enable Incremental Evolution**: Design systems that can be modified, upgraded, and modernized without major rewrites
+- **Manage Complexity**: Decompose complex problems into manageable components with clear responsibilities
+- **Document Decisions**: Create living architectural documentation that explains trade-offs and informs future decisions
+- **Validate Assumptions**: Test critical architectural decisions early to reduce risk and identify bottlenecks
+- **Enable Team Growth**: Create systems that new team members can understand within reasonable timeframes
+- **Build Resilience**: Design systems that degrade gracefully when components fail
+
+---
+
+## Capabilities
+
+### System Design
+- **System Decomposition**: Break problems into discrete, manageable components
+- **Layered Architecture**: Design horizontal layers with clear contracts
+- **Domain-Driven Design**: Apply DDD principles for complex domain modeling
+- **Evolutionary Architecture**: Design for incremental modification and refactoring
+
+### Data Architecture
+- **Data Modeling**: Design schemas and data structures aligned with requirements
+- **Scalability**: Plan for database scaling through replication, sharding, partitioning
+- **Consistency**: Design consistency models for distributed data systems
+- **Storage Strategy**: Choose appropriate storage technologies and patterns
+
+### Integration Architecture
+- **API Design**: Design APIs with clear contracts for loose coupling
+- **Integration Patterns**: Select appropriate patterns (APIs, queues, webhooks, events)
+- **Service Communication**: Plan synchronous and asynchronous communication
+- **Contract Management**: Manage API versioning and evolution
+
+### Async & Event-Driven Systems
+- **Asynchronous Patterns**: Design async systems for resilience and scalability
+- **Event Sourcing**: Build systems with audit trails and temporal queries
+- **Message Brokers**: Design reliable message-based communication
+- **Consistency Models**: Handle eventual consistency and conflict resolution
+
+### Resilience & Reliability
+- **Fault Tolerance**: Design systems that handle failures gracefully
+- **Failure Prevention**: Use circuit breakers, bulkheads, and isolation patterns
+- **Recovery**: Plan disaster recovery and data restoration
+- **Health Monitoring**: Design health checks and alerting
+
+### Performance & Scalability
+- **Bottleneck Analysis**: Identify and eliminate performance bottlenecks
+- **Caching Strategy**: Design multi-level caching for performance
+- **Load Balancing**: Plan for distribution of work across resources
+- **Performance Testing**: Design benchmarking and profiling strategies
+
+### Security & Compliance
+- **Security Architecture**: Design systems with security as a first-class concern
+- **Access Control**: Plan authentication, authorization, and multi-tenancy
+- **Encryption**: Design encryption strategies at-rest and in-transit
+- **Secrets Management**: Manage sensitive configuration securely
+
+### Observability
+- **Distributed Tracing**: Design tracing across service boundaries
+- **Metrics**: Create hierarchical metrics for understanding system behavior
+- **Logging**: Design structured logging for rapid diagnosis
+- **Alerting**: Create alert strategies that reduce false positives
+
+### Documentation & Decision Making
+- **Architecture Decision Records**: Document decisions with rationale and trade-offs
+- **Diagrams**: Create C4 models, component diagrams, data flows
+- **Technology Selection**: Evaluate and document technology choices
+- **Trade-off Analysis**: Explicitly document alternatives and trade-offs
+
+---
+
+## When to Use
+
+**Use this skill when you need to:**
+- Design a new system or major subsystem from scratch
+- Decompose a monolithic application into smaller services
+- Evaluate technology choices for a new project
+- Optimize a system for scalability, performance, or resilience
+- Design a migration or modernization strategy
+- Establish patterns for how teams will build and integrate components
+- Document architectural decisions and trade-offs
+- Analyze technical risks in a proposed design
+- Plan for system evolution and growth
+
+**Typical scenarios:**
+- Pre-development design phase for significant features or systems
+- Architecture review before starting a major project
+- System scaling analysis when hitting performance limits
+- Legacy system modernization planning
+- Team scaling or reorganization based on system architecture
+- Technology evaluation for new requirements
+
+---
+
+## Expected Workflow
+
+```
+Requirements & Constraints
+        ↓
+Understand Current State
+(if applicable)
+        ↓
+Identify Design Options
+        ↓
+Create Architecture Diagrams
+        ↓
+Analyze Trade-offs
+        ↓
+Select Approach
+        ↓
+Design Components & Interfaces
+        ↓
+Plan Data Architecture
+        ↓
+Design Integration Points
+        ↓
+Create Implementation Roadmap
+        ↓
+Document Decisions (ADRs)
+        ↓
+Validation & Stakeholder Review
+```
+
+---
+
+## Inputs
+
+- **Requirements**: Functional and non-functional requirements (latency, throughput, consistency, scale targets)
+- **Constraints**: Budget, team size, existing technology investments, compliance needs
+- **Current State**: Analysis of existing systems, if migrating or integrating
+- **Success Criteria**: Metrics that define a successful architecture
+- **Timeline**: Expected timeline for implementation and growth
+- **Team Structure**: How teams are organized and how systems will be owned
+
+---
+
+## Outputs
+
+- **Architecture Diagrams**: System context, component, deployment, data flow diagrams
+- **Component Specifications**: Component boundaries, interfaces, responsibilities
+- **Data Architecture**: Schema designs, consistency strategies, scaling plans
+- **Integration Design**: API specifications, communication patterns
+- **Technology Selection**: Evaluated options with rationale
+- **Architecture Decision Records**: Documented decisions and trade-offs
+- **Implementation Roadmap**: Phased approach with dependencies and milestones
+- **Risk Assessment**: Identified risks and mitigation strategies
+- **Team Organization**: How teams align with architectural boundaries
+
+---
+
+## Related Skills
+
+- **Design Architecture**: UI/UX design, component design, interaction patterns
+- **DevOps**: Infrastructure architecture, deployment automation, production operations
+- **Performance**: Performance optimization, profiling, benchmarking
+- **Documentation**: Technical writing, API documentation, knowledge bases
+- **Security**: Security patterns, threat modeling, access control
+- **Software Development**: Code organization, testing strategies, development workflows
+
+---
+
+## Best Practices
+
+1. **Start with Requirements, Not Technology**: Understand what you're building before deciding how to build it
+2. **Document Trade-offs**: Every decision involves trade-offs; make them explicit
+3. **Validate Assumptions Early**: Build proof-of-concepts for critical architectural decisions
+4. **Design for Change**: Assume requirements will evolve; design for incremental modification
+5. **Minimize Coupling**: Reduce dependencies between components through clear interfaces
+6. **Consistency Over Perfection**: Use consistent patterns even if not optimal for every case
+7. **Build in Observability**: Design systems that can be understood and debugged in production
+8. **Plan for Evolution**: Design systems that can be upgraded, refactored, and modernized
+9. **Review Continuously**: Regularly review architecture against current and anticipated requirements
+10. **Involve Stakeholders**: Get alignment on architecture with all affected parties
+
+---
+
+## Success Criteria
+
+1. **Meets Requirements**: Architecture addresses all functional and non-functional requirements
+2. **Stakeholder Alignment**: Architecture decisions are understood and agreed by all stakeholders
+3. **Clear Decomposition**: Components have clear boundaries and responsibilities
+4. **Flexible**: System can be modified incrementally without major rewrites
+5. **Scalable**: Architecture can accommodate growth in load, data, and complexity
+6. **Maintainable**: New team members can understand the system within reasonable timeframes
+7. **Resilient**: System handles failures gracefully without cascading impacts
+8. **Documented**: Architecture is thoroughly documented with clear rationale
+9. **Consistent**: Patterns are applied consistently throughout the system
+10. **Testable**: Critical architectural decisions can be validated before full implementation
+
+---

package/skills/architecture/examples.md

@@ -0,0 +1,316 @@
+# Architecture Skill - Examples
+
+## Example 1: Monolith to Microservices Migration
+
+**User Request**: "Our monolithic application has grown to 500k lines of code. Multiple teams are blocked waiting for deployment windows. We need a plan to decompose this into microservices without disrupting existing functionality."
+
+**Expected Behavior**:
+- Identify service boundaries using domain-driven design principles
+- Map current monolithic components to proposed services
+- Design strangler pattern approach to extract services incrementally
+- Define service contracts and communication patterns
+- Create phased migration roadmap (6-12 months)
+- Document team structure aligned with service ownership
+- Identify shared infrastructure needs (service mesh, API gateway)
+
+**Success Criteria**:
+- Teams can deploy independently within 3 months
+- No breaking changes to external APIs during migration
+- Clear service boundaries documented and agreed by stakeholders
+- Rollback strategies defined for each migration phase
+
+---
+
+## Example 2: Data Architecture for Scaling
+
+**User Request**: "Our relational database is handling 100M queries/day and we're hitting CPU limits. Design a scalability strategy that maintains ACID properties where needed and handles 10x growth."
+
+**Expected Behavior**:
+- Analyze query patterns to identify hot tables and partitioning keys
+- Design read replica strategy for read-heavy workloads
+- Create sharding strategy with clear partition keys
+- Identify queries that need cross-shard transactions
+- Design caching layer (distributed cache) for frequently accessed data
+- Plan for backup and disaster recovery at scale
+- Create migration plan with minimal downtime
+
+**Success Criteria**:
+- Database can handle 1B queries/day with <50ms p99 latency
+- Data consistency maintained across partitions
+- Backup/recovery tested and validated
+- Team trained on new architecture patterns
+
+---
+
+## Example 3: API Contract Management
+
+**User Request**: "We have 15 internal services and 30+ external API consumers. How do we design APIs that allow independent evolution without breaking integrations?"
+
+**Expected Behavior**:
+- Define API versioning strategy (URL vs. header-based)
+- Create contract-first design process with OpenAPI/GraphQL schemas
+- Design deprecation policy with 6-month notice period
+- Establish API governance board for breaking changes
+- Design API gateway for request/response transformation
+- Create SDK generation from schemas for consistency
+- Document backward compatibility guarantees
+
+**Success Criteria**:
+- No unplanned API outages due to incompatibility
+- New API versions can coexist with old versions
+- Consumers have 6 months warning before deprecation
+- SDK generation automated, reducing client errors
+
+---
+
+## Example 4: Resilience & Fault Tolerance Design
+
+**User Request**: "Our system depends on 5 external APIs. When one fails, the entire system degrades. Design a resilient architecture that gracefully handles partial failures."
+
+**Expected Behavior**:
+- Map dependencies and identify single points of failure
+- Design circuit breaker patterns for each external API
+- Create bulkhead pattern to isolate failure domains
+- Plan timeout strategies and retry logic
+- Design fallback mechanisms (cache, default values, degraded mode)
+- Implement health checks with clear failure thresholds
+- Create chaos engineering strategy to test resilience
+
+**Success Criteria**:
+- System remains operational with 1-2 external API failures
+- User-facing impact <5% when non-critical dependency fails
+- Automatic failover to fallback strategies within seconds
+- Monthly chaos tests validate resilience
+
+---
+
+## Example 5: Event-Driven Architecture Design
+
+**User Request**: "We need to build a real-time notification system that processes millions of events per day with guaranteed ordering and exactly-once delivery across multiple services."
+
+**Expected Behavior**:
+- Design event schema with versioning strategy
+- Select message broker technology (Kafka, RabbitMQ, etc.)
+- Design partition key strategy to maintain ordering
+- Plan for exactly-once processing semantics
+- Design dead-letter queue handling for failed events
+- Create event replay strategy for debugging
+- Design consumer groups for independent processing
+
+**Success Criteria**:
+- Events processed in order within same partition
+- No duplicate processing detected in tests
+- Failed events recoverable and retryable
+- System can handle 10x traffic spike without data loss
+
+---
+
+## Example 6: Security Architecture for Multi-tenant System
+
+**User Request**: "Design a secure multi-tenant architecture where one customer's data cannot leak to another, and sensitive operations require additional authorization."
+
+**Expected Behavior**:
+- Design tenant isolation strategy (database, schema, row-level)
+- Implement row-level security policies
+- Design authentication and authorization patterns
+- Create API design with tenant context enforcement
+- Plan for sensitive operations requiring additional factors
+- Design encryption strategy (at-rest and in-transit)
+- Create audit logging for compliance
+
+**Success Criteria**:
+- Automated tests verify no data leakage between tenants
+- All sensitive operations require additional authorization
+- Encryption keys rotated without downtime
+- Audit logs enable regulatory compliance verification
+
+---
+
+## Example 7: Observability Architecture Design
+
+**User Request**: "We need to understand what's happening in production across 20+ services. Design an observability system that enables rapid incident diagnosis."
+
+**Expected Behavior**:
+- Design distributed tracing across all services
+- Create metrics hierarchy with business and technical metrics
+- Design structured logging with context propagation
+- Plan alert strategy with clear escalation paths
+- Create dashboards for different audiences (ops, business, eng)
+- Design sampling strategy for high-volume systems
+- Plan for cost-effective storage of telemetry
+
+**Success Criteria**:
+- Any production incident diagnosed within 5 minutes
+- Root cause identification automated for >80% of incidents
+- Dashboards show system health in real-time
+- Cost per event <$0.001 for telemetry storage
+
+---
+
+## Example 8: Technology Selection for New Project
+
+**User Request**: "We're building a new product line with different requirements than our existing monolith. Recommend technology stack and justify selections."
+
+**Expected Behavior**:
+- Evaluate requirements (latency, throughput, consistency, scale)
+- Assess framework options for each layer
+- Compare language choices with team expertise
+- Evaluate database options with trade-off analysis
+- Plan for operational burden and monitoring needs
+- Create migration strategy if integrating with existing systems
+- Document technology decisions and rationale
+
+**Success Criteria**:
+- Technology selection enables meeting all requirements
+- Team trained and confident in selected technologies
+- Prototype validates key architectural assumptions
+- Decision document updated as requirements evolve
+
+---
+
+## Example 9: Configuration & Secrets Management
+
+**User Request**: "We're managing 10 different deployment environments with different configurations. Design a configuration system that's secure, flexible, and doesn't require redeployment."
+
+**Expected Behavior**:
+- Design configuration hierarchy (global, environment, service)
+- Implement secrets management (rotation, access control)
+- Create feature flag system for safe feature rollout
+- Design A/B testing framework using feature flags
+- Plan for configuration changes without redeployment
+- Create rollback strategy for configuration errors
+- Audit all configuration changes
+
+**Success Criteria**:
+- Configuration changes take effect within 30 seconds
+- No secrets exposed in logs or error messages
+- Feature flags enable safe canary deployments
+- Configuration rollback automatic if health checks fail
+
+---
+
+## Example 10: Dependency Management Strategy
+
+**User Request**: "We have hundreds of transitive dependencies and spend 2 weeks per quarter on security updates. Design a dependency management strategy that reduces this burden."
+
+**Expected Behavior**:
+- Audit all direct and transitive dependencies
+- Create policies for dependency selection and updates
+- Implement automated vulnerability scanning
+- Design monorepo structure for consistent versions
+- Plan for major version upgrades with impact analysis
+- Create testing strategy for dependency changes
+- Implement supply chain security measures
+
+**Success Criteria**:
+- Security updates applied automatically for patch versions
+- Monthly vulnerability scans detect 99% of known issues
+- Dependency upgrade process takes <2 hours per major version
+- No supply chain attacks detected
+
+---
+
+## Example 11: Domain-Driven Design for Large System
+
+**User Request**: "Our system spans multiple business domains and teams are stepping on each other. Use DDD to reorganize around bounded contexts."
+
+**Expected Behavior**:
+- Facilitate domain analysis workshops with subject matter experts
+- Identify bounded contexts and ubiquitous language
+- Create context maps showing service relationships
+- Design aggregate boundaries within each context
+- Plan for anti-corruption layers between contexts
+- Design data consistency strategy across contexts
+- Align team structure with bounded contexts
+
+**Success Criteria**:
+- Teams have clear ownership of bounded contexts
+- Service dependencies map to bounded contexts
+- Teams can deploy independently without coordination
+- Ubiquitous language documented and used consistently
+
+---
+
+## Example 12: Caching Strategy Design
+
+**User Request**: "Our database is handling user profile requests but latency is 200ms. Design a caching strategy that gets latency to <10ms while keeping data fresh."
+
+**Expected Behavior**:
+- Analyze read/write patterns and cache hit targets
+- Design multi-level caching (in-process, distributed)
+- Choose cache eviction policy (LRU, LFU, TTL)
+- Plan invalidation strategy (time-based, event-based)
+- Design cache warming strategy
+- Plan for cache stampede prevention
+- Create monitoring for cache effectiveness
+
+**Success Criteria**:
+- Cache hit rate >85% for profile queries
+- Latency reduced to <10ms for cached queries
+- Stale data window <5 minutes
+- Cache miss latency acceptable
+
+---
+
+## Example 13: Async Processing Architecture
+
+**User Request**: "We have expensive background jobs that block user requests. Design an async processing system with guaranteed execution and retry logic."
+
+**Expected Behavior**:
+- Design job queue system with priority levels
+- Plan retry strategy with exponential backoff
+- Design dead-letter queue for failed jobs
+- Create job monitoring and alerting
+- Plan for job deduplication
+- Design graceful shutdown of workers
+- Create visibility into job status
+
+**Success Criteria**:
+- User requests return immediately
+- Jobs complete within SLA 99% of time
+- Failed jobs automatically retried without data loss
+- Job processing scales with load automatically
+
+---
+
+## Example 14: API Gateway & Service Mesh Design
+
+**User Request**: "We're moving to microservices and need consistent API routing, rate limiting, and service-to-service security. Design the control plane."
+
+**Expected Behavior**:
+- Design API gateway for client request routing
+- Plan rate limiting strategy (per-user, per-IP, global)
+- Design service mesh for inter-service communication
+- Create mTLS strategy for service-to-service auth
+- Plan for observability in service mesh
+- Design traffic routing policies (canary, blue-green)
+- Create failure injection for chaos engineering
+
+**Success Criteria**:
+- Clients see single entry point for APIs
+- Rate limiting prevents abuse without impacting legitimate traffic
+- Service-to-service communication encrypted by default
+- Traffic policies enable safe deployments
+
+---
+
+## Example 15: Legacy System Modernization Roadmap
+
+**User Request**: "We have a 10-year-old system with significant technical debt. Create a modernization roadmap that maintains revenue while improving code quality."
+
+**Expected Behavior**:
+- Audit current system architecture and dependencies
+- Identify strangler pattern migration candidates
+- Prioritize modernization by impact and effort
+- Design anti-corruption layers for gradual migration
+- Plan feature flag strategy for gradual rollout
+- Create team capacity planning for refactoring
+- Design rollback strategies for each phase
+
+**Success Criteria**:
+- Legacy system continues generating revenue during migration
+- Code quality metrics improve incrementally
+- Team velocity increases as debt is reduced
+- No major outages during modernization
+
+---