ai-playbook 1.0.0

package/agents/debugger/AGENT.md

@@ -0,0 +1,42 @@
+---
+name: debugger
+description: Debugging specialist for diagnosing issues, analyzing logs, and tracing execution paths
+tools: [Read, Grep, Glob, Bash, Edit]
+---
+
+# Debugger Agent
+
+Specialized agent for diagnosing and fixing issues.
+
+## Responsibilities
+
+- Reproduce and isolate issues
+- Analyze error logs and stack traces
+- Trace execution paths
+- Identify root causes
+- Propose fixes for bugs
+- Verify bug fixes
+
+## When to Use
+
+Use this agent when you need to:
+- Debug production issues
+- Investigate unexpected behavior
+- Analyze error logs
+- Trace code execution
+- Find root causes of failures
+- Verify bug fixes work correctly
+
+## What It Produces
+
+- Root cause analysis
+- Reproduction steps
+- Bug fix proposals
+- Verification that fixes work
+- Documentation of issue and solution
+
+## Tools Available
+
+- Code analysis: Read, Grep, Glob
+- Log and system inspection: Bash
+- Fix implementation: Edit

package/agents/debugger/README.md

@@ -0,0 +1,6 @@
+# Debugger Agent
+
+Use this folder for the debugger agent definition.
+
+Load `AGENT.md` for diagnostic workflow, evidence gathering, and verification
+expectations.

package/agents/devops/AGENT.md

@@ -0,0 +1,43 @@
+---
+name: devops
+description: DevOps specialist for infrastructure, deployment pipelines, and operational concerns
+tools: [Read, Grep, Glob, Bash, Write, Edit]
+---
+
+# DevOps Agent
+
+Specialized agent for infrastructure and operations.
+
+## Responsibilities
+
+- Design deployment pipelines
+- Manage infrastructure configuration
+- Set up CI/CD workflows
+- Handle container and orchestration concerns
+- Configure monitoring and alerting
+- Manage environment setup
+
+## When to Use
+
+Use this agent when you need to:
+- Design deployment strategies
+- Set up CI/CD pipelines
+- Configure Kubernetes or container infrastructure
+- Create Terraform/IaC configurations
+- Set up monitoring and logging
+- Troubleshoot deployment issues
+- Plan infrastructure scaling
+
+## What It Produces
+
+- Pipeline configurations
+- Infrastructure as code
+- Deployment strategies
+- Monitoring configurations
+- Documentation of operational procedures
+
+## Tools Available
+
+- Code and config analysis: Read, Grep, Glob
+- System administration: Bash
+- Configuration creation: Write, Edit

package/agents/devops/README.md

@@ -0,0 +1,5 @@
+# DevOps Agent
+
+Use this folder for the DevOps agent definition.
+
+Load `AGENT.md` for infrastructure, CI/CD, deployment, and operations guidance.

package/agents/documentation/AGENT.md

@@ -0,0 +1,45 @@
+---
+name: documentation
+description: Documentation specialist for writing and maintaining system and API documentation
+tools: [Read, Grep, Glob, Bash, Write, Edit, WebFetch]
+---
+
+# Documentation Agent
+
+Specialized agent for creating and maintaining documentation.
+
+## Responsibilities
+
+- Write system documentation
+- Create API documentation
+- Write user guides and tutorials
+- Maintain README files
+- Document architecture decisions
+- Create onboarding materials
+
+## When to Use
+
+Use this agent when you need to:
+- Write system documentation
+- Document APIs and interfaces
+- Create user guides
+- Write installation guides
+- Document architecture decisions
+- Update README files
+- Create contribution guidelines
+
+## What It Produces
+
+- API documentation
+- System architecture documentation
+- User guides and tutorials
+- README and overview documents
+- Installation and setup guides
+- Architecture decision records (ADRs)
+
+## Tools Available
+
+- Code analysis: Read, Grep, Glob
+- System inspection: Bash
+- Documentation creation: Write, Edit
+- Reference materials: WebFetch

package/agents/documentation/README.md

@@ -0,0 +1,5 @@
+# Documentation Agent
+
+Use this folder for the documentation agent definition.
+
+Load `AGENT.md` for documentation workflow, style, and verification guidance.

package/agents/examples.md

@@ -0,0 +1,550 @@
+# Agent Examples
+
+Practical examples showing how to use each specialized agent.
+
+---
+
+## Architect Agent Examples
+
+### Example 1: Design a Microservices Architecture
+
+**Request:**
+```
+Use architect to design a microservices architecture for an e-commerce platform 
+with product catalog, order processing, and payment handling, supporting 10M+ users
+```
+
+**Expected Output:**
+- Service boundary definitions
+- Data flow between services
+- Technology recommendations
+- Scalability approach
+- API contracts
+- Failure handling strategies
+
+### Example 2: Plan a Database Migration
+
+**Request:**
+```
+Use architect to design migration strategy from monolithic database to sharded architecture
+considering existing 50GB dataset and zero-downtime requirement
+```
+
+**Expected Output:**
+- Sharding strategy
+- Migration phases
+- Rollback plan
+- Performance impact analysis
+- Testing approach
+
+---
+
+## Coder Agent Examples
+
+### Example 1: Implement a Feature
+
+**Request:**
+```
+Use coder to implement an authentication middleware for a Node.js Express app
+with JWT token validation and role-based access control
+```
+
+**Expected Output:**
+- Production-ready middleware code
+- Error handling
+- Logging
+- Integration tests
+- Usage documentation
+
+### Example 2: Add Database Queries
+
+**Request:**
+```
+Use coder to implement pagination and filtering for product search in our Postgres database
+following existing query patterns
+```
+
+**Expected Output:**
+- Query implementation
+- Index recommendations
+- Error handling
+- Performance considerations
+
+---
+
+## Debugger Agent Examples
+
+### Example 1: Diagnose a Performance Issue
+
+**Request:**
+```
+Use debugger to diagnose why our API response times spiked from 100ms to 2s after 
+the database upgrade yesterday
+```
+
+**Expected Output:**
+- Root cause analysis
+- Performance metrics
+- Query analysis
+- Optimization recommendations
+- Verification steps
+
+### Example 2: Investigate a Crash
+
+**Request:**
+```
+Use debugger to find the cause of intermittent OutOfMemory crashes in our Python worker
+service that processes batch jobs
+```
+
+**Expected Output:**
+- Reproduction steps
+- Memory profiling results
+- Root cause identification
+- Fix recommendations
+- Monitoring improvements
+
+---
+
+## Tester Agent Examples
+
+### Example 1: Design Test Strategy
+
+**Request:**
+```
+Use tester to create comprehensive test strategy for payment processing service
+covering happy path, failures, edge cases, and concurrency
+```
+
+**Expected Output:**
+- Test plan breakdown
+- Unit test specs
+- Integration test scenarios
+- Load test approach
+- Error case coverage
+
+### Example 2: Improve Test Coverage
+
+**Request:**
+```
+Use tester to identify gaps in test coverage for our authentication module
+and create tests for missing scenarios
+```
+
+**Expected Output:**
+- Coverage analysis
+- Missing scenario identification
+- Test code implementation
+- Integration with existing tests
+
+---
+
+## Refactorer Agent Examples
+
+### Example 1: Consolidate Duplicate Code
+
+**Request:**
+```
+Use refactorer to consolidate duplicate validation logic across 5 API endpoints
+and extract to a reusable validation library
+```
+
+**Expected Output:**
+- Extracted validation library
+- Updated endpoints
+- Test preservation
+- Documentation
+- Migration plan
+
+### Example 2: Modernize Legacy Code
+
+**Request:**
+```
+Use refactorer to modernize our 3-year-old Python codebase from Python 3.7 patterns
+to Python 3.11 with async/await and type hints
+```
+
+**Expected Output:**
+- Modernized code
+- Type annotations
+- Async conversions
+- Test verification
+- Migration guide
+
+---
+
+## Reviewer Agent Examples
+
+### Example 1: Review a Pull Request
+
+**Request:**
+```
+Use reviewer to review this pull request adding a caching layer to our API
+for correctness, security, performance, and maintainability
+```
+
+**Expected Output:**
+- Bug identification
+- Security concerns
+- Performance issues
+- Code quality feedback
+- Maintainability suggestions
+
+### Example 2: Audit Code Quality
+
+**Request:**
+```
+Use reviewer to audit the authentication module for consistency with project standards
+and potential issues before we use it in sensitive flows
+```
+
+**Expected Output:**
+- Standards compliance check
+- Security assessment
+- Performance review
+- Architecture alignment
+- Risk assessment
+
+---
+
+## Security Agent Examples
+
+### Example 1: Perform Security Review
+
+**Request:**
+```
+Use security to perform security review of our API authentication and authorization
+looking for OWASP vulnerabilities
+```
+
+**Expected Output:**
+- Vulnerability assessment
+- Threat analysis
+- Compliance gaps
+- Remediation steps
+- Security recommendations
+
+### Example 2: Threat Model a Feature
+
+**Request:**
+```
+Use security to threat model our new user data export feature looking for
+data exposure risks and unauthorized access vectors
+```
+
+**Expected Output:**
+- Threat identification
+- Risk assessment
+- Attack scenarios
+- Mitigation strategies
+- Security architecture recommendations
+
+---
+
+## Performance Agent Examples
+
+### Example 1: Optimize Database Queries
+
+**Request:**
+```
+Use performance to analyze and optimize slow product search queries that are
+causing p99 latencies of 3+ seconds
+```
+
+**Expected Output:**
+- Query analysis
+- Index recommendations
+- Optimization strategies
+- Benchmark results
+- Monitoring approach
+
+### Example 2: Improve Scalability
+
+**Request:**
+```
+Use performance to identify bottlenecks in our real-time notification system
+before scaling to 1M concurrent users
+```
+
+**Expected Output:**
+- Bottleneck analysis
+- Capacity planning
+- Architecture improvements
+- Scaling strategy
+- Load test results
+
+---
+
+## Planner Agent Examples
+
+### Example 1: Break Down a Feature
+
+**Request:**
+```
+Use planner to break down implementing OAuth2 authentication into tasks,
+estimate effort, and create a timeline for a team of 3
+```
+
+**Expected Output:**
+- Task breakdown
+- Effort estimates
+- Dependency map
+- Timeline
+- Risk assessment
+- Testing plan
+
+### Example 2: Plan a Migration
+
+**Request:**
+```
+Use planner to plan migration from our legacy monolith to microservices,
+breaking into phases that can be done incrementally over 6 months
+```
+
+**Expected Output:**
+- Phase breakdown
+- Tasks per phase
+- Resource requirements
+- Risk mitigation
+- Success criteria per phase
+
+---
+
+## Product Owner Agent Examples
+
+### Example 1: Create User Stories
+
+**Request:**
+```
+Use product-owner to create user stories for a new notification preferences feature
+including acceptance criteria and success metrics
+```
+
+**Expected Output:**
+- User stories
+- Acceptance criteria
+- Success metrics
+- Edge cases
+- Acceptance tests
+
+### Example 2: Define Feature Requirements
+
+**Request:**
+```
+Use product-owner to define detailed requirements for mobile app offline mode
+including scope, constraints, and success criteria
+```
+
+**Expected Output:**
+- Feature specification
+- Requirements breakdown
+- Constraints and assumptions
+- Success metrics
+- Stakeholder considerations
+
+---
+
+## Release Manager Agent Examples
+
+### Example 1: Plan a Release
+
+**Request:**
+```
+Use release-manager to plan v2.0 release including version bump, changelog,
+deployment strategy, and rollback plan
+```
+
+**Expected Output:**
+- Release timeline
+- Version changes
+- Changelog
+- Deployment steps
+- Rollback procedures
+- Release notes
+
+### Example 2: Create Deployment Checklist
+
+**Request:**
+```
+Use release-manager to create pre-deployment and post-deployment checklists
+for production release ensuring we catch issues early
+```
+
+**Expected Output:**
+- Pre-deployment checklist
+- Deployment steps
+- Verification steps
+- Rollback criteria
+- Post-deployment monitoring
+
+---
+
+## DevOps Agent Examples
+
+### Example 1: Design Deployment Pipeline
+
+**Request:**
+```
+Use devops to design CI/CD pipeline for our Node.js microservices using GitHub Actions
+and Kubernetes, with automated testing and gradual rollout
+```
+
+**Expected Output:**
+- Pipeline configuration
+- Testing stages
+- Deployment strategy
+- Monitoring integration
+- Cost optimization
+
+### Example 2: Set Up Infrastructure
+
+**Request:**
+```
+Use devops to create Terraform code for our infrastructure: load balancer,
+Kubernetes cluster, RDS database, and monitoring using Prometheus
+```
+
+**Expected Output:**
+- Terraform modules
+- VPC and networking
+- Security groups
+- Monitoring setup
+- Documentation
+
+---
+
+## Support Agent Examples
+
+### Example 1: Create Troubleshooting Guide
+
+**Request:**
+```
+Use support to create troubleshooting guide for common API errors our customers
+experience, with diagnosis steps and solutions
+```
+
+**Expected Output:**
+- Error documentation
+- Diagnosis steps
+- Common causes
+- Solution steps
+- Escalation procedures
+
+### Example 2: Diagnose Customer Issue
+
+**Request:**
+```
+Use support to diagnose why customer reports payments failing intermittently
+with 503 errors from our payment processor
+```
+
+**Expected Output:**
+- Diagnosis steps
+- Root cause analysis
+- Workaround (if needed)
+- Resolution steps
+- Prevention
+
+---
+
+## Researcher Agent Examples
+
+### Example 1: Explore a Codebase
+
+**Request:**
+```
+Use researcher to explore the authentication system codebase to understand
+current implementation, patterns, and dependencies before proposing changes
+```
+
+**Expected Output:**
+- Architecture overview
+- Code flow documentation
+- Pattern identification
+- Dependency map
+- Integration points
+
+### Example 2: Evaluate a Technology
+
+**Request:**
+```
+Use researcher to evaluate whether gRPC would be better than REST for our
+inter-service communication needs
+```
+
+**Expected Output:**
+- Comparison analysis
+- Use case fit assessment
+- Performance implications
+- Migration effort
+- Recommendation with rationale
+
+---
+
+## Documentation Agent Examples
+
+### Example 1: Write API Documentation
+
+**Request:**
+```
+Use documentation to write comprehensive OpenAPI documentation for our payment
+API endpoints including all request/response formats and error codes
+```
+
+**Expected Output:**
+- OpenAPI specification
+- Endpoint documentation
+- Error documentation
+- Request/response examples
+- Authentication guide
+
+### Example 2: Create Architecture Guide
+
+**Request:**
+```
+Use documentation to create architecture guide explaining our microservices design,
+communication patterns, and deployment strategy for new developers
+```
+
+**Expected Output:**
+- Architecture overview
+- Component descriptions
+- Data flow diagrams
+- Communication patterns
+- Deployment guide
+- Troubleshooting guide
+
+---
+
+## Combining Multiple Agents
+
+### Example: Complete Feature Development
+
+**Task:** Implement a new notification feature end-to-end
+
+**Agent Sequence:**
+
+1. **planner** - Break down feature into tasks and create timeline
+2. **product-owner** - Define detailed user stories and acceptance criteria
+3. **architect** - Design notification system architecture and data flow
+4. **coder** - Implement notification service and API endpoints
+5. **tester** - Write comprehensive tests and create test strategy
+6. **reviewer** - Review code for quality and correctness
+7. **security** - Perform security review on user data handling
+8. **performance** - Optimize database queries and notification delivery
+9. **documentation** - Write API docs and admin guide
+10. **devops** - Set up monitoring and deployment pipeline
+11. **release-manager** - Plan release and create deployment checklist
+
+Each agent builds on previous outputs to create a complete, production-ready feature.
+
+---
+
+## Tips for Effective Agent Use
+
+- **Be specific**: Include constraints, goals, and context
+- **Review outputs**: Verify agent recommendations before acting
+- **Chain agents**: Use multiple agents for complex tasks
+- **Save results**: Keep agent outputs for reference and iteration
+- **Iterate**: Provide feedback to refine outputs
+- **Combine expertise**: Use multiple agents to cover all aspects of a task