ai-playbook 1.0.0

package/skills/devops/skill.md

@@ -0,0 +1,210 @@
+# DevOps Skill
+
+## Purpose
+
+The DevOps skill enables organizations to automate infrastructure, deployment pipelines, and operational processes while maintaining reliability, security, and observability. This skill focuses on bridging development and operations through automation, continuous integration/continuous deployment (CI/CD), infrastructure as code, and operational excellence. It encompasses building and maintaining systems that enable rapid, safe deployments while keeping systems stable and secure.
+
+---
+
+## Table of Contents
+
+1. [Core Competencies](#core-competencies)
+2. [Specific Domains & Tools](#specific-domains--tools)
+3. [Best Practices](#best-practices)
+4. [Deliverables](#deliverables)
+5. [Success Criteria](#success-criteria)
+
+---
+
+## Core Competencies
+
+### 1. **Continuous Integration (CI)**
+Design and implement CI pipelines that automatically test code changes. Establish build automation that runs on every commit. Implement test coverage requirements and quality gates. Create fast feedback loops that inform developers of issues quickly.
+
+**Application**: GitHub Actions, GitLab CI, Jenkins, CircleCI for automated testing and building.
+
+### 2. **Continuous Deployment & Delivery (CD)**
+Design deployment pipelines that safely move code from development to production. Implement automated testing across environments. Plan rollback strategies and canary deployments. Enable rapid, frequent deployments with minimal risk.
+
+**Application**: Automated deployment to staging/production, blue-green deployments, canary releases.
+
+### 3. **Infrastructure as Code (IaC)**
+Define infrastructure using code and version control. Create reproducible infrastructure provisioning. Plan for infrastructure changes and rollbacks. Enable infrastructure testing and validation.
+
+**Application**: Terraform, CloudFormation, Ansible for infrastructure definition and provisioning.
+
+### 4. **Container Orchestration**
+Design and manage containerized applications at scale. Implement container clustering, scheduling, and resource management. Plan for high availability and self-healing. Design for stateless application deployment.
+
+**Application**: Kubernetes, Docker Swarm, container management platforms.
+
+### 5. **Service Mesh & Load Balancing**
+Design service discovery, load balancing, and inter-service communication. Implement traffic management, circuit breaking, and retries. Design for resilience and observability across service boundaries.
+
+**Application**: Istio, Envoy, service mesh implementations for distributed systems.
+
+### 6. **Secrets Management**
+Design systems for securely storing and managing secrets. Implement rotation policies and access controls. Plan for secrets injection into applications. Enable secure secret sharing across teams.
+
+**Application**: HashiCorp Vault, AWS Secrets Manager, Kubernetes secrets for secret management.
+
+### 7. **Monitoring & Observability**
+Design monitoring systems that provide visibility into application and infrastructure health. Implement metrics collection, logging, and distributed tracing. Create dashboards and alerting. Enable rapid diagnosis of failures.
+
+**Application**: Prometheus, Grafana, ELK Stack, Datadog for monitoring and observability.
+
+### 8. **Logging & Log Analysis**
+Design logging systems that capture relevant information without overwhelming storage. Implement structured logging and centralized log aggregation. Create search and analysis capabilities. Enable debugging and compliance auditing.
+
+**Application**: ELK Stack, Splunk, CloudWatch, Loki for log management.
+
+### 9. **Alerting & Incident Response**
+Design alerting systems that notify appropriate teams of issues. Implement escalation policies and on-call rotations. Create runbooks for common issues. Enable rapid incident response and mitigation.
+
+**Application**: PagerDuty, Alertmanager, incident management systems.
+
+### 10. **Configuration Management**
+Design configuration systems that manage application and infrastructure configuration safely. Implement versioning and rollback capabilities. Plan for environment-specific configurations. Enable rapid configuration changes without redeployment.
+
+**Application**: Ansible, Chef, Puppet for configuration management.
+
+### 11. **Database Administration & Migrations**
+Design database deployments, scaling, and maintenance. Implement backup and disaster recovery strategies. Plan zero-downtime migrations. Monitor database performance and health.
+
+**Application**: Database replication, sharding, backup automation, migration tools.
+
+### 12. **Disaster Recovery & Business Continuity**
+Design recovery strategies for various failure scenarios. Plan backup and restoration processes. Implement geo-redundancy and failover mechanisms. Test disaster recovery regularly.
+
+**Application**: Backup automation, geo-replication, failover systems, DR testing.
+
+### 13. **Security & Compliance Automation**
+Design automated security scanning and compliance checking. Implement vulnerability scanning in CI/CD pipelines. Plan for security policy enforcement. Enable compliance reporting and auditing.
+
+**Application**: SAST/DAST scanning, vulnerability management, compliance automation.
+
+### 14. **Performance Optimization & Scaling**
+Design auto-scaling policies based on metrics. Optimize infrastructure costs. Plan for load testing and capacity planning. Enable efficient resource utilization.
+
+**Application**: Auto-scaling groups, performance testing, cost optimization tools.
+
+### 15. **Network Architecture & Security**
+Design network topology and security controls. Implement firewalls, VPNs, and network segmentation. Plan for DDoS protection and load balancing. Enable secure inter-service communication.
+
+**Application**: VPC design, security groups, network policies, service mesh.
+
+### 16. **Cloud Platform Management**
+Design and manage cloud infrastructure deployments. Implement multi-cloud or hybrid cloud strategies. Plan for vendor lock-in mitigation. Optimize cloud costs.
+
+**Application**: AWS, Azure, GCP, cloud management platforms.
+
+### 17. **Disaster Recovery Testing**
+Design and execute DR tests regularly. Validate backup restoration processes. Measure recovery time objectives (RTO) and recovery point objectives (RPO). Document learnings and improvements.
+
+**Application**: DR drills, chaos engineering, incident simulations.
+
+### 18. **GitOps & Declarative Deployment**
+Design systems where desired state is defined in Git. Implement automated reconciliation of actual vs. declared state. Plan for audit trails and rollback. Enable self-healing systems.
+
+**Application**: ArgoCD, Flux, GitOps workflows for infrastructure and application deployment.
+
+---
+
+## Specific Domains & Tools
+
+### CI/CD Platforms
+- **GitHub Actions**: Workflows integrated with GitHub repositories
+- **GitLab CI**: CI/CD native to GitLab
+- **Jenkins**: Self-hosted CI/CD orchestration
+- **CircleCI**: Cloud-hosted CI/CD platform
+- **Travis CI**: CI/CD for GitHub repositories
+
+### Infrastructure & Cloud
+- **AWS**: EC2, RDS, S3, Lambda, CloudFormation
+- **Google Cloud**: Compute Engine, Cloud SQL, Cloud Storage
+- **Azure**: Virtual Machines, SQL Database, App Service
+- **Terraform**: Infrastructure as Code for multiple clouds
+- **Ansible**: Configuration management and automation
+
+### Container & Orchestration
+- **Docker**: Container runtime and image creation
+- **Kubernetes**: Container orchestration and management
+- **Docker Compose**: Multi-container application definition
+- **Docker Registry**: Image storage and distribution
+- **Container Network Interface (CNI)**: Networking for containers
+
+### Monitoring & Observability
+- **Prometheus**: Metrics collection and alerting
+- **Grafana**: Visualization and dashboarding
+- **ELK Stack**: Elasticsearch, Logstash, Kibana for logging
+- **Datadog**: APM and infrastructure monitoring
+- **New Relic**: Application performance monitoring
+
+### Database & Backup
+- **PostgreSQL/MySQL**: Relational databases with replication
+- **MongoDB**: NoSQL database with backup strategies
+- **Redis**: In-memory data store with persistence
+- **Backup Tools**: Velero, pg_dump, mysqldump
+
+### Security & Secrets
+- **HashiCorp Vault**: Secrets management
+- **AWS Secrets Manager**: Cloud secrets management
+- **Let's Encrypt**: SSL/TLS certificate automation
+- **Falco**: Container runtime security
+- **Sonarqube**: Code quality and security scanning
+
+---
+
+## Best Practices
+
+1. **Automation First**: Automate repetitive tasks; manual processes introduce errors and delays.
+
+2. **Infrastructure as Code**: Define all infrastructure in code; enable version control and reproducibility.
+
+3. **Test Thoroughly**: Test code, infrastructure, and deployments automatically; catch issues early.
+
+4. **Fail Fast**: Detect issues in CI/CD pipelines quickly; provide rapid feedback to developers.
+
+5. **Security in Pipeline**: Scan for vulnerabilities and compliance issues in CI/CD; shift left on security.
+
+6. **Observability by Default**: Design applications and infrastructure with observability built-in.
+
+7. **Safe Deployments**: Use canary, blue-green, or rolling deployments; enable quick rollbacks.
+
+8. **Monitor Everything**: Monitor applications, infrastructure, and business metrics; set up comprehensive alerting.
+
+9. **Document Runbooks**: Create clear procedures for common operational tasks and incidents.
+
+10. **Continuous Improvement**: Collect metrics on deployment frequency, lead time, MTTR; measure and improve.
+
+---
+
+## Deliverables
+
+- **CI/CD Pipeline Configuration**: GitHub Actions, GitLab CI, Jenkins pipeline definitions
+- **Infrastructure as Code**: Terraform modules, CloudFormation templates, Ansible playbooks
+- **Container Images**: Dockerfiles, image build pipelines, image registry setup
+- **Kubernetes Manifests**: Deployment, service, configmap, secret definitions
+- **Monitoring & Observability**: Prometheus configs, Grafana dashboards, alert rules, logging setup
+- **Security Configuration**: Network policies, RBAC definitions, secrets management setup
+- **Runbooks**: Procedures for common operational tasks and incident response
+- **Disaster Recovery Plan**: Backup strategies, RTO/RPO definitions, DR test results
+- **Documentation**: Infrastructure documentation, deployment guides, troubleshooting guides
+- **Cost Analysis**: Cloud cost optimization reports, resource utilization analysis
+- **Scaling Policies**: Auto-scaling configurations, load testing results, capacity plans
+- **Security Scanning**: SAST/DAST configurations, vulnerability scan results, compliance reports
+
+---
+
+## Success Criteria
+
+1. **Deployment Frequency**: Deployments occur multiple times per day without manual intervention
+2. **Lead Time**: Changes move from commit to production in minutes to hours
+3. **Mean Time to Recovery**: Systems recover from failures automatically within minutes
+4. **Change Failure Rate**: <15% of deployments cause incidents or require rollback
+5. **Security**: Zero unpatched critical vulnerabilities; compliance maintained automatically
+6. **Reliability**: 99.9%+ availability with clear SLOs and monitoring
+7. **Scalability**: System automatically scales to handle load spikes
+8. **Cost Efficiency**: Cloud costs optimized with appropriate resource allocation
+9. **Visibility**: All deployments, infrastructure, and incidents visible and auditable
+10. **Automation**: >95% of operational tasks automated without manual intervention

package/skills/documentation/README.md

@@ -0,0 +1,182 @@
+# Documentation Skill
+
+## Overview
+
+The Documentation skill enables the creation and maintenance of clear, comprehensive technical documentation that enables users, developers, and stakeholders to understand, use, and maintain software systems effectively. This skill encompasses API documentation, user guides, architecture documentation, knowledge bases, and governance processes that ensure documentation evolves alongside systems. Quality documentation reduces support burden, accelerates onboarding, enables self-service problem-solving, and preserves institutional knowledge.
+
+---
+
+## Goals
+
+- **Enable Self-Service**: Create documentation that helps users accomplish tasks without support
+- **Accelerate Onboarding**: Enable new team members to become productive quickly
+- **Preserve Knowledge**: Document decisions, architecture, and operational procedures
+- **Reduce Support Burden**: Create FAQ and troubleshooting guides that reduce support requests
+- **Ensure Clarity**: Write clear, well-structured documentation that users understand
+- **Support Discovery**: Make documentation easy to find through search and organization
+- **Maintain Accuracy**: Establish processes to keep documentation synchronized with code
+- **Enable Collaboration**: Create environments where documentation is easy to contribute to and maintain
+
+---
+
+## Capabilities
+
+### API Documentation
+- **Endpoint Documentation**: Complete documentation of all API endpoints with parameters and examples
+- **OpenAPI/Swagger**: Creating and maintaining machine-readable API specifications
+- **Code Examples**: Writing working examples in multiple programming languages
+- **Error Documentation**: Explaining error codes and recovery strategies
+- **Authentication**: Documenting authentication and authorization requirements
+
+### User Documentation
+- **Getting Started Guides**: Quick start documentation for new users
+- **Feature Documentation**: Step-by-step guides for using features
+- **Tutorials**: Complete walkthroughs of common workflows
+- **Video Tutorials**: Recorded walkthroughs of complex features
+- **FAQ & Troubleshooting**: Addressing common questions and problems
+
+### Technical Documentation
+- **Architecture Documentation**: System design, components, and relationships
+- **Design Decisions**: Architecture Decision Records explaining decisions
+- **Configuration Guides**: Documenting all configuration options and effects
+- **Deployment Procedures**: Step-by-step deployment guides
+- **Runbooks**: Operational procedures and incident response
+
+### Knowledge Management
+- **Knowledge Bases**: Building searchable, organized documentation sites
+- **Content Organization**: Creating hierarchical structures for easy navigation
+- **Version Control**: Managing documentation versions with code releases
+- **Search & Discovery**: Implementing search and recommendation systems
+- **Maintenance Processes**: Establishing workflows for keeping documentation current
+
+### Supporting Capabilities
+- **Diagrams & Visuals**: Creating architecture diagrams and flowcharts
+- **Glossaries**: Defining domain-specific terms and concepts
+- **Accessibility**: Creating documentation accessible to all users
+- **Multi-language Support**: Documenting in multiple languages
+- **Analytics**: Tracking documentation usage and effectiveness
+
+---
+
+## When to Use
+
+**Use this skill when you need to:**
+- Document an API for third-party developers
+- Create user guides for product features
+- Onboard new team members or engineers
+- Document system architecture and design decisions
+- Build a searchable knowledge base
+- Create deployment and operational runbooks
+- Write FAQ and troubleshooting guides
+- Maintain release notes and changelogs
+- Document configuration options and migrations
+- Create video tutorials for complex features
+
+**Typical scenarios:**
+- Pre-launch documentation for new products
+- Post-feature documentation as features are built
+- Knowledge base expansion based on support tickets
+- Onboarding documentation for teams
+- Architecture documentation for legacy systems
+- API documentation for public or internal APIs
+- Migration and upgrade guides
+
+---
+
+## Expected Workflow
+
+```
+Define Audience & Goals
+        ↓
+Plan Content Structure
+        ↓
+Research & Gather Information
+        ↓
+Write Documentation
+        ↓
+Create Examples & Diagrams
+        ↓
+Review & Edit
+        ↓
+Test Code Examples
+        ↓
+Publish & Deploy
+        ↓
+Gather Feedback
+        ↓
+Maintain & Update
+```
+
+---
+
+## Inputs
+
+- **Product/System Knowledge**: Understanding of features, architecture, configuration
+- **Audience**: Target users (developers, end-users, operators) and their expertise levels
+- **Goals**: What documentation should enable users to accomplish
+- **Existing Documentation**: Any existing documentation to build upon or refactor
+- **Examples**: Real-world use cases and scenarios to document
+- **Change History**: Recent changes, fixes, and deprecations to document
+- **User Feedback**: Support tickets and questions indicating documentation gaps
+
+---
+
+## Outputs
+
+- **API Documentation**: Complete endpoint documentation with examples
+- **User Guides**: Step-by-step feature guides and tutorials
+- **Architecture Documentation**: System design and component documentation
+- **Getting Started Guide**: Quick start documentation for new users
+- **Troubleshooting Guides**: Common issues and solutions
+- **FAQ**: Frequently asked questions with answers
+- **Release Notes**: Change documentation for each release
+- **Deployment Guides**: Procedures for deploying and configuring systems
+- **Runbooks**: Operational procedures and incident response
+- **Architecture Decision Records**: Documented decisions with rationale
+- **Configuration Documentation**: Reference for all configuration options
+- **Glossary**: Domain-specific term definitions
+- **Video Tutorials**: Recorded walkthroughs
+- **Style Guide**: Writing conventions and standards
+- **Documentation Site**: Searchable, organized documentation platform
+
+---
+
+## Related Skills
+
+- **Design Architecture**: Creating documentation interfaces and user experiences
+- **Architecture**: Understanding systems to document them effectively
+- **DevOps**: Documenting deployment and operational procedures
+- **Software Development**: Understanding code to document APIs and examples
+- **Performance**: Documenting performance tuning and optimization
+
+---
+
+## Best Practices
+
+1. **Write for Your Audience**: Understand your readers' expertise and tailor content accordingly
+2. **Keep Docs Current**: Update documentation within 2 weeks of code changes; make docs part of definition of done
+3. **Provide Working Examples**: Give complete, executable examples with expected outputs
+4. **Use Consistent Terminology**: Define terms and use them consistently throughout
+5. **Structure for Scannability**: Use headings, short paragraphs, and formatting for quick scanning
+6. **One Authoritative Version**: Avoid duplication; link to authoritative sources instead
+7. **Version with Code**: Keep documentation versions synchronized with software releases
+8. **Seek Feedback**: Ask users what documentation helped or didn't; iterate based on feedback
+9. **Test Examples**: Verify code examples work; automate example testing when possible
+10. **Make It Discoverable**: Use clear titles, keywords, and implement site search
+
+---
+
+## Success Criteria
+
+1. **Accessibility**: Users find documentation they need within 2-3 clicks
+2. **Clarity**: New users understand features without requiring support
+3. **Completeness**: Documentation answers >95% of user questions
+4. **Accuracy**: Documentation matches current system behavior
+5. **Freshness**: Documentation updated within 2 weeks of code changes
+6. **Searchability**: Users find relevant documentation through search
+7. **Self-Service**: 80%+ of user issues resolved through documentation
+8. **Onboarding**: New team members productive within expected timeframe
+9. **Maintainability**: Documentation easy to update and version control
+10. **Impact**: Reduced support tickets, faster issue resolution, less onboarding time required
+
+---