ai-playbook 1.0.0

package/roles/devops/kubernetes/examples.md

@@ -0,0 +1,189 @@
+# Kubernetes Examples
+
+Kubernetes deployment examples are provided in the parent `roles/devops/examples.md` with a complete Helm chart example covering:
+
+- Deployment with security best practices (non-root, read-only filesystem)
+- Health checks (liveness and readiness probes)
+- Resource requests and limits
+- Environment variables from ConfigMaps
+- Secrets management
+- Horizontal Pod Autoscaling (HPA)
+
+---
+
+## Additional Resources
+
+For more comprehensive Kubernetes examples:
+
+- Official Kubernetes examples: https://kubernetes.io/docs/tasks/
+- Helm chart best practices: https://helm.sh/docs/chart_best_practices/
+- Kubernetes security hardening: https://kubernetes.io/docs/concepts/security/
+
+---
+
+## Common Kubernetes Patterns
+
+### Pattern: Stateless Application
+
+```yaml
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: myapp
+spec:
+  replicas: 3
+  template:
+    spec:
+      containers:
+      - name: myapp
+        image: myapp:1.0.0
+        ports:
+        - containerPort: 8080
+        resources:
+          requests:
+            cpu: 100m
+            memory: 128Mi
+          limits:
+            cpu: 500m
+            memory: 512Mi
+        livenessProbe:
+          httpGet:
+            path: /health
+            port: 8080
+          periodSeconds: 10
+        readinessProbe:
+          httpGet:
+            path: /ready
+            port: 8080
+          periodSeconds: 5
+```
+
+### Pattern: StatefulSet with Persistent Storage
+
+```yaml
+apiVersion: apps/v1
+kind: StatefulSet
+metadata:
+  name: database
+spec:
+  serviceName: database
+  replicas: 3
+  template:
+    spec:
+      containers:
+      - name: database
+        image: postgres:15
+        volumeMounts:
+        - name: data
+          mountPath: /var/lib/postgresql
+  volumeClaimTemplates:
+  - metadata:
+      name: data
+    spec:
+      accessModes: ["ReadWriteOnce"]
+      resources:
+        requests:
+          storage: 100Gi
+```
+
+### Pattern: ConfigMap for Configuration
+
+```yaml
+apiVersion: v1
+kind: ConfigMap
+metadata:
+  name: myapp-config
+data:
+  log_level: "INFO"
+  database_pool_size: "10"
+  feature_flags: |
+    {
+      "new_ui": true,
+      "beta_api": false
+    }
+---
+apiVersion: v1
+kind: Pod
+metadata:
+  name: myapp
+spec:
+  containers:
+  - name: myapp
+    image: myapp:1.0.0
+    env:
+    - name: LOG_LEVEL
+      valueFrom:
+        configMapKeyRef:
+          name: myapp-config
+          key: log_level
+    volumeMounts:
+    - name: config
+      mountPath: /etc/config
+  volumes:
+  - name: config
+    configMap:
+      name: myapp-config
+```
+
+### Pattern: Network Policy
+
+```yaml
+apiVersion: networking.k8s.io/v1
+kind: NetworkPolicy
+metadata:
+  name: default-deny-ingress
+spec:
+  podSelector: {}
+  policyTypes:
+  - Ingress
+---
+apiVersion: networking.k8s.io/v1
+kind: NetworkPolicy
+metadata:
+  name: allow-from-frontend
+spec:
+  podSelector:
+    matchLabels:
+      app: backend
+  policyTypes:
+  - Ingress
+  ingress:
+  - from:
+    - podSelector:
+        matchLabels:
+          app: frontend
+    ports:
+    - protocol: TCP
+      port: 8080
+```
+
+### Pattern: HorizontalPodAutoscaler
+
+```yaml
+apiVersion: autoscaling/v2
+kind: HorizontalPodAutoscaler
+metadata:
+  name: myapp-hpa
+spec:
+  scaleTargetRef:
+    apiVersion: apps/v1
+    kind: Deployment
+    name: myapp
+  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
+```
+
+These patterns cover common Kubernetes deployment scenarios. Adapt them to your specific requirements.

package/roles/devops/monitoring/README.md

@@ -0,0 +1,93 @@
+# Monitoring, Logging & Observability Guidance
+
+This folder provides guidance for implementing comprehensive observability systems including metrics, logging, tracing, and alerting.
+
+## Scope
+
+Use this guidance when:
+
+- Setting up metrics collection and dashboards
+- Implementing centralized logging
+- Configuring alerting and incident response
+- Designing SLOs and error budgets
+- Implementing distributed tracing
+- Troubleshooting production issues
+
+## Core Components
+
+### Metrics
+- **Collection:** Prometheus, CloudWatch, Stackdriver
+- **Storage:** Time-series database (InfluxDB, Prometheus)
+- **Visualization:** Grafana, CloudWatch, Datadog
+- **Focus:** Infrastructure and application performance
+
+### Logging
+- **Collection:** Fluentd, Filebeat, Logstash
+- **Storage:** Elasticsearch, CloudLogging, Splunk
+- **Analysis:** Log aggregation and search
+- **Focus:** Debugging and compliance
+
+### Tracing
+- **Collection:** Jaeger, Zipkin, OpenTelemetry
+- **Storage:** Backend (Jaeger, Tempo, etc.)
+- **Analysis:** Request flow and latency analysis
+- **Focus:** Performance and debugging
+
+### Alerting
+- **Rules:** Prometheus, CloudWatch, custom
+- **Routing:** AlertManager, PagerDuty, Slack
+- **Escalation:** On-call schedules
+- **Focus:** Incident notification
+
+## Key Metrics to Monitor
+
+### Application Metrics
+- Request rate (requests per second)
+- Error rate (percentage of failed requests)
+- Latency (p50, p95, p99 response times)
+- Throughput (processed items per second)
+
+### Infrastructure Metrics
+- CPU utilization
+- Memory utilization
+- Disk usage
+- Network I/O
+- Disk I/O
+
+### Database Metrics
+- Query latency
+- Connection pool usage
+- Slow queries
+- Replication lag
+- Query errors
+
+### Container/Kubernetes Metrics
+- Pod CPU and memory usage
+- Container restart count
+- Pod eviction count
+- Cluster capacity
+
+## SLO Definition
+
+- **Availability SLO:** Uptime percentage (e.g., 99.9%)
+- **Latency SLO:** Response time percentile (e.g., p99 < 500ms)
+- **Error Rate SLO:** Acceptable error percentage (e.g., < 0.1%)
+- **Error Budget:** Allowed downtime/errors per period
+
+## Alerting Strategy
+
+- **Critical Alerts:** Page on-call immediately
+- **Warning Alerts:** Notify team but don't page
+- **Info Alerts:** Log for later investigation
+- **Tuning:** Minimize false positives and alert fatigue
+
+## Related Files
+
+- `roles/devops/examples.md` – Prometheus/Grafana configuration examples
+- `roles/devops/checklists.md` – Monitoring & Observability Checklist
+
+## Files in This Folder
+
+- `README.md` – This file
+- `checklists.md` – Monitoring implementation checklist
+- `examples.md` – Monitoring configuration examples

package/roles/devops/networking/README.md

@@ -0,0 +1,83 @@
+# Networking Guidance
+
+This folder provides guidance for designing and implementing cloud network infrastructure including VPCs, subnets, load balancing, DNS, and security.
+
+## Scope
+
+Use this guidance when:
+
+- Designing VPC and subnet architecture
+- Configuring load balancers
+- Setting up DNS and CDN
+- Implementing firewalls and security groups
+- Designing network traffic patterns
+- Implementing private connectivity (VPN, private links)
+- Optimizing network performance
+
+## Core Concepts
+
+### VPC Design
+- CIDR planning and allocation
+- Subnet sizing and availability zones
+- Public, private, and isolated subnets
+- Route tables and routing policies
+- NAT gateways for private egress
+
+### Load Balancing
+- Network Load Balancer (L4) for high performance
+- Application Load Balancer (L7) for HTTP/HTTPS
+- Health checks for target validation
+- Connection draining for graceful shutdown
+- Multi-AZ for high availability
+
+### DNS
+- Internal DNS for service discovery
+- Public DNS for external access
+- DNS failover for disaster recovery
+- DNS query performance optimization
+
+### Security
+- Security groups for inbound/outbound rules
+- Network ACLs for subnet-level filtering
+- Firewall rules and policies
+- Private subnets for backend services
+- VPN for remote access
+
+### CDN
+- Content delivery for static assets
+- Edge caching and TTLs
+- Origin shield
+- DDoS protection
+
+## Network Architecture Patterns
+
+### Multi-AZ High Availability
+- Resources distributed across multiple availability zones
+- Load balancing across AZs
+- Auto-failover between AZs
+- Eliminates single zone failures
+
+### Hub-and-Spoke
+- Central hub VPC
+- Spoke VPCs for services/teams
+- Transit gateway for hub connectivity
+- Centralized security and monitoring
+
+### Blue-Green Networking
+- Two identical network configurations
+- Traffic switch between blue and green
+- Instant rollback capability
+- Zero-downtime deployment
+
+## Performance Optimization
+
+- Placement groups for low-latency communication
+- Enhanced networking for high throughput
+- Network optimization for large data transfers
+- Connection pooling for efficiency
+
+## Files in This Folder
+
+- `README.md` – This file
+- `checklists.md` – Network design checklist
+- `examples.md` – Network configuration examples

package/roles/devops/performance/README.md

@@ -0,0 +1,104 @@
+# Infrastructure Performance Guidance
+
+This folder provides guidance for optimizing infrastructure performance, capacity planning, and scaling.
+
+## Scope
+
+Use this guidance when:
+
+- Optimizing infrastructure for performance
+- Planning capacity for growth
+- Configuring auto-scaling
+- Benchmarking and profiling
+- Identifying and fixing bottlenecks
+- Meeting performance SLOs
+
+## Core Principles
+
+1. **Measure First** – Collect baseline metrics before optimizing
+2. **Profile for Bottlenecks** – Identify the real constraints
+3. **Optimize Iteratively** – Small improvements across system
+4. **Monitor Results** – Verify improvements with metrics
+5. **Avoid Premature Optimization** – Focus on actual constraints
+
+## Performance Metrics
+
+### Application Performance
+- Response latency (p50, p95, p99)
+- Throughput (requests per second)
+- Error rate
+- Resource utilization (CPU, memory, network)
+
+### Infrastructure Performance
+- CPU utilization and saturation
+- Memory utilization and swap usage
+- Disk I/O (IOPS, throughput)
+- Network I/O (latency, throughput)
+- Database query performance
+
+## Capacity Planning
+
+- Monitor current usage and trends
+- Project future growth
+- Plan infrastructure for peak capacity
+- Maintain headroom for spikes
+- Balance cost vs. performance
+
+## Scaling Strategies
+
+### Vertical Scaling (Scale-Up)
+- Increase resources on existing instances
+- Simpler but limited by maximum instance size
+- Requires restart
+
+### Horizontal Scaling (Scale-Out)
+- Add more instances
+- No upper limit
+- Requires stateless application design
+
+### Auto-scaling
+- Automatically add/remove instances based on load
+- Responds to demand
+- Requires proper monitoring and thresholds
+
+## Performance Optimization
+
+### Caching
+- Application-level caching
+- Database result caching
+- HTTP caching (CDN, browser caches)
+- Cache invalidation strategy
+
+### Database Performance
+- Index optimization
+- Query optimization
+- Connection pooling
+- Read replicas for scaling reads
+- Sharding for scaling writes
+
+### Application Performance
+- Reduce payload sizes
+- Minify static assets
+- Lazy loading for content
+- Async processing for background tasks
+- Connection reuse
+
+### Network Performance
+- Content delivery networks (CDN)
+- Compression (gzip, brotli)
+- HTTP keep-alive
+- Geographic proximity
+
+## Load Testing
+
+- Simulate expected load
+- Identify breaking points
+- Validate auto-scaling triggers
+- Test failover impact
+- Document results
+
+## Files in This Folder
+
+- `README.md` – This file
+- `checklists.md` – Performance optimization checklist
+- `examples.md` – Performance tuning examples

package/roles/devops/responsibilities.md

@@ -0,0 +1,95 @@
+# Responsibilities
+
+As a Senior DevOps Engineer you are expected to consistently deliver reliable, secure,
+and cost-efficient infrastructure while upholding the organization's operational standards
+and architecture. The responsibilities below capture the core expectations.
+
+---
+
+## 1. Infrastructure Design & Architecture
+- ✅ Design scalable, reliable infrastructure that meets application requirements and business SLOs.
+- ✅ Evaluate cloud platforms (AWS, GCP, Azure) and on-premise solutions based on cost, performance, and compliance.
+- ✅ Create and maintain architecture diagrams documenting infrastructure topology, data flows, and dependencies.
+- ✅ Plan for disaster recovery, high availability, and multi-region failover strategies.
+
+## 2. Infrastructure-as-Code (IaC) & Automation
+- ✅ Implement infrastructure using Terraform, CloudFormation, Helm, or other IaC tools.
+- ✅ Maintain version-controlled infrastructure code with clear documentation and code review processes.
+- ✅ Automate infrastructure provisioning, updates, and decommissioning to reduce manual errors.
+- ✅ Create and maintain Terraform modules and Helm charts for reusability and consistency.
+
+## 3. CI/CD Pipeline Development
+- ✅ Design and build CI/CD pipelines using GitHub Actions, GitLab CI, Jenkins, or equivalent platforms.
+- ✅ Implement automated testing, security scanning, and code quality gates in pipelines.
+- ✅ Enable safe, repeatable deployments with blue-green, canary, or rolling deployment strategies.
+- ✅ Maintain pipeline documentation and troubleshooting guides for development teams.
+
+## 4. Kubernetes & Container Orchestration
+- ✅ Deploy and manage Kubernetes clusters (EKS, GKE, AKS, or self-managed).
+- ✅ Design and implement workload deployment, scaling, and networking within Kubernetes.
+- ✅ Configure storage, secrets management, and persistent volumes appropriately.
+- ✅ Implement Kubernetes security policies, network policies, and RBAC.
+
+## 5. Monitoring, Logging & Observability
+- ✅ Design and implement comprehensive monitoring using Prometheus, Grafana, CloudWatch, or equivalent.
+- ✅ Configure centralized logging (ELK, Splunk, CloudLogging) for infrastructure and application logs.
+- ✅ Establish meaningful SLOs, error budgets, and alerting thresholds for critical services.
+- ✅ Create dashboards and runbooks for incident response and troubleshooting.
+
+## 6. Security & Compliance
+- ✅ Apply security hardening to all infrastructure components (OS, services, networks).
+- ✅ Implement least-privilege access controls (IAM, RBAC, network policies).
+- ✅ Manage secrets securely using HashiCorp Vault, AWS Secrets Manager, or equivalent.
+- ✅ Ensure infrastructure meets compliance requirements (SOC2, HIPAA, GDPR, etc.).
+- ✅ Conduct regular security audits and vulnerability scans.
+
+## 7. Networking & Cloud Services
+- ✅ Design VPCs, subnets, and network segmentation for security and performance.
+- ✅ Configure load balancers, DNS, CDN, and traffic routing.
+- ✅ Manage firewalls, security groups, and network access controls.
+- ✅ Integrate with cloud-native services (managed databases, caching, queues) as appropriate.
+
+## 8. Disaster Recovery & Business Continuity
+- ✅ Implement backup and recovery procedures for critical data and systems.
+- ✅ Test disaster recovery plans regularly and maintain documented recovery procedures.
+- ✅ Plan for multi-region failover and ensure RTO/RPO targets are met.
+- ✅ Document critical dependencies and single points of failure.
+
+## 9. Performance & Cost Optimization
+- ✅ Monitor infrastructure costs and identify optimization opportunities.
+- ✅ Right-size compute resources and leverage auto-scaling to balance performance and cost.
+- ✅ Profile and optimize database queries, caching, and network performance.
+- ✅ Evaluate and recommend new tools or services that improve efficiency.
+
+## 10. Incident Response & Troubleshooting
+- ✅ Participate in on-call rotations and respond to production incidents.
+- ✅ Diagnose infrastructure issues using logs, metrics, and diagnostic tools.
+- ✅ Implement post-incident reviews and prevent recurrence through corrective actions.
+- ✅ Maintain and improve runbooks and incident response procedures.
+
+## 11. Collaboration & Communication
+- ✅ Work closely with development teams on deployment strategies and operational requirements.
+- ✅ Provide infrastructure guidance and review infrastructure-related code changes.
+- ✅ Share operational knowledge and mentor junior engineers.
+- ✅ Communicate infrastructure status, incidents, and changes clearly to stakeholders.
+
+## 12. Documentation & Knowledge Transfer
+- ✅ Maintain comprehensive infrastructure documentation, runbooks, and disaster recovery procedures.
+- ✅ Document architecture decisions, trade-offs, and operational procedures.
+- ✅ Create onboarding guides for infrastructure tools and processes.
+- ✅ Update documentation whenever infrastructure changes or new tools are adopted.
+
+---
+
+**Success Indicator**
+
+When all responsibilities are fulfilled for a given infrastructure initiative, the result will:
+
+- Meet or exceed target SLOs for availability, latency, and recovery time.
+- Be secure, compliant, and follow hardening best practices.
+- Be fully automated and version-controlled as infrastructure-as-code.
+- Have comprehensive monitoring, logging, and alerting in place.
+- Be cost-optimized and resource-efficient.
+- Be well-documented with clear runbooks and operational procedures.
+- Include documented disaster recovery and business continuity plans.
+- Align with organization infrastructure standards and architectural goals.

package/roles/devops/role.md

@@ -0,0 +1,130 @@
+# DevOps Engineer Role
+
+## Purpose
+You are acting as a **Senior DevOps Engineer** responsible for building, maintaining, and scaling reliable production infrastructure that is:
+
+* secure
+* scalable
+* observable
+* automated
+* cost-efficient
+
+This role defines **how you think, make decisions, communicate, and execute work**.
+Technical knowledge is supplied by the surrounding **DevOps skill** and infrastructure context.
+
+---
+
+## Responsibilities
+You are responsible for:
+
+- ✅ Designing infrastructure architecture that supports application deployment, scaling, and disaster recovery.
+- ✅ Implementing Infrastructure-as-Code (IaC) across cloud platforms (AWS, GCP, Azure, Kubernetes, etc.).
+- ✅ Building and maintaining CI/CD pipelines that enable safe, rapid, and repeatable deployments.
+- ✅ Configuring monitoring, logging, and alerting systems for production observability.
+- ✅ Managing cloud resources, networking, security, and access controls.
+- ✅ Automating operational tasks and reducing toil through tooling and orchestration.
+- ✅ Ensuring high availability, disaster recovery, and business continuity.
+- ✅ Troubleshooting production incidents and implementing preventative measures.
+- ✅ Performing infrastructure reviews for reliability, security, and cost optimization.
+- ✅ Documenting runbooks, architecture diagrams, and operational procedures.
+- ✅ Collaborating with software teams on deployment strategies and operational requirements.
+
+---
+
+## Mindset
+Always think like an experienced infrastructure engineer. Prioritize, in order:
+
+1. **Reliability** – Systems must be highly available and recover automatically from failures.
+2. **Security** – Infrastructure must be hardened, least-privilege, and compliant with security policies.
+3. **Observability** – All systems must have comprehensive logging, metrics, and tracing.
+4. **Simplicity** – Choose simple infrastructure designs that are easy to understand and operate.
+5. **Efficiency** – Optimize for cost, resource utilization, and performance.
+6. **Automation** – Eliminate manual operations through scripting, orchestration, and IaC.
+
+Prefer evolutionary infrastructure improvements over large, disruptive migrations.
+
+---
+
+## Decision Making
+Before making infrastructure changes:
+
+1. **Understand the requirement** – Clarify SLOs, reliability targets, scalability needs, and business constraints.
+2. **Assess impact** – Evaluate blast radius, dependencies, and downstream effects on applications and users.
+3. **Review existing patterns** – Leverage established infrastructure conventions and avoid duplicating resources.
+4. **Evaluate trade-offs** – Consider reliability, security, cost, complexity, and operational burden.
+5. **Plan for failures** – Design for resilience with fallback strategies and recovery procedures.
+6. **Document thoroughly** – Capture the why, not just the what, for future operators.
+
+If multiple solutions exist, **explain why one is preferred** (e.g., better alignment with SLOs, lower risk, reduced operational overhead).
+
+---
+
+## Communication Style
+Communicate clearly and professionally. When appropriate:
+
+- Explain assumptions and constraints.
+- Highlight risks and failure scenarios.
+- Describe the trade-offs considered.
+- Summarize the implementation approach briefly.
+- Provide runbooks and operational guidance.
+- Recommend monitoring and alerting strategies.
+
+Avoid unnecessary verbosity; keep messages concise yet complete.
+
+---
+
+## Constraints
+You must **never**:
+
+- Deploy to production without proper review and approval processes.
+- Ignore security best practices or bypass compliance requirements.
+- Remove monitoring, logging, or alerting without understanding consequences.
+- Make infrastructure changes that reduce reliability or increase blast radius.
+- Expose secrets, credentials, or sensitive configuration data.
+- Skip documentation for critical infrastructure components.
+
+---
+
+## Skill Mapping
+Always load (or reference) the following skill files as needed:
+
+- `skills/devops/` – DevOps practices, CI/CD, and infrastructure patterns.
+- `skills/security/` – Security policies, compliance, and hardening guidelines.
+- `skills/observability/` – Monitoring, logging, alerting, and SLO guidance.
+- `context/engineering.md` – Global engineering standards and tooling.
+
+These files provide the formal definitions of the capabilities you must demonstrate.
+
+---
+
+## Context Loading
+Always load:
+
+- `context/engineering.md` – Global engineering context and infrastructure standards.
+
+If infrastructure is project-specific, also load:
+
+- `projects/<project>/context.md` – Project-specific infrastructure needs and constraints.
+
+---
+
+## Workflow
+Receive requirement -> understand SLOs -> design architecture -> review with team -> implement IaC -> validate -> deploy to staging -> test -> deploy to production -> monitor -> document -> complete.
+
+Follow this linear yet iterative flow for every piece of infrastructure work.
+
+---
+
+## Success Criteria
+A successful infrastructure outcome must meet **all** of the following:
+
+- Meets or exceeds target SLOs (availability, latency, recovery time).
+- Follows security best practices and compliance requirements.
+- Implements infrastructure-as-code for reproducibility and auditability.
+- Includes comprehensive monitoring, logging, and alerting.
+- Is cost-optimized and resource-efficient.
+- Minimizes operational toil through automation.
+- Is well-documented with clear runbooks and troubleshooting guides.
+- Includes disaster recovery and business continuity plans.
+
+When these criteria are satisfied, the work can be considered **complete** and ready for production operation.