ai-playbook 1.0.0

package/hooks/deployment/health-check.md

@@ -0,0 +1,102 @@
+# health-check Hook
+
+**Category:** deployment  
+**Purpose:** Verify system health after deployment  
+**Trigger:** After deployment
+
+## Description
+
+Validates that the deployed system is healthy and responding correctly after deployment completes.
+
+## Health Checks Performed
+
+- **Service availability** - Can reach health endpoint
+- **Status response** - Returns 200/ok status
+- **Dependencies** - Database, cache, external services
+- **Response time** - Performance within acceptable range
+
+## Success Criteria
+
+✓ Health endpoint responds with 200 OK  
+✓ Status includes "healthy" or "ok"  
+✓ Response time < 2 seconds  
+✓ All dependencies healthy  
+
+## Configuration
+
+Set health check URL:
+```bash
+export HEALTH_CHECK_URL="https://api.example.com/health"
+```
+
+## Retry Behavior
+
+| Parameter | Default | Purpose |
+|---|---|---|
+| `MAX_RETRIES` | 10 | Max attempts |
+| `RETRY_DELAY` | 5s | Wait between retries |
+
+## Typical Health Check Response
+
+```json
+{
+  "status": "ok",
+  "uptime": 3600,
+  "version": "1.2.3",
+  "dependencies": {
+    "database": "ok",
+    "cache": "ok",
+    "api": "ok"
+  }
+}
+```
+
+## Failure Handling
+
+| Scenario | Local | CI |
+|---|---|---|
+| Service down | Prompt to rollback | Auto-rollback |
+| Slow response | Warning | Continue checking |
+| Dependency issue | Alert on dashboard | Notify team |
+
+## Environment Variables
+
+- `HEALTH_CHECK_URL` - Endpoint to check
+- `MAX_RETRIES` - Number of attempts (default: 10)
+- `RETRY_DELAY` - Seconds between retries (default: 5)
+- `SKIP_HOOKS=true` - Skip check
+
+## Related Hooks
+
+- `pre-deploy-check.md` - Pre-deployment validation
+- `commands/rollback.sh` - Emergency rollback
+
+## Metrics Monitored
+
+- **Availability** - Can reach endpoint
+- **Latency** - Response time in ms
+- **Error rate** - 5xx responses
+- **Throughput** - Requests/sec
+
+## Common Issues
+
+| Issue | Solution |
+|---|---|
+| Slow startup | Increase `RETRY_DELAY` |
+| Connection refused | Check network, endpoints |
+| Unhealthy dependency | Investigate and fix |
+| False positives | Adjust timeout values |
+
+## Integration
+
+- Slack notifications on failure
+- PagerDuty alerts
+- Datadog monitoring
+- CloudWatch dashboards
+
+## Implementation Notes
+
+- Runs immediately post-deployment
+- Blocks user access until healthy
+- Automatic rollback if fails
+- Integrates with monitoring systems

package/hooks/deployment/pre-deploy-check.md

@@ -0,0 +1,84 @@
+# pre-deploy-check Hook
+
+**Category:** deployment  
+**Purpose:** Verify system is ready before deployment  
+**Trigger:** Before deployment
+
+## Description
+
+Validates that all prerequisites are met before attempting to deploy code to any environment.
+
+## Pre-deployment Checks
+
+- **Environment variables** - All required config present
+- **Database connectivity** - Can connect to database
+- **Migrations pending** - Database schema is current
+- **Build artifacts** - Build is recent and present
+- **Git status** - Working directory clean
+
+## Configuration Verification
+
+Checks for required environment variables per environment:
+
+**Production:**
+- `DATABASE_URL` ✓
+- `API_KEY` ✓
+- `SLACK_WEBHOOK` ✓
+
+**Staging:**
+- `DATABASE_URL` ✓
+- `API_KEY` ✓
+
+## Success Criteria
+
+✓ All required variables configured  
+✓ Database is reachable  
+✓ Migrations up to date  
+✓ Build artifacts are recent  
+✓ Git working directory clean  
+
+## Failure Handling
+
+| Check | Failure Behavior |
+|---|---|
+| Missing variable | Block deployment |
+| DB unreachable | Warning (may recover) |
+| Stale build | Prompt to rebuild |
+| Uncommitted changes | Block deployment |
+| Pending migrations | Warn, allow override |
+
+## Environment Variables
+
+- `ENVIRONMENT=staging|production` - Target environment
+- `SKIP_HOOKS=true` - Skip checks (not recommended)
+
+## Related Hooks
+
+- `health-check.md` - Verify health post-deploy
+- `commands/validate.sh` - General validation
+
+## Common Issues
+
+| Issue | Solution |
+|---|---|
+| Missing env var | Add to `.env` / secrets manager |
+| DB won't connect | Verify credentials, network |
+| Stale build | Run build before deploy |
+| Uncommitted changes | Commit or stash changes |
+
+## Safe Deployment Workflow
+
+1. Create release branch
+2. Run tests (all passing)
+3. Build artifacts
+4. Run pre-deploy-check
+5. Deploy to staging
+6. Verify staging
+7. Deploy to production
+
+## Implementation Notes
+
+- Non-blocking warnings for recovery scenarios
+- Specific error messages for each failure
+- Environment-aware configuration
+- Integration with CI/CD pipelines

package/hooks/documentation/README.md

@@ -0,0 +1,6 @@
+# Documentation Hooks
+
+Use this folder for documentation hook guidance.
+
+Hook files should explain what documentation is updated, when it runs, and how
+to verify the result.

package/hooks/documentation/update-changelog.md

@@ -0,0 +1,146 @@
+# update-changelog Hook
+
+**Category:** documentation  
+**Purpose:** Auto-generate changelog from commits  
+**Trigger:** During release process
+
+## Description
+
+Automatically generates or updates CHANGELOG.md based on commit history using conventional commit format.
+
+## Changelog Format
+
+Follows [Keep a Changelog](https://keepachangelog.com/) and [Semantic Versioning](https://semver.org/):
+
+```markdown
+## [1.2.3] - 2024-01-15
+
+### Added
+- New feature description
+
+### Changed
+- Behavior change description
+
+### Fixed
+- Bug fix description
+
+### Deprecated
+- Deprecated feature description
+
+### Removed
+- Removed feature description
+
+### Security
+- Security fix description
+```
+
+## Commit Format (Conventional Commits)
+
+```
+type(scope): subject
+
+body
+
+footer
+```
+
+**Types:**
+- `feat` → Added
+- `fix` → Fixed
+- `refactor` → Changed
+- `perf` → Changed
+- `docs` → Documentation
+- `test` → Testing
+
+## Tools Supported
+
+| Tool | Command |
+|------|---------|
+| conventional-changelog | `conventional-changelog` |
+| git-changelog | `git-changelog` |
+| Manual | Edit CHANGELOG.md directly |
+
+## Installation
+
+```bash
+npm install -D conventional-changelog-cli
+```
+
+## Success Criteria
+
+✓ CHANGELOG.md updated  
+✓ Version bumped correctly  
+✓ All changes documented  
+✓ Changelog staged for commit  
+
+## Configuration
+
+Create `.changelogrc.json`:
+```json
+{
+  "preset": "angular",
+  "skipCommit": false
+}
+```
+
+## Commit Examples
+
+✓ **Good:**
+```
+feat(api): add authentication endpoint
+fix(database): resolve connection pool leak
+docs: update README with examples
+```
+
+✗ **Bad:**
+```
+Update stuff
+Fixed things
+Work in progress
+```
+
+## Generated Sections
+
+| Section | Trigger |
+|---------|---------|
+| Added | `feat:` commits |
+| Changed | `refactor:`, `perf:` commits |
+| Fixed | `fix:` commits |
+| Deprecated | Footer `DEPRECATED:` |
+| Removed | Footer `BREAKING CHANGE:` |
+| Security | `security:` commits |
+
+## Related Hooks
+
+- `commands/release.sh` - Release automation
+- `post-task/run-tests.md` - Validate changes
+
+## Common Issues
+
+| Issue | Solution |
+|---|---|
+| No changes detected | Check commit format |
+| Wrong version bump | Update version manually |
+| Incomplete changelog | Add missing commits |
+
+## Manual Editing
+
+If auto-generation doesn't capture everything:
+1. Generate base changelog
+2. Edit sections manually
+3. Add missing changes
+4. Commit updates
+
+## Integration
+
+- Auto-commit CHANGELOG.md in release
+- Include in version tag
+- GitHub release notes from CHANGELOG
+- NPM package README
+
+## Implementation Notes
+
+- Runs during release process
+- Reads commit history
+- Parses conventional commits
+- Generates formatted sections

package/hooks/post-task/README.md

@@ -0,0 +1,5 @@
+# Post Task Hooks
+
+Use this folder for hooks that run after task completion.
+
+Hook files should cover validation, cleanup, summaries, and final quality gates.

package/hooks/post-task/run-tests.md

@@ -0,0 +1,61 @@
+# run-tests Hook
+
+**Category:** post-task  
+**Purpose:** Run tests after task completion to validate changes  
+**Trigger:** After completing a task
+
+## Description
+
+Automatically runs test suite after task completion to verify changes work correctly.
+
+## Tests Run
+
+- Unit tests (if configured)
+- Integration tests (if separate)
+- Coverage reporting (if configured)
+
+## Success Criteria
+
+✓ All tests pass  
+✓ Coverage meets threshold (if configured)  
+✓ No test regressions  
+
+## Test Runners Supported
+
+- npm test
+- pytest
+- go test
+- Custom test scripts
+
+## Failure Handling
+
+| Environment | Failure Behavior |
+|---|---|
+| Local dev | Warning, continue allowed |
+| CI | Error - exit with failure |
+
+## Configuration
+
+No configuration needed. Auto-detects test framework from:
+- `package.json` (npm)
+- `pytest.ini` (Python)
+- `go.mod` (Go)
+- `Makefile`
+
+## Environment Variables
+
+- `SKIP_HOOKS=true` - Skip tests
+- `CI=true` - Strict failure mode
+- `COVERAGE=true` - Include coverage report
+
+## Related Hooks
+
+- `test-before-finish/run-all-tests.md` - Comprehensive suite before finishing
+- `pre-commit/lint.md` - Lint before commit
+
+## Implementation Notes
+
+- Runs silently if no tests found
+- Caches test results for performance
+- Shows last 20 lines of output on failure
+- Supports parallel test execution

package/hooks/pre-commit/README.md

@@ -0,0 +1,6 @@
+# Pre Commit Hooks
+
+Use this folder for pre-commit hook guidance.
+
+Hook files should document formatting, linting, type checks, security checks, and
+how failures should be fixed.

package/hooks/pre-commit/format.md

@@ -0,0 +1,63 @@
+# format Hook
+
+**Category:** pre-commit  
+**Purpose:** Auto-format code to project standards before commit  
+**Trigger:** Before git commit
+
+## Description
+
+Automatically formats staged code files to ensure consistent style across the project.
+
+## Formatters Supported
+
+| Language | Tool |
+|----------|------|
+| JavaScript/TypeScript/JSON/Markdown | Prettier |
+| Python | Black, autopep8 |
+| Go | gofmt |
+| Terraform | terraform fmt |
+| YAML | yamlfmt |
+
+## Behavior
+
+1. Format staged files
+2. Re-stage formatted files
+3. Allow commit to proceed
+
+## Configuration
+
+- `.prettierrc` - Prettier config
+- `pyproject.toml` - Black config
+- `.editorconfig` - General formatting
+
+## Success Criteria
+
+✓ All staged files formatted  
+✓ Consistent with project style  
+✓ Changes re-staged automatically  
+
+## Environment Variables
+
+- `SKIP_HOOKS=true` - Skip formatting
+- `DRY_RUN=true` - Show what would format
+
+## Related Hooks
+
+- `lint.md` - Check code quality
+- `type-check.md` - Type validation
+
+## Common Scenarios
+
+| Scenario | Behavior |
+|----------|----------|
+| Prettier installed | Format JS/TS/JSON/MD |
+| Black installed | Format Python |
+| Both installed | Format all languages |
+| No formatters | Skip silently |
+
+## Implementation Notes
+
+- Modifies staged files in-place
+- Re-stages formatted changes
+- Formatters run in parallel
+- Non-blocking if formatter not installed

package/hooks/pre-commit/lint.md

@@ -0,0 +1,62 @@
+# lint Hook
+
+**Category:** pre-commit  
+**Purpose:** Check code quality before committing  
+**Trigger:** Before git commit
+
+## Description
+
+Runs linters on staged files to ensure code meets project quality standards.
+
+## Linters Supported
+
+| Language | Tools |
+|----------|-------|
+| JavaScript/TypeScript | ESLint |
+| Python | Pylint, Flake8 |
+| Go | golint, go vet |
+| Bash | shellcheck |
+
+## Success Criteria
+
+✓ No lint errors in staged files  
+✓ All configured rules pass  
+✓ Code style consistent  
+
+## What Gets Checked
+
+- Code style violations
+- Unused variables
+- Missing imports
+- Syntax errors
+- Best practice violations
+
+## Configuration
+
+Add `.eslintrc.json`, `.pylintrc`, `.golangci.yml` to project root for custom rules.
+
+## Environment Variables
+
+- `SKIP_HOOKS=true` - Skip linting
+- `VERBOSE=true` - Show all output
+
+## Failure Handling
+
+Linting failures prevent commit. Options:
+
+1. Fix issues manually
+2. Auto-fix with `format.md` hook
+3. Override with `SKIP_HOOKS=true` (not recommended)
+
+## Related Hooks
+
+- `format.md` - Auto-format code
+- `type-check.md` - Type validation
+- `test-before-finish/run-all-tests.md` - Full validation
+
+## Implementation Notes
+
+- Only checks staged files (changed content)
+- Multiple linters run in parallel
+- Fails fast on first error
+- Caches linter config for performance

package/hooks/pre-commit/type-check.md

@@ -0,0 +1,78 @@
+# type-check Hook
+
+**Category:** pre-commit  
+**Purpose:** Run type checker before committing  
+**Trigger:** Before git commit
+
+## Description
+
+Validates type annotations and catches type errors before code is committed.
+
+## Type Checkers Supported
+
+| Language | Tool |
+|----------|------|
+| TypeScript | tsc (TypeScript Compiler) |
+| JavaScript | Flow |
+| Python | MyPy |
+| Go | go vet |
+
+## Success Criteria
+
+✓ No type errors  
+✓ All type annotations valid  
+✓ Type compatibility verified  
+
+## What Gets Checked
+
+- Variable type mismatches
+- Function argument types
+- Return type compatibility
+- Type annotation syntax
+- Generic type constraints
+
+## Configuration
+
+- `tsconfig.json` - TypeScript config
+- `.flowconfig` - Flow config
+- `mypy.ini` - MyPy config
+
+## Failure Handling
+
+Type check failures prevent commit. Options:
+
+1. Fix type errors
+2. Update type annotations
+3. Skip with `SKIP_HOOKS=true` (not recommended)
+
+## Environment Variables
+
+- `SKIP_HOOKS=true` - Skip type check
+- `VERBOSE=true` - Show detailed errors
+
+## Related Hooks
+
+- `lint.md` - Code quality
+- `format.md` - Code formatting
+- `test-before-finish/run-all-tests.md` - Full validation
+
+## Performance
+
+- TypeScript: ~1-5s (depends on project size)
+- Flow: ~1-3s
+- MyPy: ~2-10s (depends on type coverage)
+
+## Common Issues
+
+| Issue | Solution |
+|-------|----------|
+| Type errors on valid code | Update .strict mode gradually |
+| Slow type checking | Enable incremental mode |
+| Missing type definitions | Install @types packages |
+
+## Implementation Notes
+
+- Runs after format/lint hooks
+- Type errors are always blocking
+- Caches type information
+- Supports incremental checking

package/hooks/pre-task/README.md

@@ -0,0 +1,6 @@
+# Pre Task Hooks
+
+Use this folder for hooks that run before task work begins.
+
+Hook files should validate environment, branch, dependencies, permissions, and
+other task prerequisites.

package/hooks/pre-task/check-branch.md

@@ -0,0 +1,48 @@
+# check-branch Hook
+
+**Category:** pre-task  
+**Purpose:** Verify on correct branch before starting work  
+**Trigger:** Before starting a new task
+
+## Description
+
+Validates that you're on an appropriate branch for making changes and that your local branch is up to date with remote.
+
+## Checks Performed
+
+- Current branch is not main/master (or warns if it is)
+- Local branch is up to date with remote
+- Offers to pull latest changes if behind
+
+## Success Criteria
+
+✓ On feature/development branch  
+✓ Branch is up to date with remote  
+✓ No merge conflicts or divergence  
+
+## Failure Handling
+
+| Scenario | Local Behavior | CI Behavior |
+|----------|---|---|
+| On main/master | Warning, optional pull | Error - exit |
+| Behind remote | Prompt to pull | Skip (requires manual) |
+
+## Configuration
+
+No configuration needed. Detects main/master/develop branches automatically.
+
+## Environment Variables
+
+- `SKIP_HOOKS=true` - Skip all validation
+- `CI=true` - Running in CI (stricter checks)
+
+## Related Hooks
+
+- `validate-environment.md` - Check tools/deps (runs before this)
+
+## Implementation Notes
+
+- Fetches from remote to check status
+- Non-blocking warnings in local dev
+- Strict checks in CI environment
+- Handles both 'main' and 'master' conventions