ai-playbook 1.0.0

package/agents/SKILL.md

@@ -0,0 +1,633 @@
+# Specialized Agents Skill
+
+## Purpose
+
+This skill defines how to select and use specialized AI agents for different roles and responsibilities in software engineering and product development.
+
+Specialized agents are pre-configured AI assistants optimized for specific domains with focused expertise, curated tools, and clear output formats.
+
+---
+
+## Table of Contents
+
+1. Agent Selection
+2. Agent Types
+3. When to Use Each Agent
+4. Agent Tool Access
+5. Combining Agents
+6. Workflow Patterns
+7. Best Practices
+
+---
+
+## 1. Agent Selection
+
+### Selection Criteria
+
+Choose agents based on:
+
+| Criteria | Guidance |
+|----------|----------|
+| **Domain match** | Select agent whose specialty matches your task |
+| **Task complexity** | Simple tasks: single agent; complex tasks: multiple agents |
+| **Tool needs** | Verify agent has tools required (code writing, research, etc.) |
+| **Timeline** | Consider agent expertise and output quality |
+| **Scope** | Focused agents better than trying one agent for everything |
+
+### Decision Tree
+
+```
+What is your task?
+
+├─ Design/Architecture
+│  └─ → architect
+├─ Writing Code
+│  └─ → coder
+├─ Finding/Fixing Bugs
+│  └─ → debugger
+├─ Testing/QA
+│  └─ → tester
+├─ Improving Code
+│  └─ → refactorer
+├─ Reviewing Code
+│  └─ → reviewer
+├─ Security/Threats
+│  └─ → security
+├─ Performance/Optimization
+│  └─ → performance
+├─ Planning Work
+│  └─ → planner
+├─ Requirements/Features
+│  └─ → product-owner
+├─ Releases/Deployment
+│  └─ → release-manager
+├─ Infrastructure/DevOps
+│  └─ → devops
+├─ Customer Issues
+│  └─ → support
+├─ Research/Analysis
+│  └─ → researcher
+└─ Documentation/Guides
+   └─ → documentation
+```
+
+---
+
+## 2. Agent Types
+
+### Core Development Agents
+
+| Agent | Specialty | Key Skills | Tools |
+|-------|-----------|-----------|-------|
+| **architect** | Systems design | Data flow, scalability, patterns | Read, Grep, Write, Web research |
+| **coder** | Implementation | Production code, patterns | Read, Edit, Write, Bash |
+| **debugger** | Root cause | Issue diagnosis, trace | Read, Grep, Bash, Edit |
+| **tester** | Quality | Test design, validation | Read, Write, Edit, Bash |
+| **refactorer** | Quality improvement | Refactoring, modernizing | Read, Edit, Grep |
+
+### Quality Agents
+
+| Agent | Specialty | Key Skills | Tools |
+|-------|-----------|-----------|-------|
+| **reviewer** | Code assessment | Quality checks, standards | Read, Grep, Bash |
+| **security** | Threat analysis | Vulnerabilities, compliance | Read, Grep, Research |
+| **performance** | Optimization | Bottlenecks, scaling | Read, Grep, Bash |
+
+### Planning Agents
+
+| Agent | Specialty | Key Skills | Tools |
+|-------|-----------|-----------|-------|
+| **planner** | Project planning | Breakdown, estimates, risks | Read, Write, Analysis |
+| **product-owner** | Requirements | User stories, criteria | Read, Write, Research |
+| **release-manager** | Release coordination | Versioning, deployment | Read, Edit, Write |
+
+### Operations Agents
+
+| Agent | Specialty | Key Skills | Tools |
+|-------|-----------|-----------|-------|
+| **devops** | Infrastructure | CI/CD, IaC, containers | Read, Write, Bash |
+| **support** | Troubleshooting | Diagnostics, help | Read, Research, Bash |
+
+### Knowledge Agents
+
+| Agent | Specialty | Key Skills | Tools |
+|-------|-----------|-----------|-------|
+| **researcher** | Analysis | Codebase exploration | Read, Grep, Research |
+| **documentation** | Writing | API docs, guides | Read, Write, Research |
+
+---
+
+## 3. When to Use Each Agent
+
+### Architect
+
+**Use when:**
+- Designing new systems or major components
+- Planning architecture changes
+- Analyzing scalability needs
+- Creating data flow designs
+
+**Expected outputs:**
+- Architecture diagrams
+- Component interactions
+- Data flows
+- Scalability analysis
+- Risk assessment
+
+**Example:**
+```
+Use architect to design a distributed cache layer for our microservices 
+considering our 10K+ RPS requirement and consistency needs
+```
+
+### Coder
+
+**Use when:**
+- Implementing features
+- Writing new code
+- Adding functionality
+- Following project patterns
+
+**Expected outputs:**
+- Production code
+- Error handling
+- Logging
+- Tests
+- Documentation via code
+
+**Example:**
+```
+Use coder to implement user profile update endpoint with validation,
+error handling, and following existing API patterns
+```
+
+### Debugger
+
+**Use when:**
+- Investigating issues
+- Finding root causes
+- Analyzing failures
+- Diagnosing performance problems
+
+**Expected outputs:**
+- Root cause analysis
+- Reproduction steps
+- Fix recommendations
+- Verification approach
+
+**Example:**
+```
+Use debugger to diagnose why batch jobs occasionally fail with 
+database connection errors
+```
+
+### Tester
+
+**Use when:**
+- Creating test strategies
+- Writing tests
+- Improving coverage
+- Validating implementations
+
+**Expected outputs:**
+- Test plans
+- Test code
+- Coverage analysis
+- Edge cases
+- Validation approach
+
+**Example:**
+```
+Use tester to create comprehensive tests for payment processing
+covering happy path, failures, and concurrency
+```
+
+### Refactorer
+
+**Use when:**
+- Removing duplication
+- Improving code quality
+- Modernizing patterns
+- Addressing technical debt
+
+**Expected outputs:**
+- Refactored code
+- Consolidated logic
+- Improved structure
+- Maintained tests
+- Migration guide
+
+**Example:**
+```
+Use refactorer to consolidate duplicate auth logic across 3 middleware files
+and extract to a shared library
+```
+
+### Reviewer
+
+**Use when:**
+- Reviewing code
+- Assessing quality
+- Checking standards
+- Validating before merge
+
+**Expected outputs:**
+- Quality findings
+- Bug identification
+- Improvement suggestions
+- Risk assessment
+- Approval recommendation
+
+**Example:**
+```
+Use reviewer to review this pull request for correctness, performance,
+and security before we merge
+```
+
+### Security
+
+**Use when:**
+- Performing security reviews
+- Identifying vulnerabilities
+- Threat modeling
+- Compliance analysis
+
+**Expected outputs:**
+- Vulnerability findings
+- Threat analysis
+- Compliance gaps
+- Remediation steps
+- Security recommendations
+
+**Example:**
+```
+Use security to threat model our user data export feature for
+unauthorized access and data exposure risks
+```
+
+### Performance
+
+**Use when:**
+- Analyzing bottlenecks
+- Optimizing slow code
+- Planning scalability
+- Improving efficiency
+
+**Expected outputs:**
+- Bottleneck identification
+- Optimization recommendations
+- Benchmark results
+- Scalability analysis
+
+**Example:**
+```
+Use performance to identify bottlenecks in our notification system
+before scaling to 1M concurrent users
+```
+
+### Planner
+
+**Use when:**
+- Planning feature development
+- Breaking down work
+- Estimating effort
+- Creating roadmaps
+
+**Expected outputs:**
+- Task breakdown
+- Effort estimates
+- Dependencies
+- Timeline
+- Risk assessment
+
+**Example:**
+```
+Use planner to break down implementing OAuth2 authentication
+into tasks for a team of 3 with timeline
+```
+
+### Product Owner
+
+**Use when:**
+- Defining requirements
+- Creating user stories
+- Prioritizing features
+- Setting success criteria
+
+**Expected outputs:**
+- User stories
+- Acceptance criteria
+- Requirements specs
+- Success metrics
+- Prioritization
+
+**Example:**
+```
+Use product-owner to define requirements for our new real-time
+collaboration feature including success metrics
+```
+
+### Release Manager
+
+**Use when:**
+- Planning releases
+- Managing versions
+- Creating deployment plans
+- Planning rollbacks
+
+**Expected outputs:**
+- Release plan
+- Version/changelog
+- Deployment steps
+- Rollback procedures
+- Release notes
+
+**Example:**
+```
+Use release-manager to plan v2.0 release including versioning,
+deployment strategy, and rollback plan
+```
+
+### DevOps
+
+**Use when:**
+- Designing deployment pipelines
+- Setting up infrastructure
+- Configuring monitoring
+- Managing environments
+
+**Expected outputs:**
+- Pipeline configuration
+- Infrastructure code
+- Monitoring setup
+- Documentation
+- Scaling strategy
+
+**Example:**
+```
+Use devops to design CI/CD pipeline for our Node.js microservices
+with Kubernetes and GitHub Actions
+```
+
+### Support
+
+**Use when:**
+- Troubleshooting issues
+- Creating help documentation
+- Diagnosing problems
+- Creating guides
+
+**Expected outputs:**
+- Troubleshooting guides
+- Root cause analysis
+- Solutions/workarounds
+- FAQ documentation
+- Help articles
+
+**Example:**
+```
+Use support to create troubleshooting guide for common API errors
+our customers experience
+```
+
+### Researcher
+
+**Use when:**
+- Exploring codebases
+- Understanding architecture
+- Evaluating technologies
+- Analyzing patterns
+
+**Expected outputs:**
+- Architecture analysis
+- Pattern documentation
+- Technology evaluations
+- Understanding summaries
+- Comparison analyses
+
+**Example:**
+```
+Use researcher to explore our authentication system to understand
+current implementation before proposing changes
+```
+
+### Documentation
+
+**Use when:**
+- Writing API documentation
+- Creating guides
+- Writing architecture docs
+- Creating README files
+
+**Expected outputs:**
+- API documentation
+- User guides
+- Architecture guides
+- README files
+- Examples
+
+**Example:**
+```
+Use documentation to write OpenAPI docs for our payment API
+with all endpoints, errors, and request/response examples
+```
+
+---
+
+## 4. Agent Tool Access
+
+### Code Modification Tools
+- **Read**: Files and code
+- **Edit**: Code changes
+- **Write**: New files
+- **NotebookEdit**: Jupyter notebooks
+
+Agents with these: architect, coder, refactorer, documentation, devops
+
+### Code Analysis Tools
+- **Grep**: Pattern matching
+- **Glob**: File search
+- **Read**: Code inspection
+
+Agents with these: All agents
+
+### Execution Tools
+- **Bash**: System commands, testing, execution
+
+Agents with these: Most agents
+
+### Research Tools
+- **WebFetch**: Fetch external resources
+- **WebSearch**: Search for information
+
+Agents with these: researcher, documentation, security, product-owner
+
+---
+
+## 5. Combining Agents
+
+### Sequential Patterns
+
+**Research → Design → Implement → Test → Review**
+```
+1. researcher - Understand existing patterns
+2. architect - Design new component
+3. coder - Implement component
+4. tester - Create tests
+5. reviewer - Review for quality
+```
+
+**Plan → Design → Implement → Optimize**
+```
+1. planner - Break down work
+2. architect - Design system
+3. coder - Implement
+4. performance - Optimize
+```
+
+**Require → Design → Implement → Secure → Deploy**
+```
+1. product-owner - Define requirements
+2. architect - Design system
+3. coder - Implement
+4. security - Security review
+5. devops - Create deployment
+```
+
+### Parallel Patterns
+
+**Multiple reviewers for comprehensive coverage**
+```
+1. reviewer - Code quality
+2. security - Security issues
+3. performance - Performance concerns
+→ Combine findings
+```
+
+**Design verification**
+```
+1. architect - Design
+2. performance - Scalability analysis
+3. security - Security analysis
+→ Validate design
+```
+
+---
+
+## 6. Workflow Patterns
+
+### Feature Development Workflow
+
+```
+planner
+  ↓
+product-owner (define requirements)
+  ↓
+architect (design)
+  ↓
+coder (implement)
+  ↓
+tester (test)
+  ↓
+reviewer (quality check)
+  ↓
+security (security check)
+  ↓
+performance (optimization)
+  ↓
+documentation (create docs)
+  ↓
+release-manager (plan release)
+  ↓
+devops (deploy)
+```
+
+### Bug Fix Workflow
+
+```
+debugger (diagnose)
+  ↓
+coder (implement fix)
+  ↓
+tester (verify fix)
+  ↓
+reviewer (code review)
+  ↓
+devops (deploy)
+```
+
+### Architecture Improvement Workflow
+
+```
+researcher (analyze current)
+  ↓
+architect (design improvement)
+  ↓
+performance (analyze impact)
+  ↓
+security (review security)
+  ↓
+planner (plan migration)
+  ↓
+coder (implement)
+```
+
+---
+
+## 7. Best Practices
+
+### Selection Best Practices
+
+**Do:**
+- ✅ Choose agent whose specialty matches your task
+- ✅ Use multiple agents for complex tasks
+- ✅ Provide context about constraints and goals
+- ✅ Review outputs before acting
+- ✅ Chain agents based on output dependencies
+
+**Don't:**
+- ❌ Use one agent for all tasks
+- ❌ Skip agent review of important decisions
+- ❌ Combine unrelated tasks in one agent request
+- ❌ Ignore agent suggestions without review
+- ❌ Use wrong agent for the task
+
+### Request Best Practices
+
+**Do:**
+- ✅ Be specific about the task
+- ✅ Include relevant constraints
+- ✅ Provide necessary context
+- ✅ State success criteria
+- ✅ Mention scope limitations
+
+**Don't:**
+- ❌ Be vague or ambiguous
+- ❌ Skip important constraints
+- ❌ Ask for unrelated tasks together
+- ❌ Assume agent knowledge
+- ❌ Overload with information
+
+### Workflow Best Practices
+
+**Do:**
+- ✅ Use sequential agents for dependent tasks
+- ✅ Save agent outputs for reference
+- ✅ Use parallel agents for independent reviews
+- ✅ Iterate on outputs
+- ✅ Document agent decisions
+
+**Don't:**
+- ❌ Skip planning before implementation
+- ❌ Implement before design review
+- ❌ Deploy without comprehensive testing
+- ❌ Skip security review
+- ❌ Ignore performance analysis
+
+---
+
+## Version
+
+**Version:** 1.0
+
+This skill defines how to use the 15 specialized agents. Update as new agents are added or existing ones are modified.

package/agents/architect/AGENT.md

@@ -0,0 +1,44 @@
+---
+name: architect
+description: Systems architect for designing solution architectures, data flows, and implementation strategies
+tools: [Read, Grep, Glob, Bash, Write, Edit, WebFetch, WebSearch]
+---
+
+# Architect Agent
+
+Specialized agent for system and solution architecture design.
+
+## Responsibilities
+
+- Design system architectures and component interactions
+- Create data flow diagrams and sequences
+- Evaluate architectural tradeoffs
+- Propose scalability and reliability patterns
+- Analyze existing codebase patterns
+- Document architecture decisions
+
+## When to Use
+
+Use this agent when you need to:
+- Design new system components or services
+- Plan major refactoring initiatives
+- Evaluate architectural approaches
+- Document system design decisions
+- Analyze cross-service data flows
+- Plan migrations or infrastructure changes
+
+## What It Produces
+
+- Architecture diagrams (ASCII or description)
+- Component interaction flows
+- Data flow specifications
+- Scalability analysis
+- Risk assessments
+- Implementation roadmaps
+
+## Tools Available
+
+- Code exploration: Read, Grep, Glob
+- System commands: Bash
+- Documentation: Write, Edit
+- Research: WebFetch, WebSearch

package/agents/architect/README.md

@@ -0,0 +1,5 @@
+# Architect Agent
+
+Use this folder for the architect agent definition.
+
+Load `AGENT.md` for the operating model, responsibilities, and expected outputs.

package/agents/coder/AGENT.md

@@ -0,0 +1,43 @@
+---
+name: coder
+description: Implementation specialist for writing production-quality code following project patterns
+tools: [Read, Grep, Glob, Bash, Write, Edit, NotebookEdit]
+---
+
+# Coder Agent
+
+Specialized agent for implementing features and writing code.
+
+## Responsibilities
+
+- Implement new features and functionality
+- Write production-quality code
+- Follow existing project patterns and conventions
+- Handle error scenarios
+- Write meaningful logging and instrumentation
+- Implement incremental changes
+
+## When to Use
+
+Use this agent when you need to:
+- Implement new features
+- Write code following project patterns
+- Add functionality to existing systems
+- Complete feature specifications
+- Write library code or utilities
+- Implement API endpoints or handlers
+
+## What It Produces
+
+- Production-ready code
+- Implementation following existing patterns
+- Error handling and edge cases
+- Logging and observability
+- Code documentation via naming and structure
+
+## Tools Available
+
+- Code reading and analysis: Read, Grep, Glob
+- Execution: Bash
+- Code creation and modification: Write, Edit
+- Notebook support: NotebookEdit

package/agents/coder/README.md

@@ -0,0 +1,5 @@
+# Coder Agent
+
+Use this folder for the coder agent definition.
+
+Load `AGENT.md` for implementation posture, workflow, and completion criteria.