ai-playbook 1.0.0

package/hooks/pre-task/validate-environment.md

@@ -0,0 +1,48 @@
+# validate-environment Hook
+
+**Category:** pre-task  
+**Purpose:** Validate development environment is properly configured  
+**Trigger:** Before starting a new task
+
+## Description
+
+Checks that all required tools, dependencies, and configuration files are in place before starting work.
+
+## Checks Performed
+
+- Required tools installed (git, node, npm, etc.)
+- `.env` file exists (creates from `.env.example` if needed)
+- Dependencies installed (`node_modules`, etc.)
+- Git repository initialized
+- Uncommitted changes warning
+
+## Success Criteria
+
+✓ All required tools available  
+✓ `.env` file configured  
+✓ Dependencies installed  
+✓ Valid git repository  
+
+## Failure Handling
+
+| Issue | Action |
+|-------|--------|
+| Missing tool | Install and retry |
+| Missing .env | Create from template, update values |
+| Missing dependencies | Run npm install / pip install |
+| Not a git repo | Initialize git repository |
+
+## Configuration
+
+No configuration needed. Hook auto-detects requirements based on project files.
+
+## Related Hooks
+
+- `check-branch.sh` - Verify on correct branch (runs after this)
+
+## Implementation Notes
+
+- Runs silently if `SKIP_HOOKS=true`
+- Auto-installs dependencies in local dev
+- Requires manual setup in CI
+- Checks are non-blocking except missing tools

package/hooks/security-check/README.md

@@ -0,0 +1,6 @@
+# Security Check Hooks
+
+Use this folder for security hook guidance.
+
+Hook files should cover dependency audits, secret scans, policy checks, and
+escalation behavior.

package/hooks/security-check/dependency-audit.md

@@ -0,0 +1,85 @@
+# dependency-audit Hook
+
+**Category:** security-check  
+**Purpose:** Audit dependencies for known vulnerabilities  
+**Trigger:** Before push / in CI
+
+## Description
+
+Scans project dependencies for known security vulnerabilities and suggests updates.
+
+## Package Managers Supported
+
+| Language | Tool |
+|----------|------|
+| Node.js | npm audit |
+| Python | pip-audit |
+| Go | govulncheck |
+| Ruby | bundle audit |
+
+## Vulnerability Levels
+
+- **Critical** - Exploitable in production (always blocking)
+- **High** - Likely exploitable (blocking in CI)
+- **Moderate** - Potentially exploitable (warning)
+- **Low** - Low severity issues (informational)
+
+## Success Criteria
+
+✓ No critical vulnerabilities  
+✓ No high vulnerabilities (in CI)  
+✓ No deprecated dependencies  
+
+## Typical Issues Found
+
+- Known CVE exploits
+- Unmaintained packages
+- Outdated dependencies
+- License conflicts
+
+## Remediation
+
+1. **Update package**: `npm update package`
+2. **Major version bump**: May require code changes
+3. **Find alternative**: If package unmaintained
+4. **Accept risk**: Document in security review
+
+## Configuration
+
+Configure severity threshold:
+```json
+{
+  "audit": {
+    "level": "moderate"
+  }
+}
+```
+
+## Failure Handling
+
+| Vulnerability | Local | CI |
+|---|---|---|
+| Critical | Error | Error |
+| High | Prompt | Error |
+| Moderate | Warning | Prompt |
+| Low | Info | Info |
+
+## Related Hooks
+
+- `secrets-scan.md` - Secret detection
+- `code-review/check-coverage.md` - Quality
+
+## Common Issues
+
+| Issue | Action |
+|-------|--------|
+| False positive | File `.npmauditignore` |
+| Package unmaintained | Find alternative |
+| Breaking changes | Update code + tests |
+
+## Implementation Notes
+
+- Runs before push (not commit)
+- Checks package-lock files
+- Updates remediation options
+- Integrates with GitHub security

package/hooks/security-check/secrets-scan.md

@@ -0,0 +1,77 @@
+# secrets-scan Hook
+
+**Category:** security-check  
+**Purpose:** Scan for exposed secrets before pushing  
+**Trigger:** Before git push / in CI
+
+## Description
+
+Detects exposed API keys, passwords, tokens, and other sensitive data that should not be committed.
+
+## Detection Methods
+
+- **gitleaks** - Regex patterns for known secret formats
+- **Pattern matching** - API keys, passwords, private keys
+- **.env file check** - Prevents .env from being committed
+
+## Secrets Detected
+
+- AWS access keys and secrets
+- API keys and tokens
+- Private SSH keys
+- Database credentials
+- OAuth tokens
+- Slack webhooks
+- Database connection strings
+
+## Success Criteria
+
+✓ No exposed secrets  
+✓ `.env` file not staged  
+✓ No hardcoded credentials  
+
+## Configuration
+
+Install gitleaks for better detection:
+```bash
+brew install gitleaks
+```
+
+## Failure Handling
+
+| Finding | Local Behavior | CI Behavior |
+|---------|---|---|
+| Secrets found | Prompt to fix | Error - exit |
+| Pattern match | Warning shown | Error - exit |
+
+## Emergency Access
+
+If blocked:
+1. Remove secret from code
+2. Rotate the credential
+3. Commit without secret
+4. Update `.env` file
+
+## Environment Variables
+
+- `SKIP_HOOKS=true` - Skip scan
+- `VERBOSE=true` - Show all checks
+
+## Related Hooks
+
+- `dependency-audit.md` - Vulnerability scanning
+- `code-review/check-coverage.md` - Quality checks
+
+## False Positives
+
+If pattern triggers incorrectly, add to `.gitleaksignore`:
+```
+# Pattern:match_string:file.js
+```
+
+## Implementation Notes
+
+- Runs before push (not commit)
+- Multi-pass detection strategy
+- Caches results for performance
+- Integration with `.gitignore` patterns

package/hooks/test-before-finish/README.md

@@ -0,0 +1,6 @@
+# Test Before Finish Hooks
+
+Use this folder for final verification hook guidance.
+
+Hook files should define what tests run before completion and how skipped checks
+are reported.

package/hooks/test-before-finish/run-all-tests.md

@@ -0,0 +1,128 @@
+# run-all-tests Hook
+
+**Category:** test-before-finish  
+**Purpose:** Comprehensive test suite before finishing task  
+**Trigger:** Before completing a task / in CI
+
+## Description
+
+Runs complete test validation including unit, integration, E2E, linting, and type checking before marking a task as complete.
+
+## Test Suites Run
+
+| Suite | Scope | Blocking |
+|-------|-------|----------|
+| Unit tests | Individual functions/modules | Yes |
+| Integration tests | Component interactions | Yes |
+| E2E tests | Full user workflows | No |
+| Lint checks | Code quality | Yes |
+| Type checks | Type validation | Yes |
+| Coverage | Test coverage threshold | Yes |
+
+## Success Criteria
+
+✓ All unit tests pass  
+✓ All integration tests pass  
+✓ Code lint passes  
+✓ Type checks pass  
+✓ Coverage meets threshold  
+✓ E2E tests pass (optional)  
+
+## Test Runners Supported
+
+| Language | Runner |
+|----------|--------|
+| JavaScript | Jest, Mocha, Vitest |
+| Python | pytest, unittest |
+| Go | go test |
+
+## Execution Order
+
+```
+1. Unit Tests
+   ↓
+2. Integration Tests
+   ↓
+3. Linting
+   ↓
+4. Type Checking
+   ↓
+5. E2E Tests (optional)
+```
+
+## Failure Handling
+
+| Test Type | Failure Impact |
+|---|---|
+| Unit tests | Block completion |
+| Integration tests | Block completion |
+| Lint | Block completion |
+| Type checks | Block completion |
+| E2E tests | Warn but allow |
+
+## Configuration
+
+Configure in `package.json`:
+```json
+{
+  "scripts": {
+    "test": "jest",
+    "test:integration": "jest --testPathPattern=integration",
+    "test:e2e": "cypress run",
+    "lint": "eslint .",
+    "type-check": "tsc --noEmit"
+  }
+}
+```
+
+## Environment Variables
+
+- `SKIP_HOOKS=true` - Skip all tests (not recommended)
+- `CI=true` - Strict failure mode
+- `VERBOSE=true` - Show all output
+
+## Performance
+
+Typical execution times:
+- Unit tests: 5-30 seconds
+- Integration tests: 10-60 seconds
+- Linting: 2-5 seconds
+- Type checking: 1-10 seconds
+- E2E: 30-120 seconds
+
+## Failure Troubleshooting
+
+| Error | Solution |
+|---|---|
+| Test timeout | Increase timeout, optimize test |
+| Flaky tests | Add retries, fix timing issues |
+| Lint fails | Run format hook, fix manually |
+| Type errors | Update types, fix code |
+
+## Related Hooks
+
+- `pre-commit/lint.md` - Lint before commit
+- `post-task/run-tests.md` - Post-task validation
+- `code-review/check-coverage.md` - Coverage check
+
+## Best Practices
+
+✓ Run locally before pushing  
+✓ Fix issues immediately  
+✓ Keep tests fast  
+✓ Test before finishing  
+✓ Review test output  
+
+## Parallel Execution
+
+To speed up tests, run in parallel:
+```bash
+npm test -- --parallel
+```
+
+## Implementation Notes
+
+- Runs in sequence for reliability
+- Detailed error output on failure
+- Reports pass/fail per suite
+- Integration with CI/CD

package/index.js

@@ -0,0 +1,69 @@
+import { fileURLToPath } from 'url';
+import path from 'path';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+/**
+ * AI Playbook - Comprehensive resource for AI engineering
+ *
+ * Export paths to playbook components for programmatic access
+ */
+
+export const playbookPath = __dirname;
+
+export const paths = {
+  root: __dirname,
+  agents: path.join(__dirname, 'agents'),
+  commands: path.join(__dirname, 'commands'),
+  context: path.join(__dirname, 'context'),
+  hooks: path.join(__dirname, 'hooks'),
+  knowledge: path.join(__dirname, 'knowledge'),
+  patterns: path.join(__dirname, 'patterns'),
+  prompts: path.join(__dirname, 'prompts'),
+  roles: path.join(__dirname, 'roles'),
+  skills: path.join(__dirname, 'skills'),
+};
+
+export const components = {
+  agents: {
+    architect: path.join(__dirname, 'agents', 'architect'),
+    coder: path.join(__dirname, 'agents', 'coder'),
+    debugger: path.join(__dirname, 'agents', 'debugger'),
+    devops: path.join(__dirname, 'agents', 'devops'),
+    documentation: path.join(__dirname, 'agents', 'documentation'),
+    performance: path.join(__dirname, 'agents', 'performance'),
+    planner: path.join(__dirname, 'agents', 'planner'),
+    productOwner: path.join(__dirname, 'agents', 'product-owner'),
+    refactorer: path.join(__dirname, 'agents', 'refactorer'),
+    releaseManager: path.join(__dirname, 'agents', 'release-manager'),
+    researcher: path.join(__dirname, 'agents', 'researcher'),
+    reviewer: path.join(__dirname, 'agents', 'reviewer'),
+    security: path.join(__dirname, 'agents', 'security'),
+    support: path.join(__dirname, 'agents', 'support'),
+    tester: path.join(__dirname, 'agents', 'tester'),
+  },
+
+  prompts: {
+    developer: path.join(__dirname, 'prompts', 'developer'),
+    architect: path.join(__dirname, 'prompts', 'architect'),
+    reviewer: path.join(__dirname, 'prompts', 'reviewer'),
+    debugger: path.join(__dirname, 'prompts', 'debugger'),
+    productOwner: path.join(__dirname, 'prompts', 'product-owner'),
+    support: path.join(__dirname, 'prompts', 'support'),
+  },
+
+  skills: path.join(__dirname, 'skills'),
+  patterns: path.join(__dirname, 'patterns'),
+  roles: path.join(__dirname, 'roles'),
+  hooks: path.join(__dirname, 'hooks'),
+  commands: path.join(__dirname, 'commands'),
+  knowledge: path.join(__dirname, 'knowledge'),
+  context: path.join(__dirname, 'context'),
+};
+
+export default {
+  playbookPath,
+  paths,
+  components,
+};

package/knowledge/README.md

@@ -0,0 +1,33 @@
+# Knowledge
+
+This folder contains durable reference knowledge that is broader than one role,
+skill, or project. Use it when an agent needs background concepts, shared
+mental models, or reusable explanations before applying a role or skill.
+
+## How To Use
+
+1. Load the relevant role, skill, context, or project files first.
+2. Load knowledge files only when they clarify the domain or decision.
+3. Prefer the most specific project context when it conflicts with general
+   knowledge.
+4. Treat knowledge files as reference material, not mandatory workflow steps.
+
+## Current References
+
+| File | Use When |
+| --- | --- |
+| [ai-agents.md](ai-agents.md) | Designing, evaluating, or operating AI agents and agentic workflows. |
+| [decision-making.md](decision-making.md) | Choosing between options, documenting trade-offs, or making recommendations. |
+| [documentation.md](documentation.md) | Writing durable docs, READMEs, runbooks, handoffs, or knowledge-base pages. |
+| [engineering-principles.md](engineering-principles.md) | Applying broad software engineering judgment across roles and projects. |
+| [product-discovery.md](product-discovery.md) | Understanding users, shaping product bets, and validating problems. |
+| [security-privacy.md](security-privacy.md) | Considering security and privacy risks before or during implementation. |
+| [testing-quality.md](testing-quality.md) | Selecting verification depth, test types, and quality gates. |
+
+## Maintenance Rules
+
+- Keep knowledge durable and cross-project.
+- Move project-specific facts to `projects/`.
+- Move procedural role behavior to `roles/`.
+- Move executable capability guidance to `skills/`.
+- Update links when files are renamed.

package/knowledge/ai-agents.md

@@ -0,0 +1,74 @@
+# AI Agents
+
+Use this reference when designing, reviewing, or operating AI agents and
+agentic workflows.
+
+## Core Concepts
+
+| Concept | Meaning |
+| --- | --- |
+| Agent | A system that can interpret a goal, choose actions, use tools, and adapt based on results. |
+| Tool | A bounded capability the agent can call, such as file access, search, database access, or browser control. |
+| Context | Information the agent loads to make better decisions. |
+| Memory | Durable information saved across tasks. |
+| Plan | A temporary sequence of intended actions. |
+| Guardrail | A rule or check that reduces risk, misuse, or poor-quality output. |
+| Evaluation | A method for judging agent behavior against expected outcomes. |
+
+## Design Principles
+
+- Give agents clear goals, boundaries, and success criteria.
+- Keep tools narrow, observable, and auditable.
+- Prefer structured inputs and outputs for tool calls.
+- Load only the context needed for the task.
+- Make uncertainty explicit when the agent lacks evidence.
+- Design recovery paths for failed tools, missing context, and partial progress.
+- Separate reasoning about a task from irreversible external actions.
+
+## Common Agent Patterns
+
+### Planner Executor
+
+A planner breaks the work into steps and an executor completes them. Use this
+when tasks are multi-step, ambiguous, or high risk.
+
+### Researcher Synthesizer
+
+A researcher gathers evidence and a synthesizer turns it into a recommendation
+or artifact. Use this when source quality matters.
+
+### Reviewer Fixer
+
+A reviewer identifies defects and a fixer applies narrow changes. Use this when
+quality and regression risk matter.
+
+### Tool Router
+
+The agent chooses among specialized tools based on task type. Use this when a
+workflow spans files, browser actions, APIs, databases, or external services.
+
+## Failure Modes
+
+- Acting on stale or incomplete context.
+- Treating generated text as verified fact.
+- Overusing tools without a clear decision point.
+- Hiding uncertainty behind confident language.
+- Making broad changes when a narrow fix was requested.
+- Failing to preserve user changes in a shared workspace.
+- Confusing project-specific instructions with reusable guidance.
+
+## Evaluation Signals
+
+- The agent solved the requested problem.
+- Tool use was necessary, scoped, and auditable.
+- Outputs are grounded in loaded context or cited sources.
+- Risks and skipped checks are named.
+- The final artifact can be used by another person without hidden assumptions.
+
+## Human Review Triggers
+
+- Irreversible actions such as deleting data, deploying, spending money, or
+  changing production settings.
+- Security, legal, financial, or medical implications.
+- Ambiguous ownership or conflicting instructions.
+- External communication on behalf of a person or organization.

package/knowledge/decision-making.md

@@ -0,0 +1,73 @@
+# Decision Making
+
+Use this reference when comparing options, making recommendations, writing ADRs,
+or explaining trade-offs.
+
+## Decision Frame
+
+Start with four questions:
+
+1. What problem are we solving?
+2. What outcome would make the decision successful?
+3. What constraints matter most?
+4. What happens if we are wrong?
+
+## Option Quality
+
+Good options are specific enough to evaluate. Each option should include:
+
+- What changes.
+- Who owns it.
+- Expected benefit.
+- Cost and complexity.
+- Risks and mitigations.
+- Reversibility.
+- Time to learn whether it worked.
+
+## Trade-Off Dimensions
+
+| Dimension | Questions |
+| --- | --- |
+| User value | Does this improve the user workflow or outcome? |
+| Business value | Does this support a meaningful goal or metric? |
+| Complexity | Does this make the system harder to understand or operate? |
+| Cost | What are the build, run, support, and opportunity costs? |
+| Reliability | What new failure modes appear? |
+| Security | What new trust boundaries or attack surfaces appear? |
+| Privacy | What data is collected, stored, shared, or retained? |
+| Reversibility | Can we undo this safely? |
+| Team fit | Can the team build and maintain it? |
+
+## Recommendation Structure
+
+Use this shape for concise recommendations:
+
+```text
+Recommendation: Choose <option>.
+
+Why: <primary reason>.
+
+Trade-offs: <costs or rejected alternatives>.
+
+Risks: <main risks and mitigations>.
+
+Next step: <smallest concrete action>.
+```
+
+## When To Use An ADR
+
+Use an architecture decision record when a decision is:
+
+- Hard to reverse.
+- Cross-team or cross-system.
+- Likely to be questioned later.
+- Driven by non-obvious trade-offs.
+- Important for security, reliability, privacy, cost, or data design.
+
+## Decision Hygiene
+
+- State assumptions as assumptions.
+- Avoid false precision when evidence is weak.
+- Include the status quo as an option.
+- Make the owner and review date explicit.
+- Revisit decisions when constraints change.

package/knowledge/documentation.md

@@ -0,0 +1,67 @@
+# Documentation
+
+Use this reference when writing durable documentation, READMEs, runbooks,
+handoffs, design notes, and knowledge-base material.
+
+## Documentation Types
+
+| Type | Purpose |
+| --- | --- |
+| README | Help someone understand what a folder, project, role, or skill is for. |
+| Guide | Teach a repeatable workflow or concept. |
+| Runbook | Help someone operate or recover a system under real conditions. |
+| ADR | Record a decision, alternatives, and consequences. |
+| Checklist | Prevent common misses during execution or review. |
+| Template | Provide a reusable structure for future work. |
+| Handoff | Transfer current status, risks, and next steps. |
+
+## Writing Principles
+
+- Start with the reader's task.
+- Put the most important action or decision early.
+- Prefer concrete instructions over vague values.
+- Keep durable knowledge separate from one-off status.
+- Link to source files instead of duplicating large content.
+- Name unknowns and owners when information is incomplete.
+- Remove stale instructions when workflows change.
+
+## Useful README Shape
+
+```text
+# Name
+
+What this is for.
+
+## When To Use
+
+## What To Load
+
+## How It Works
+
+## Quality Gates
+
+## Related Files
+```
+
+## Useful Runbook Shape
+
+```text
+# Runbook: <System Or Incident>
+
+## Symptoms
+## Severity
+## First Checks
+## Mitigation
+## Diagnosis
+## Rollback Or Recovery
+## Escalation
+## After Action
+```
+
+## Review Checklist
+
+- The document has a clear audience and use case.
+- Instructions can be followed without hidden context.
+- Commands, paths, and owners are current.
+- Risks, assumptions, and limits are explicit.
+- Links point to files that exist.