ai-playbook 1.0.0

package/hooks/README.md

@@ -0,0 +1,326 @@
+# Hooks
+
+Automation triggers and workflows for common development scenarios.
+
+## Overview
+
+Hooks are triggered at specific points in workflows to automate checks, validations, and processes. They can:
+- Run before/after tasks or commits
+- Validate code quality
+- Execute security checks
+- Generate documentation
+- Deploy applications
+- Run tests
+
+## Hook Categories
+
+### Pre-Task Hooks
+
+Run before starting a task:
+- `validate-environment` - Check environment is ready
+- `check-branch` - Verify on correct branch
+- `fetch-latest` - Pull latest changes
+- `backup-state` - Save current state before changes
+
+### Post-Task Hooks
+
+Run after task completion:
+- `run-tests` - Validate changes work
+- `update-docs` - Update documentation
+- `commit-changes` - Auto-commit if needed
+- `notify-team` - Alert team of progress
+
+### Pre-Commit Hooks
+
+Run before committing:
+- `lint` - Check code quality
+- `format` - Auto-format code
+- `type-check` - Validate types
+- `security-scan` - Check for vulnerabilities
+
+### Code Review Hooks
+
+Run during code review:
+- `check-coverage` - Verify test coverage
+- `analyze-complexity` - Check code complexity
+- `security-review` - Security assessment
+- `performance-check` - Performance analysis
+
+### Test Hooks
+
+Run test validations:
+- `unit-tests` - Run unit tests
+- `integration-tests` - Run integration tests
+- `e2e-tests` - Run end-to-end tests
+- `coverage-report` - Generate coverage report
+
+### Deployment Hooks
+
+Run during deployment:
+- `pre-deploy-check` - Verify readiness
+- `health-check` - Verify system health
+- `smoke-tests` - Run quick tests
+- `post-deploy-notify` - Notify of deployment
+
+### Security Hooks
+
+Run security checks:
+- `dependency-audit` - Check for vulnerabilities
+- `secrets-scan` - Scan for exposed secrets
+- `sast` - Static application security testing
+- `dast` - Dynamic application security testing
+
+### Documentation Hooks
+
+Generate and update docs:
+- `update-changelog` - Update changelog
+- `generate-api-docs` - Generate API documentation
+- `update-readme` - Update README
+- `generate-diagrams` - Generate architecture diagrams
+
+### Custom Hooks
+
+Project-specific automation:
+- Define custom hooks per project
+- Extend standard hooks
+- Create domain-specific automation
+
+## Using Hooks
+
+### In Claude Code Settings
+
+Hooks are configured in `.claude/settings.json`:
+
+```json
+{
+  "hooks": {
+    "before_commit": ["lint", "type-check"],
+    "before_push": ["test", "security-scan"],
+    "after_task": ["update-docs"],
+    "on_pr_creation": ["code-review-checklist"]
+  }
+}
+```
+
+### Running Hooks Manually
+
+```bash
+# Run specific hook
+bash hooks/pre-commit/lint.sh
+
+# Run all hooks in category
+for hook in hooks/pre-commit/*.sh; do bash "$hook"; done
+```
+
+### CI/CD Integration
+
+```yaml
+# GitHub Actions example
+- name: Run pre-commit hooks
+  run: |
+    for hook in hooks/pre-commit/*.sh; do
+      bash "$hook"
+    done
+```
+
+## Hook Format
+
+Each hook follows this structure:
+
+```bash
+#!/bin/bash
+# [hook-name].sh
+# Category: [pre-task|post-task|pre-commit|etc]
+# Purpose: [what this hook does]
+# Trigger: [when this runs]
+
+set -e
+
+echo "Running [hook-name]..."
+
+# Validation
+if ! command -v [tool] &> /dev/null; then
+    echo "Error: [tool] not found"
+    exit 1
+fi
+
+# Main logic
+echo "Checking..."
+
+# Actions
+if [ problem ]; then
+    echo "Found issue..."
+    exit 1
+fi
+
+echo "✓ [hook-name] passed"
+```
+
+## Hook Best Practices
+
+**Do:**
+- ✅ Keep hooks focused on one concern
+- ✅ Make hooks idempotent (safe to run multiple times)
+- ✅ Provide clear output about what passed/failed
+- ✅ Return meaningful exit codes (0 = pass, 1 = fail)
+- ✅ Support dry-run mode
+- ✅ Document hook purpose and triggers
+- ✅ Make hooks fast (avoid slow operations)
+- ✅ Allow disabling hooks when necessary
+
+**Don't:**
+- ❌ Make hooks take too long
+- ❌ Fail silently without feedback
+- ❌ Require manual interaction
+- ❌ Hardcode paths or configuration
+- ❌ Have interdependencies between hooks
+- ❌ Modify code without permission
+
+## Common Hook Patterns
+
+### Exit Codes
+
+```bash
+# Success
+exit 0
+
+# Failure
+exit 1
+
+# Conditional based on environment
+if [ "$CI" = "true" ]; then
+    exit 1  # Strict in CI
+else
+    exit 0  # Warning only locally
+fi
+```
+
+### Dry Run Support
+
+```bash
+if [ "$DRY_RUN" = "true" ]; then
+    echo "[Would execute: command]"
+else
+    command
+fi
+```
+
+### Skip Hooks
+
+```bash
+if [ "$SKIP_HOOKS" = "true" ]; then
+    echo "Skipping hooks"
+    exit 0
+fi
+```
+
+### Environment Checks
+
+```bash
+if ! command -v tool &> /dev/null; then
+    echo "Warning: tool not found, skipping"
+    exit 0
+fi
+```
+
+## Hook Configuration
+
+### Environment Variables
+
+Standard variables hooks can use:
+
+- `CI` - Running in CI environment
+- `DRY_RUN` - Show what would execute
+- `SKIP_HOOKS` - Skip all hooks
+- `VERBOSE` - More output
+- `ENVIRONMENT` - Current environment (dev/staging/prod)
+
+### File Paths
+
+Hooks should be resilient to different working directories:
+
+```bash
+# Good: relative to hook location
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+
+# Better: use git root
+GIT_ROOT=$(git rev-parse --show-toplevel)
+cd "$GIT_ROOT"
+```
+
+## Extending Hooks
+
+### Add Hook to Category
+
+```bash
+# Create new hook
+touch hooks/[category]/[new-hook].sh
+
+# Make executable
+chmod +x hooks/[category]/[new-hook].sh
+```
+
+### Create Custom Category
+
+```bash
+# Create new category directory
+mkdir -p hooks/[custom-category]
+
+# Add hooks to new category
+touch hooks/[custom-category]/[hook].sh
+```
+
+## Troubleshooting Hooks
+
+### Hook Not Running
+
+- Check file is executable: `chmod +x hooks/[category]/[hook].sh`
+- Verify it's configured in settings.json
+- Check environment variables are set
+- Review logs for errors
+
+### Hook Too Slow
+
+- Profile hook to find bottleneck
+- Consider running only in CI
+- Cache expensive operations
+- Split into smaller hooks
+
+### Hook Breaking Workflow
+
+- Add `SKIP_HOOKS=true` to bypass
+- Debug with `VERBOSE=true`
+- Check for hook dependencies
+- Review recent changes to hook
+
+## Hook Integration Examples
+
+### Complete Workflow
+
+```bash
+# Pre-task
+hooks/pre-task/validate-environment.sh
+hooks/pre-task/check-branch.sh
+
+# Development
+# [work on code]
+
+# Pre-commit
+hooks/pre-commit/lint.sh
+hooks/pre-commit/type-check.sh
+hooks/pre-commit/format.sh
+
+# Push
+# [git push]
+
+# CI/CD
+# runs all test hooks
+# runs security hooks
+# runs deployment hooks
+```
+
+## Version
+
+**Version:** 1.0
+
+Hooks provide flexible automation at key workflow points. Customize per project and team.

package/hooks/code-review/README.md

@@ -0,0 +1,6 @@
+# Code Review Hooks
+
+Use this folder for hook guidance that runs around code review.
+
+Hook files should describe trigger, command or check, expected output, and
+failure handling.

package/hooks/code-review/check-coverage.md

@@ -0,0 +1,101 @@
+# check-coverage Hook
+
+**Category:** code-review  
+**Purpose:** Verify test coverage meets minimum threshold  
+**Trigger:** During code review / in CI
+
+## Description
+
+Validates that code changes are covered by tests and meet the project's minimum coverage threshold.
+
+## Coverage Metrics Checked
+
+- **Line coverage** - Percentage of code lines executed by tests
+- **Branch coverage** - Percentage of conditional branches tested
+- **Function coverage** - Percentage of functions called by tests
+- **Statement coverage** - Percentage of statements executed
+
+## Default Threshold
+
+- **Minimum:** 80% line coverage
+- **Can be configured** in `package.json` or environment
+
+## Supported Tools
+
+| Language | Tool |
+|----------|------|
+| JavaScript/TypeScript | Istanbul/nyc, Jest coverage |
+| Python | coverage.py |
+| Go | go coverage |
+
+## Success Criteria
+
+✓ Coverage >= configured minimum  
+✓ No significant drops from main  
+✓ New code has tests  
+
+## Configuration
+
+Set threshold in `package.json`:
+```json
+{
+  "jest": {
+    "coverageThreshold": {
+      "global": {
+        "lines": 80,
+        "functions": 80,
+        "branches": 75
+      }
+    }
+  }
+}
+```
+
+## Environment Variables
+
+- `MIN_COVERAGE=90` - Override threshold
+- `SKIP_HOOKS=true` - Skip check
+- `CI=true` - Strict mode
+
+## Failure Handling
+
+| Scenario | Local | CI |
+|---|---|---|
+| Below threshold | Warning | Error |
+| Coverage drops | Warning | Error |
+| No test changes | Prompt | Error |
+
+## Coverage Reports
+
+View detailed reports:
+```bash
+npm run test:coverage
+open coverage/lcov-report/index.html
+```
+
+## How to Improve Coverage
+
+1. Add tests for uncovered code
+2. Write integration tests
+3. Test error scenarios
+4. Test edge cases
+
+## Related Hooks
+
+- `post-task/run-tests.md` - Run tests
+- `test-before-finish/run-all-tests.md` - Comprehensive tests
+
+## Common Issues
+
+| Issue | Solution |
+|---|---|
+| Coverage drops | Add tests for new code |
+| Excluded files hurt coverage | Adjust coverage config |
+| Unrealistic threshold | Adjust to project needs |
+
+## Implementation Notes
+
+- Generated from test runs
+- HTML reports available
+- Badge-friendly output
+- CI/CD integration ready

package/hooks/custom/README.md

@@ -0,0 +1,6 @@
+# Custom Hooks
+
+Use this folder for project-specific hook guidance.
+
+Document when custom hooks run, what they may change, and how to disable or
+debug them safely.

package/hooks/custom/project-specific-hooks.md

@@ -0,0 +1,273 @@
+# Project-Specific Hooks
+
+**Category:** custom  
+**Purpose:** Define domain or project-specific automation  
+**Trigger:** Custom (project-defined)
+
+## Overview
+
+Custom hooks allow teams to extend the standard hook system with checks, validations, and automations specific to their project or domain.
+
+## Creating Custom Hooks
+
+### 1. Define Hook Purpose
+
+Create a .md file describing what the hook does:
+
+```markdown
+# hook-name Hook
+
+**Category:** custom  
+**Purpose:** [What this validates]  
+**Trigger:** [When it runs]
+
+## Description
+...
+```
+
+### 2. Document Success Criteria
+
+What must pass for the hook to succeed?
+
+### 3. Define Configuration
+
+How is the hook configured for your project?
+
+### 4. Document Failure Handling
+
+What happens if the hook fails?
+
+## Common Custom Hooks
+
+### 1. Commit Message Format
+
+Validates commit messages follow conventional format:
+
+```
+feat(feature): description
+fix(bug): description
+docs: documentation
+refactor: code cleanup
+```
+
+**Trigger:** Before commit  
+**Tools:** commitlint, husky
+
+### 2. Branch Naming
+
+Validates branch names follow convention:
+
+```
+feature/short-description
+bugfix/issue-123
+hotfix/description
+release/1.2.3
+```
+
+**Trigger:** Before push  
+**Tools:** Custom regex validation
+
+### 3. File Size Limits
+
+Prevents large files from being committed:
+
+**Trigger:** Before commit  
+**Limits:** 
+- Images: < 2MB
+- Videos: < 50MB
+- Documents: < 10MB
+
+### 4. API Contract Validation
+
+Validates API changes match contract:
+
+**Trigger:** Before commit (API files)  
+**Checks:**
+- Breaking changes documented
+- Examples updated
+- Schema validation
+- Backward compatibility
+
+### 5. Database Schema
+
+Validates database schema changes:
+
+**Trigger:** Before commit (migration files)  
+**Checks:**
+- Migration is reversible
+- Data loss prevented
+- Indexes defined
+- Foreign keys valid
+
+### 6. Configuration Validation
+
+Validates config files are correct:
+
+**Trigger:** Before commit  
+**Checks:**
+- Valid JSON/YAML syntax
+- Required fields present
+- No hardcoded secrets
+- Values in valid range
+
+### 7. Dependency License Check
+
+Validates dependencies have compatible licenses:
+
+**Trigger:** After `npm install`  
+**Checks:**
+- No GPL in non-GPL project
+- License compliance
+- Restriction tracking
+
+### 8. Code Architecture
+
+Validates code follows architecture patterns:
+
+**Trigger:** Before commit  
+**Checks:**
+- Import paths follow conventions
+- Circular dependencies prevented
+- Layer violations caught
+- Module organization validated
+
+## Template
+
+```markdown
+# [hook-name] Hook
+
+**Category:** custom  
+**Purpose:** [What this checks]  
+**Trigger:** [When this runs]
+
+## Description
+[What the hook does]
+
+## Checks Performed
+- Check 1
+- Check 2
+- Check 3
+
+## Success Criteria
+✓ Criteria 1  
+✓ Criteria 2  
+✓ Criteria 3  
+
+## Failure Handling
+| Scenario | Behavior |
+|----------|----------|
+| Failure 1 | Action |
+| Failure 2 | Action |
+
+## Configuration
+[How to configure]
+
+## Examples
+[Example scenarios]
+
+## Related Hooks
+- Hook A
+- Hook B
+
+## Implementation Notes
+- Note 1
+- Note 2
+```
+
+## Implementation Strategies
+
+### Shell Script (Simple)
+```bash
+#!/bin/bash
+# Check condition
+if [ condition ]; then
+    echo "✓ Check passed"
+else
+    echo "❌ Check failed"
+    exit 1
+fi
+```
+
+### npm Package (JavaScript)
+```javascript
+module.exports = {
+    name: 'hook-name',
+    check: async () => {
+        // validation logic
+        return { passed: true, message: 'Check passed' }
+    }
+}
+```
+
+### GitHub Actions (CI/CD)
+```yaml
+- name: Custom Check
+  run: npm run custom:check
+```
+
+## Best Practices
+
+✓ **Single responsibility** - Each hook does one thing  
+✓ **Clear feedback** - Tell users why they failed  
+✓ **Fast execution** - Hooks should complete in seconds  
+✓ **Idempotent** - Safe to run multiple times  
+✓ **Documented** - Clear README explaining behavior  
+✓ **Configurable** - Allow teams to tune behavior  
+✓ **Graceful failure** - Good error messages  
+
+## Integration
+
+### With Husky
+
+```bash
+# Create hook
+npx husky add .husky/commit-msg 'npm run custom:check'
+```
+
+### With GitHub Actions
+
+```yaml
+- name: Custom checks
+  run: |
+    for hook in hooks/custom/*.sh; do
+      bash "$hook"
+    done
+```
+
+## Maintenance
+
+- Review hooks quarterly
+- Update for new dependencies
+- Remove unused hooks
+- Document changes
+- Test in CI environment
+
+## Examples by Domain
+
+**E-commerce:**
+- Product data validation
+- Price calculation accuracy
+- Inventory constraints
+
+**Healthcare:**
+- HIPAA compliance checks
+- Data privacy validation
+- Audit logging
+
+**Finance:**
+- Transaction validation
+- Regulatory compliance
+- Data accuracy
+
+**SaaS:**
+- Multi-tenant isolation
+- API rate limiting config
+- Security policies
+
+## Support
+
+For help creating custom hooks:
+- Review existing hooks in `hooks/` directory
+- Consult team documentation
+- Check integration examples
+- Run in dry-run mode first

package/hooks/deployment/README.md

@@ -0,0 +1,6 @@
+# Deployment Hooks
+
+Use this folder for deployment hook guidance.
+
+Hook files should cover readiness, health checks, rollback signals, and
+post-deployment verification.