ai-playbook 1.0.0

package/roles/devops/workflow.md

@@ -0,0 +1,197 @@
+# Workflow
+
+This document describes the canonical lifecycle for infrastructure and DevOps work, from
+initial requirement through production operation and ongoing maintenance.
+
+---
+
+## Phases
+
+### 1. Requirement & Discovery
+**Goal:** Understand what needs to be built and why.
+
+- [ ] Clarify business requirement or incident that triggered the request.
+- [ ] Identify SLOs: availability targets, latency, recovery time objectives (RTO/RPO).
+- [ ] Document constraints: compliance, security, cost, organizational policies.
+- [ ] Identify dependencies: applications, services, databases, external systems.
+- [ ] Define success metrics: reliability, cost, performance, security posture.
+
+**Deliverable:** Requirement summary with SLOs, constraints, and dependencies documented.
+
+---
+
+### 2. Design & Architecture
+**Goal:** Create a reliable, secure, and cost-effective solution.
+
+- [ ] Review existing infrastructure patterns and conventions.
+- [ ] Evaluate multiple approaches (on-premise vs. cloud, single-region vs. multi-region).
+- [ ] Document trade-offs: reliability vs. complexity, cost vs. performance.
+- [ ] Create architecture diagrams showing topology, dependencies, and data flows.
+- [ ] Design for failure: identify single points of failure and mitigation strategies.
+- [ ] Plan disaster recovery and business continuity procedures.
+- [ ] Estimate costs and resource requirements.
+
+**Deliverable:** Architecture design document with diagrams, trade-offs, and risk assessment.
+
+---
+
+### 3. Security & Compliance Review
+**Goal:** Ensure infrastructure meets security and compliance requirements.
+
+- [ ] Review security checklist from `skills/security/`.
+- [ ] Plan for least-privilege access controls and secrets management.
+- [ ] Identify compliance requirements (SOC2, HIPAA, GDPR, etc.).
+- [ ] Plan for encryption at rest and in transit.
+- [ ] Design network segmentation and firewall rules.
+- [ ] Plan for security monitoring and audit logging.
+
+**Deliverable:** Security and compliance review document with identified controls.
+
+---
+
+### 4. Infrastructure-as-Code Implementation
+**Goal:** Build reproducible, version-controlled infrastructure.
+
+- [ ] Create Terraform modules, CloudFormation templates, or Helm charts.
+- [ ] Follow IaC best practices: modularity, reusability, clear variable naming.
+- [ ] Implement infrastructure validation and linting.
+- [ ] Version control all infrastructure code with clear commit messages.
+- [ ] Implement code review process before merging infrastructure changes.
+- [ ] Create and maintain detailed comments explaining non-obvious decisions.
+
+**Deliverable:** Version-controlled, well-documented infrastructure code.
+
+---
+
+### 5. Staging & Testing
+**Goal:** Validate infrastructure in a production-like environment before deploying.
+
+- [ ] Deploy infrastructure to staging environment using IaC.
+- [ ] Verify all components (compute, networking, storage, security) are correctly configured.
+- [ ] Test failover and recovery procedures.
+- [ ] Perform load testing to validate scalability and performance.
+- [ ] Test security controls and access restrictions.
+- [ ] Validate monitoring and alerting configurations.
+
+**Deliverable:** Staging deployment report with test results and any issues identified.
+
+---
+
+### 6. Monitoring & Observability Setup
+**Goal:** Ensure production systems are observable and maintainable.
+
+- [ ] Configure metrics collection (Prometheus, CloudWatch, etc.).
+- [ ] Set up centralized logging (ELK, Splunk, CloudLogging).
+- [ ] Create dashboards for key infrastructure and application metrics.
+- [ ] Define SLOs and error budgets aligned with business requirements.
+- [ ] Configure alerting for critical conditions and thresholds.
+- [ ] Create runbooks for common operational tasks and incidents.
+
+**Deliverable:** Monitoring stack configured with dashboards, alerts, and runbooks.
+
+---
+
+### 7. Production Deployment
+**Goal:** Deploy infrastructure to production with minimal risk.
+
+- [ ] Schedule deployment during low-traffic window if possible.
+- [ ] Brief team on deployment plan and rollback procedures.
+- [ ] Deploy in phases (if applicable) using blue-green or canary strategies.
+- [ ] Verify each deployment phase with monitoring and health checks.
+- [ ] Document deployment execution and any issues encountered.
+- [ ] Maintain communication channel for incident response.
+
+**Deliverable:** Production infrastructure deployed and validated.
+
+---
+
+### 8. Post-Deployment Validation
+**Goal:** Confirm production infrastructure meets SLOs and requirements.
+
+- [ ] Monitor key metrics and dashboards for anomalies.
+- [ ] Verify all alerts and notifications are firing correctly.
+- [ ] Test failover scenarios and recovery procedures.
+- [ ] Confirm backups are working and restorable.
+- [ ] Validate security policies and access controls are enforced.
+- [ ] Verify cost tracking and budget alerts are in place.
+
+**Deliverable:** Post-deployment validation report confirming SLO compliance.
+
+---
+
+### 9. Documentation & Knowledge Transfer
+**Goal:** Capture operational knowledge for future operators.
+
+- [ ] Update architecture documentation with production details.
+- [ ] Create or update operational runbooks.
+- [ ] Document troubleshooting procedures for common issues.
+- [ ] Document disaster recovery procedures and recovery steps.
+- [ ] Conduct knowledge transfer session with on-call team.
+- [ ] Create alerts and escalation procedures for critical alerts.
+
+**Deliverable:** Complete documentation for operations and incident response.
+
+---
+
+### 10. Ongoing Operations & Optimization
+**Goal:** Maintain, monitor, and continuously improve infrastructure.
+
+- [ ] Monitor infrastructure health and performance metrics continuously.
+- [ ] Respond to incidents and perform root cause analysis.
+- [ ] Implement performance improvements based on monitoring data.
+- [ ] Optimize costs by right-sizing resources and leveraging reserved capacity.
+- [ ] Apply security patches and updates regularly.
+- [ ] Conduct regular disaster recovery drills.
+- [ ] Review and update documentation as infrastructure evolves.
+
+**Deliverable:** Healthy, secure, cost-optimized production infrastructure.
+
+---
+
+## Workflow Triggers
+
+This workflow activates when:
+
+- A new infrastructure component or service needs to be built.
+- An existing infrastructure requires significant changes (scaling, redundancy, compliance).
+- A production incident reveals infrastructure weaknesses requiring architectural changes.
+- Cost optimization or performance improvements are needed.
+- Security vulnerabilities or compliance gaps are discovered.
+- Business requirements change, affecting SLOs or infrastructure design.
+
+---
+
+## Decision Gates
+
+Before proceeding to the next phase:
+
+1. **After Discovery:** Requirement and SLOs are clearly documented and agreed upon.
+2. **After Design:** Architecture is reviewed and approved by infrastructure team and stakeholders.
+3. **After Security Review:** Security and compliance concerns are addressed and documented.
+4. **After IaC Implementation:** Code is reviewed, tested, and ready for staging.
+5. **After Staging:** All tests pass and infrastructure behaves as expected.
+6. **After Monitoring Setup:** Observability is confirmed to be working correctly.
+7. **After Production Deployment:** Deployment succeeds and post-deployment validation passes.
+8. **After Documentation:** All documentation is complete and communicated to operations team.
+
+If any gate fails, resolve the issue before proceeding to the next phase.
+
+---
+
+## Role & Responsibilities
+
+- **DevOps Engineer:** Leads design, implementation, and deployment of infrastructure.
+- **Infrastructure Team:** Reviews architecture, security, and IaC code.
+- **Application Team:** Provides requirements, performance constraints, and testing support.
+- **Security Team:** Reviews security and compliance controls.
+- **On-Call Team:** Inherits ownership of production infrastructure after deployment.
+
+---
+
+## Timeline Guidance
+
+- **Small change (configuration, monitoring, single service):** 1-3 days
+- **Medium change (new service, significant scaling):** 1-2 weeks
+- **Large change (architectural redesign, multi-region):** 2-8 weeks
+
+Timelines vary based on complexity, approval requirements, and testing needs.

package/roles/qa/README.md

@@ -0,0 +1,16 @@
+# QA Role
+
+Use this folder for quality-assurance role guidance.
+
+This role packet defines how to plan, execute, automate, and report quality
+work across product changes.
+
+## Files
+
+- `role.md` - Operating model for QA work.
+- `responsibilities.md` - Primary ownership areas.
+- `workflow.md` - Standard QA workflow.
+- `triggers.md` - When to activate this role.
+- `skill-map.md` - Related skills and contexts.
+- `checklists.md` - Reusable QA checklists.
+- `examples.md` - Example QA outputs.

package/roles/qa/api-testing/README.md

@@ -0,0 +1,6 @@
+# API Testing
+
+Use this folder for QA role guidance related to API testing.
+
+Add contract checks, integration test patterns, fixtures, negative cases, and
+test-data guidance when this packet becomes active.

package/roles/qa/automation/README.md

@@ -0,0 +1,6 @@
+# Automation
+
+Use this folder for QA role guidance related to test automation.
+
+Add automation strategy, selector guidance, flake handling, CI integration, and
+maintenance practices when this packet becomes active.

package/roles/qa/checklists.md

@@ -0,0 +1,24 @@
+# QA Checklists
+
+## Test Planning
+
+- [ ] Acceptance criteria are clear and testable.
+- [ ] Critical user journeys are identified.
+- [ ] Positive, negative, boundary, and permission cases are listed.
+- [ ] Required test data and environments are available.
+- [ ] Dependencies and integration points are understood.
+
+## Execution
+
+- [ ] Functional checks cover the changed behavior.
+- [ ] Regression checks cover nearby existing behavior.
+- [ ] Exploratory testing covers failure states and unusual inputs.
+- [ ] Automated tests are added or updated where valuable.
+- [ ] Evidence is captured for failures and release-critical passes.
+
+## Release Readiness
+
+- [ ] Critical and high severity defects are resolved or accepted.
+- [ ] Blockers and residual risks are documented.
+- [ ] Test results are summarized with pass, fail, blocked, and not-run status.
+- [ ] Follow-up coverage or automation work is recorded.

package/roles/qa/examples/README.md

@@ -0,0 +1,6 @@
+# QA Examples
+
+Use this folder for QA role examples.
+
+Examples should show test plans, bug reports, regression notes, automation
+reviews, and release-quality gates.

package/roles/qa/examples.md

@@ -0,0 +1,27 @@
+# QA Examples
+
+## Defect Report
+
+```markdown
+Title: Checkout fails when saved card requires 3DS challenge
+Severity: High
+Environment: staging
+Steps:
+1. Sign in as a user with a saved 3DS card.
+2. Add any paid plan to checkout.
+3. Submit payment.
+Expected: User is redirected to the 3DS challenge.
+Actual: Checkout displays a generic failure and no retry path.
+Evidence: staging logs, screenshot, request id.
+```
+
+## Release Summary
+
+```markdown
+Status: Conditional go
+Passed: Core signup, checkout, billing update, cancellation
+Failed: None
+Blocked: Tax calculation for Canadian addresses pending test data
+Risks: Limited browser coverage on Safari
+Recommendation: Ship after tax fixture is validated or explicitly defer Canada launch.
+```

package/roles/qa/performance/README.md

@@ -0,0 +1,6 @@
+# Performance Testing
+
+Use this folder for QA role guidance related to performance testing.
+
+Add workload models, load-test plans, thresholds, reporting templates, and
+regression checks when this packet becomes active.

package/roles/qa/playwright/README.md

@@ -0,0 +1,6 @@
+# Playwright
+
+Use this folder for QA role guidance related to Playwright.
+
+Add test structure, fixtures, selectors, traces, screenshots, CI usage, and
+debugging practices when this packet becomes active.

package/roles/qa/responsibilities.md

@@ -0,0 +1,16 @@
+# QA Responsibilities
+
+## Core Ownership
+
+- Test planning and quality strategy for product changes.
+- Functional, regression, exploratory, and integration validation.
+- Defect reproduction, isolation, severity assessment, and retest.
+- Automation recommendations and maintenance.
+- Release readiness reporting.
+
+## Collaboration
+
+- Work with product owners to clarify acceptance criteria.
+- Work with developers to identify implementation risk and test seams.
+- Work with SRE or DevOps on environment, deployment, and reliability signals.
+- Work with support teams to turn customer issues into regression coverage.

package/roles/qa/role.md

@@ -0,0 +1,47 @@
+# QA Engineer Role
+
+## Purpose
+
+You are acting as a **Senior QA Engineer** responsible for ensuring product
+changes are correct, testable, reliable, and ready for release.
+
+This role defines how you plan quality work, find risks, verify behavior, and
+communicate release confidence.
+
+## Responsibilities
+
+- Understand acceptance criteria, user journeys, and risk areas.
+- Build test plans that cover functional, integration, regression, and edge cases.
+- Create and maintain automated tests where automation provides durable value.
+- Perform exploratory testing to discover gaps that scripted tests miss.
+- Validate defects, reproduce failures, and provide actionable evidence.
+- Review requirements and designs for ambiguity, missing states, and untestable promises.
+- Report release readiness with clear pass, fail, blocked, and risk status.
+
+## Mindset
+
+Prioritize:
+
+1. **User impact** - Test the paths that matter most to real users.
+2. **Risk** - Spend the most attention where failure would hurt most.
+3. **Evidence** - Support claims with reproducible steps, logs, screenshots, or test output.
+4. **Automation value** - Automate stable, repeatable checks and avoid brittle noise.
+5. **Clarity** - Make defects and quality status easy for the team to act on.
+
+## Constraints
+
+You must never:
+
+- Mark a change as verified without running the relevant checks.
+- Hide known release risks or ambiguous results.
+- Treat automation as a substitute for risk analysis.
+- File vague bugs without reproduction steps or expected behavior.
+- Use production data in tests unless explicitly approved and protected.
+
+## Success Criteria
+
+- Acceptance criteria are verified.
+- Critical and high-risk flows have appropriate coverage.
+- Defects include clear reproduction, evidence, impact, and severity.
+- Automated tests are stable, meaningful, and maintainable.
+- Release status is clear enough for a go/no-go decision.

package/roles/qa/selenium/README.md

@@ -0,0 +1,6 @@
+# Selenium
+
+Use this folder for QA role guidance related to Selenium.
+
+Add browser matrix, page-object patterns, wait strategies, grid setup, and flake
+triage notes when this packet becomes active.

package/roles/qa/skill-map.md

@@ -0,0 +1,14 @@
+# QA Skill Map
+
+## Primary Skills
+
+- `skills/qa/` - Test strategy, coverage, and quality gates.
+- `skills/software-development/` - Code-aware testing and defect isolation.
+- `skills/security/` - Security and privacy validation.
+- `skills/performance/` - Performance and load-testing considerations.
+
+## Context
+
+- `context/engineering.md` - Engineering standards and delivery process.
+- `context/coding-style.md` - Project conventions that affect test code.
+- `projects/<project>/` - Project-specific flows, risks, and environments.

package/roles/qa/triggers.md

@@ -0,0 +1,10 @@
+# QA Triggers
+
+Use the QA role when work involves:
+
+- Verifying a feature, bug fix, migration, or release candidate.
+- Designing test coverage for a new workflow.
+- Investigating flaky tests or unclear quality signals.
+- Creating regression plans after a production incident.
+- Reviewing acceptance criteria for testability.
+- Deciding whether a change is ready to ship.

package/roles/qa/workflow.md

@@ -0,0 +1,9 @@
+# QA Workflow
+
+1. Load product context, acceptance criteria, and affected user journeys.
+2. Identify risk areas, dependencies, test data needs, and environment constraints.
+3. Create or update the test plan.
+4. Execute functional, integration, regression, and exploratory checks.
+5. Record defects with reproduction steps, impact, evidence, and expected behavior.
+6. Retest fixes and update automation where it reduces future risk.
+7. Summarize release readiness, open risks, and recommended next actions.

package/roles/software-architect/README.md

@@ -0,0 +1,16 @@
+# Software Architect Role
+
+Use this folder for software-architecture role guidance.
+
+This role packet defines how to evaluate architecture decisions, document
+trade-offs, and guide system design work.
+
+## Files
+
+- `role.md` - Operating model for architecture work.
+- `responsibilities.md` - Primary ownership areas.
+- `workflow.md` - Standard architecture workflow.
+- `triggers.md` - When to activate this role.
+- `skill-map.md` - Related skills and contexts.
+- `checklists.md` - Reusable architecture checklists.
+- `examples.md` - Example architecture outputs.

package/roles/software-architect/agents/README.md

@@ -0,0 +1,6 @@
+# Agents
+
+Use this folder for software-architecture guidance related to AI agents.
+
+Add agent boundaries, tool design, memory, evaluation, safety, and orchestration
+patterns when this packet becomes active.

package/roles/software-architect/ai-architecture/README.md

@@ -0,0 +1,6 @@
+# AI Architecture
+
+Use this folder for software-architecture guidance related to AI systems.
+
+Add model selection, orchestration, evaluation, observability, safety, and
+deployment patterns when this packet becomes active.

package/roles/software-architect/aws/README.md

@@ -0,0 +1,6 @@
+# AWS
+
+Use this folder for software-architecture guidance related to AWS.
+
+Add service-selection notes, reference architectures, security, networking,
+cost, and operational guidance when this packet becomes active.

package/roles/software-architect/azure/README.md

@@ -0,0 +1,6 @@
+# Azure
+
+Use this folder for software-architecture guidance related to Azure.
+
+Add service-selection notes, reference architectures, identity, networking,
+cost, and operational guidance when this packet becomes active.

package/roles/software-architect/caching/README.md

@@ -0,0 +1,6 @@
+# Caching
+
+Use this folder for software-architecture guidance related to caching.
+
+Add cache strategy, invalidation, consistency, TTL, failure modes, and
+observability guidance when this packet becomes active.

package/roles/software-architect/checklists.md

@@ -0,0 +1,25 @@
+# Software Architect Checklists
+
+## Architecture Framing
+
+- [ ] Business goal, success metrics, and non-goals are documented.
+- [ ] Functional and quality requirements are separated.
+- [ ] Current-state dependencies and constraints are mapped.
+- [ ] Data ownership and consistency needs are understood.
+- [ ] Security, privacy, and compliance requirements are identified.
+
+## Design Review
+
+- [ ] Interfaces and ownership boundaries are explicit.
+- [ ] Failure modes and recovery paths are described.
+- [ ] Observability, deployment, and rollback are included.
+- [ ] Scalability and performance assumptions are stated.
+- [ ] Cost and operational burden are considered.
+- [ ] Alternatives and trade-offs are documented.
+
+## Delivery Readiness
+
+- [ ] Implementation can be split into safe increments.
+- [ ] Migration and compatibility risks are covered.
+- [ ] Open questions have owners.
+- [ ] ADR or design document is linked from the project docs.

package/roles/software-architect/cloud/README.md

@@ -0,0 +1,6 @@
+# Cloud
+
+Use this folder for software-architecture guidance related to cloud systems.
+
+Add provider-neutral architecture patterns, security, reliability, cost, and
+operations guidance when this packet becomes active.

package/roles/software-architect/database-design/README.md

@@ -0,0 +1,6 @@
+# Database Design
+
+Use this folder for software-architecture guidance related to database design.
+
+Add modeling, indexing, migration, consistency, scaling, and operational
+guidance when this packet becomes active.

package/roles/software-architect/diagrams/README.md

@@ -0,0 +1,6 @@
+# Diagrams
+
+Use this folder for software-architecture diagram guidance.
+
+Add diagram conventions, examples, notation, review criteria, and export
+guidance when this packet becomes active.

package/roles/software-architect/distributed-systems/README.md

@@ -0,0 +1,7 @@
+# Distributed Systems
+
+Use this folder for software-architecture guidance related to distributed
+systems.
+
+Add consistency, coordination, partitioning, resilience, observability, and
+failure-mode guidance when this packet becomes active.

package/roles/software-architect/docker/README.md

@@ -0,0 +1,6 @@
+# Docker
+
+Use this folder for software-architecture guidance related to Docker.
+
+Add container design, image boundaries, runtime assumptions, security, and
+deployment trade-offs when this packet becomes active.

package/roles/software-architect/event-driven/README.md

@@ -0,0 +1,7 @@
+# Event Driven
+
+Use this folder for software-architecture guidance related to event-driven
+systems.
+
+Add event schemas, ordering, retries, idempotency, replay, and observability
+guidance when this packet becomes active.

package/roles/software-architect/examples/README.md

@@ -0,0 +1,6 @@
+# Software Architect Examples
+
+Use this folder for software-architecture examples.
+
+Examples should show system designs, ADRs, diagrams, trade-off analysis, and
+review feedback.

package/roles/software-architect/examples.md

@@ -0,0 +1,22 @@
+# Software Architect Examples
+
+## ADR Skeleton
+
+```markdown
+# ADR: Move search indexing to an async pipeline
+
+Status: Proposed
+Context: Search writes currently happen inline with user updates and increase p95 latency.
+Decision: Publish domain events and process indexing through a durable worker.
+Alternatives: Inline writes, scheduled batch indexing, direct database triggers.
+Consequences: Lower request latency, eventual consistency, new queue monitoring required.
+Rollout: Dual-write events, shadow worker, compare index drift, then cut over.
+```
+
+## Design Review Finding
+
+```markdown
+Risk: The proposed cache has no invalidation owner.
+Impact: Users may see stale entitlement state after plan changes.
+Recommendation: Define the billing service as cache invalidation owner and add a bounded TTL.
+```

package/roles/software-architect/gcp/README.md

@@ -0,0 +1,6 @@
+# GCP
+
+Use this folder for software-architecture guidance related to Google Cloud.
+
+Add service-selection notes, reference architectures, identity, networking,
+cost, and operational guidance when this packet becomes active.

package/roles/software-architect/kubernetes/README.md

@@ -0,0 +1,6 @@
+# Kubernetes
+
+Use this folder for software-architecture guidance related to Kubernetes.
+
+Add workload design, service boundaries, scaling, networking, reliability, and
+operations guidance when this packet becomes active.

package/roles/software-architect/messaging/README.md

@@ -0,0 +1,6 @@
+# Messaging
+
+Use this folder for software-architecture guidance related to messaging systems.
+
+Add queues, topics, delivery guarantees, retries, dead letters, schemas, and
+observability guidance when this packet becomes active.

package/roles/software-architect/rag/README.md

@@ -0,0 +1,7 @@
+# RAG
+
+Use this folder for software-architecture guidance related to retrieval-augmented
+generation.
+
+Add corpus design, chunking, embeddings, retrieval evaluation, grounding, and
+safety guidance when this packet becomes active.

package/roles/software-architect/responsibilities.md

@@ -0,0 +1,17 @@
+# Software Architect Responsibilities
+
+## Core Ownership
+
+- Architecture framing and option analysis.
+- System boundary and interface definition.
+- Data flow, consistency, and storage decisions.
+- Reliability, scalability, security, and operability review.
+- Migration and modernization planning.
+- Architecture decision records and diagrams.
+
+## Collaboration
+
+- Work with product teams to clarify business capabilities and constraints.
+- Work with engineers to validate implementation feasibility.
+- Work with DevOps and SRE teams to align deployment and operations.
+- Work with security stakeholders on threat models and compliance needs.