ai-playbook 1.0.0

package/knowledge/engineering-principles.md

@@ -0,0 +1,65 @@
+# Engineering Principles
+
+Use this reference for broad software engineering judgment that applies across
+roles, skills, and projects.
+
+## Principles
+
+- Make the system easier to understand after the change.
+- Prefer the smallest change that solves the real problem.
+- Keep behavior and refactoring separate when risk is high.
+- Use existing patterns unless there is a clear reason to change them.
+- Design for failure at external boundaries.
+- Verify work proportional to risk and blast radius.
+- Document decisions that future maintainers will need to understand.
+
+## Maintainability
+
+Maintainable systems have:
+
+- Clear names and ownership.
+- Small modules with explicit responsibilities.
+- Stable interfaces and documented contracts.
+- Tests that protect important behavior.
+- Observability for production behavior.
+- Low surprise for future contributors.
+
+## Complexity Budget
+
+Add complexity only when it pays for itself. Good reasons include:
+
+- It removes meaningful duplication.
+- It isolates a volatile dependency.
+- It makes a risky operation safer.
+- It clarifies a domain concept.
+- It enables necessary scale, reliability, or security.
+
+Weak reasons include:
+
+- The abstraction may be useful someday.
+- The new tool is fashionable.
+- The current code looks too simple.
+- The design optimizes for a theoretical future.
+
+## Boundaries
+
+Important boundaries deserve explicit validation and error handling:
+
+- User input.
+- Network calls.
+- File systems.
+- Databases.
+- Message queues.
+- Third-party APIs.
+- Authentication and authorization.
+- Time, money, and irreversible side effects.
+
+## Operational Thinking
+
+Before calling work complete, ask:
+
+- How will we know it is working?
+- How will we know it is failing?
+- Can we roll it back or disable it?
+- What is the support burden?
+- What documentation will the next person need?

package/knowledge/product-discovery.md

@@ -0,0 +1,68 @@
+# Product Discovery
+
+Use this reference when shaping product ideas, validating problems, prioritizing
+work, or turning user needs into requirements.
+
+## Discovery Goals
+
+Product discovery reduces uncertainty about:
+
+- Who has the problem.
+- How painful or frequent the problem is.
+- What alternatives users already use.
+- Whether the proposed solution fits the workflow.
+- Whether the outcome supports business or project goals.
+
+## Problem Statement
+
+A useful problem statement names:
+
+- User or segment.
+- Situation or trigger.
+- Pain or unmet need.
+- Current workaround.
+- Desired outcome.
+- Evidence source.
+
+Example shape:
+
+```text
+When <user> is trying to <job>, they struggle with <pain>, which causes
+<impact>. We know this from <evidence>.
+```
+
+## Evidence Quality
+
+| Evidence | Strength |
+| --- | --- |
+| Direct user behavior | Strong |
+| Repeated customer interviews | Strong |
+| Support tickets and sales calls | Medium to strong |
+| Analytics trend | Medium to strong |
+| Internal stakeholder opinion | Weak to medium |
+| Founder or team intuition | Useful, but needs validation |
+
+## Prioritization Dimensions
+
+- User impact.
+- Business impact.
+- Confidence.
+- Effort.
+- Risk.
+- Strategic fit.
+- Time sensitivity.
+- Learning value.
+
+## Requirement Quality
+
+Good requirements describe:
+
+- The user outcome.
+- Acceptance criteria.
+- Constraints and non-goals.
+- Edge cases and permissions.
+- Analytics or learning signals.
+- Rollout and rollback expectations.
+
+Avoid requirements that prematurely prescribe implementation details unless the
+technical approach is itself part of the constraint.

package/knowledge/security-privacy.md

@@ -0,0 +1,54 @@
+# Security And Privacy
+
+Use this reference when a task touches data, identity, permissions, external
+systems, infrastructure, logging, or user trust.
+
+## Security Basics
+
+- Identify assets, actors, actions, and trust boundaries.
+- Authenticate identity before relying on it.
+- Authorize every protected action.
+- Validate and sanitize untrusted input.
+- Store secrets only in approved secret-management systems.
+- Encrypt sensitive data in transit and at rest where appropriate.
+- Log enough to investigate without leaking sensitive data.
+
+## Privacy Basics
+
+- Collect the minimum data needed for the stated purpose.
+- Name retention and deletion expectations.
+- Avoid exposing personal data in logs, errors, analytics, or prompts.
+- Separate production data from development and testing whenever possible.
+- Treat screenshots, exports, and generated reports as possible data leaks.
+
+## Common Risk Areas
+
+| Area | Risk |
+| --- | --- |
+| Authentication | Weak token validation, insecure sessions, missing revocation. |
+| Authorization | Broken object-level checks, cross-tenant access, admin bypasses. |
+| APIs | Injection, over-broad responses, missing rate limits. |
+| Logs | Secrets, tokens, personal data, or confidential business data. |
+| Dependencies | Known vulnerabilities, unmaintained packages, supply-chain risk. |
+| AI systems | Prompt injection, data leakage, tool misuse, unverified outputs. |
+| Infrastructure | Public storage, broad IAM permissions, unencrypted state. |
+
+## Review Questions
+
+- What data can this code read, write, or expose?
+- Who is allowed to perform this action?
+- What happens if a user changes an ID, tenant, role, or token?
+- Are secrets or personal data present in logs, traces, prompts, or errors?
+- What external systems are trusted?
+- What is the worst plausible misuse?
+
+## Escalation Triggers
+
+Escalate for human review when work involves:
+
+- Payment, financial, medical, legal, or regulated data.
+- New authentication or authorization flows.
+- Production credentials or secret handling.
+- Public exposure of private systems.
+- Security scans with high-severity findings.
+- Unclear data retention or consent requirements.

package/knowledge/testing-quality.md

@@ -0,0 +1,63 @@
+# Testing And Quality
+
+Use this reference when deciding how to verify work, how much testing is enough,
+or what quality gates should apply.
+
+## Verification Principle
+
+Verification should match risk. A small documentation fix may need proofreading.
+A production behavior change may need unit tests, integration tests, manual
+checks, monitoring, and rollback planning.
+
+## Test Types
+
+| Type | Best For |
+| --- | --- |
+| Unit test | Pure logic, edge cases, fast feedback. |
+| Integration test | Module boundaries, databases, APIs, queues, file systems. |
+| Contract test | Shared API or event schema compatibility. |
+| End-to-end test | Critical user workflows and system wiring. |
+| Snapshot test | Stable structured output or UI regression with careful review. |
+| Load test | Throughput, latency, saturation, and capacity limits. |
+| Security test | Auth, permissions, injection, secrets, dependency risk. |
+| Manual check | Visual behavior, exploratory workflows, ambiguous UX. |
+
+## Quality Gates
+
+- Requirements are testable.
+- Important behavior has automated coverage where practical.
+- Failure and edge cases are represented.
+- Tests are deterministic and isolated.
+- Test data does not include real secrets or unnecessary personal data.
+- Local checks or CI commands are documented.
+- Skipped verification is named with a reason.
+
+## Risk-Based Depth
+
+| Risk | Verification |
+| --- | --- |
+| Low | Read-through, formatting, targeted smoke check. |
+| Medium | Relevant automated tests plus manual check of changed behavior. |
+| High | Unit, integration, regression, observability, rollback, and peer review. |
+
+## Good Test Cases
+
+Good tests usually include:
+
+- Normal success path.
+- Boundary values.
+- Empty or missing input.
+- Invalid input.
+- Permission denied.
+- External dependency failure.
+- Retry or idempotency behavior.
+- Backward compatibility when contracts change.
+
+## Completion Language
+
+When summarizing verification, be precise:
+
+- "Ran `npm test` and it passed."
+- "Ran targeted unit tests for the changed module."
+- "Did not run tests; docs-only change."
+- "Could not verify browser behavior because the dev server failed to start."

package/package.json

@@ -0,0 +1,63 @@
+{
+  "name": "ai-playbook",
+  "version": "1.0.0",
+  "description": "Comprehensive AI engineering playbook with agents, prompts, skills, patterns, and best practices",
+  "type": "module",
+  "main": "./index.js",
+  "bin": {
+    "ai-playbook": "./bin/cli.js"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "scripts": {
+    "setup": "node bin/cli.js setup",
+    "sync": "bash setup.sh",
+    "list": "node bin/cli.js list",
+    "help": "node bin/cli.js help"
+  },
+  "keywords": [
+    "ai",
+    "engineering",
+    "prompts",
+    "agents",
+    "skills",
+    "patterns",
+    "best-practices",
+    "claude",
+    "gemini",
+    "codex",
+    "development"
+  ],
+  "author": "Srikanth Kanteti",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/srikanthkanteti/ai-playbook.git"
+  },
+  "homepage": "https://github.com/srikanthkanteti/ai-playbook",
+  "bugs": {
+    "url": "https://github.com/srikanthkanteti/ai-playbook/issues"
+  },
+  "files": [
+    "agents/",
+    "commands/",
+    "context/",
+    "hooks/",
+    "knowledge/",
+    "patterns/",
+    "prompts/",
+    "roles/",
+    "skills/",
+    "bin/",
+    "setup.sh",
+    "index.js",
+    "README.md",
+    "CLAUDE.md"
+  ],
+  "preferGlobal": true,
+  "directories": {
+    "lib": "./",
+    "bin": "./bin"
+  }
+}

package/patterns/README.md

@@ -0,0 +1,7 @@
+# Patterns
+
+Use this folder for reusable solution patterns that are broader than one project
+or role.
+
+Patterns should explain when to use the approach, trade-offs, implementation
+notes, and verification guidance.

package/prompts/README.md

@@ -0,0 +1,208 @@
+# Prompts
+
+Reusable prompt templates grouped by role and task type.
+
+## Overview
+
+Prompts are templates that structure how to communicate with AI assistants for specific tasks. They define:
+
+- **When to use** - Which situation calls for this prompt
+- **What to include** - Required context and information
+- **What to expect** - Clear output and success criteria
+- **Quality gates** - How to verify completeness
+
+## Available Prompts
+
+### Developer Prompts (`developer/`)
+
+For software development tasks:
+
+- **[implement-feature.md](developer/implement-feature.md)** - Build new features
+- **[fix-bug.md](developer/fix-bug.md)** - Resolve bugs and issues
+
+### Architect Prompts (`architect/`)
+
+For system design and architecture:
+
+- **[design-system.md](architect/design-system.md)** - Design systems and architecture
+
+### Reviewer Prompts (`reviewer/`)
+
+For code review and quality:
+
+- **[code-review.md](reviewer/code-review.md)** - Review pull requests
+
+### Debugger Prompts (`debugger/`)
+
+For issue diagnosis:
+
+- **[diagnose-issue.md](debugger/diagnose-issue.md)** - Debug problems
+
+### Product Owner Prompts (`product-owner/`)
+
+For product management:
+
+- **[define-feature.md](product-owner/define-feature.md)** - Define features
+
+### Support Prompts (`support/`)
+
+For customer support:
+
+- **[resolve-issue.md](support/resolve-issue.md)** - Resolve customer issues
+
+## Using Prompts
+
+### Basic Workflow
+
+1. **Find relevant prompt** - Match task to prompt type
+2. **Read template** - Understand structure
+3. **Gather context** - Collect all needed information
+4. **Fill in template** - Complete each section
+5. **Provide to Claude** - Paste complete prompt
+6. **Review output** - Check against quality gates
+7. **Iterate** - Request refinements as needed
+
+### Example
+
+```markdown
+# From: developer/implement-feature.md
+
+## Feature Spec
+- User can create custom dashboard
+- Drag-and-drop widgets
+- Save and share dashboards
+- Real-time updates
+
+## Constraints
+- Use existing widget library
+- Support responsive design
+- No new dependencies
+- Match current UI patterns
+
+[... complete template ...]
+```
+
+## Best Practices
+
+### Writing Effective Prompts
+
+**Do:**
+- ✓ Be specific and detailed
+- ✓ Include all relevant context
+- ✓ Define success criteria
+- ✓ List constraints upfront
+- ✓ Provide examples
+
+**Don't:**
+- ✗ Be vague or ambiguous
+- ✗ Assume shared knowledge
+- ✗ Skip constraints
+- ✗ Forget edge cases
+- ✗ Mix multiple tasks
+
+### Gathering Context
+
+For any prompt, provide:
+
+1. **Background** - What we're solving
+2. **Requirements** - What needs to happen
+3. **Constraints** - What's off-limits
+4. **Context** - Related code/systems
+5. **Examples** - Concrete scenarios
+
+### Iterating on Output
+
+1. Review output against quality gates
+2. Ask for clarifications
+3. Request specific refinements
+4. Verify against test cases
+5. Merge when ready
+
+## Prompt Structure
+
+All prompts include:
+
+```
+# [Prompt Name] Prompt
+
+**Role:** [Which role uses this]
+**Type:** [Category of work]
+**Context Needed:** [What to provide]
+
+## Template
+[Fill-in template]
+
+## When to Use
+[Situations where this applies]
+
+## Required Context
+[Must-have information]
+
+## Expected Output
+[What you should get back]
+
+## Quality Gates
+[Verification checklist]
+
+## Example Usage
+[Real example filled in]
+
+## Tips
+[Best practices]
+```
+
+## Quality Gates
+
+Every prompt includes quality gates to verify:
+
+✓ **Completeness** - All requirements met  
+✓ **Clarity** - No ambiguity  
+✓ **Correctness** - Works as intended  
+✓ **Feasibility** - Realistic scope  
+✓ **Measurability** - Success verified  
+
+## Related Documentation
+
+- See `agents/` for AI agent definitions
+- Check `skills/` for domain expertise
+- Review `hooks/` for automation
+- Explore `commands/` for workflows
+
+## Tips for Success
+
+### Template Customization
+
+- Adapt prompts to your needs
+- Add domain-specific sections
+- Adjust detail level
+- Combine related prompts
+- Create new prompts for unique tasks
+
+### Integration
+
+- Use prompts in documentation
+- Reference in onboarding
+- Include in standards
+- Share with team
+- Evolve over time
+
+## Contributing
+
+To add new prompts:
+
+1. Identify a recurring task
+2. Create template in relevant folder
+3. Include all sections
+4. Provide examples
+5. Test with team
+6. Document in README
+
+## Maintenance
+
+Review prompts quarterly:
+
+- Do they still work?
+- Are they being used?
+- Need improvements?
+- Remove outdated ones?
+- Add missing ones?

package/prompts/architect/README.md

@@ -0,0 +1,96 @@
+# Architect Prompts
+
+Reusable prompts for system architecture and design.
+
+## Available Prompts
+
+### [design-system.md](design-system.md)
+
+**Use when:** Designing systems or major architecture changes
+
+**Covers:**
+- Problem statement
+- Requirements (functional/non-functional)
+- Constraints
+- Existing architecture
+- Design questions
+- Deliverables
+
+**Good for:**
+- New system design
+- Architecture redesign
+- Scalability improvements
+- Migration planning
+
+## Using Architect Prompts
+
+### Design Process
+
+1. **Define problem** - Understand what to solve
+2. **List requirements** - Functional and non-functional
+3. **State constraints** - Tech, budget, timeline
+4. **Analyze existing** - Current state
+5. **Design system** - Architecture solution
+6. **Evaluate tradeoffs** - Different approaches
+7. **Document decisions** - Why certain choices
+
+## What Gets Delivered
+
+✓ Architecture diagram  
+✓ Component descriptions  
+✓ Data flow diagrams  
+✓ Technology recommendations  
+✓ Scalability analysis  
+✓ Risk assessment  
+✓ Migration plan  
+
+## Quality Gates
+
+Design must address:
+
+✓ **Completeness** - All requirements met  
+✓ **Feasibility** - Team can build  
+✓ **Scalability** - Handles growth  
+✓ **Maintainability** - Easy to operate  
+✓ **Cost** - Budget realistic  
+
+## Design Checklist
+
+- [ ] All requirements addressed
+- [ ] Constraints acknowledged
+- [ ] Tradeoffs documented
+- [ ] Technology justified
+- [ ] Scalability planned
+- [ ] Risks identified
+- [ ] Costs estimated
+- [ ] Timeline realistic
+- [ ] Team capable
+- [ ] Migration path clear
+
+## Best Practices
+
+### Effective Design Prompts
+
+- Start with problem, not solution
+- Be clear about constraints
+- List all requirements
+- Provide context
+- Ask specific design questions
+- Request alternatives
+- Expect tradeoffs
+
+### Evaluating Designs
+
+- Does it meet all requirements?
+- Is it feasible with available resources?
+- Can team understand and implement?
+- Does it scale appropriately?
+- Are risks identified and mitigated?
+- Is cost within budget?
+- Is timeline realistic?
+
+## Related Documentation
+
+- See `../README.md` for overview
+- Check skills/ for architecture skills
+- Review patterns/ for design patterns