@codeharbor/agent-playbook 0.1.0 → 0.1.2

package/skills/debugger/SKILL.md

@@ -0,0 +1,239 @@
+---
+name: debugger
+description: Advanced debugging specialist for diagnosing and resolving code issues. Use when user encounters bugs, errors, unexpected behavior, or mentions debugging.
+allowed-tools: Read, Write, Edit, Bash, Grep, Glob
+---
+
+# Debugger
+
+An advanced debugging specialist that helps diagnose and resolve code issues systematically.
+
+## When This Skill Activates
+
+Activates when you:
+- Report an error or bug
+- Mention "debug this" or "help debug"
+- Describe unexpected behavior
+- Ask why something isn't working
+
+## Debugging Process
+
+### Phase 1: Understand the Problem
+
+1. **Reproduce the issue**
+   - What are the exact steps to reproduce?
+   - What is the expected behavior?
+   - What is the actual behavior?
+   - What error messages appear?
+
+2. **Gather context**
+   ```bash
+   # Check recent changes
+   git log --oneline -10
+
+   # Check error logs
+   tail -f logs/error.log
+
+   # Check environment
+   env | grep -i debug
+   ```
+
+### Phase 2: Isolate the Issue
+
+1. **Locate the error source**
+   - Stack trace analysis
+   - Error code lookup
+   - Log correlation
+
+2. **Narrow down scope**
+   - Binary search (comment out half)
+   - Minimize reproduction case
+   - Identify affected components
+
+### Phase 3: Analyze the Root Cause
+
+#### Common Error Categories
+
+| Category | Symptoms | Investigation Steps |
+|----------|----------|---------------------|
+| **Null/Undefined** | "Cannot read X of undefined" | Trace the variable origin |
+| **Type Errors** | "X is not a function" | Check actual vs expected type |
+| **Async Issues** | Race conditions, timing | Check promise handling, async/await |
+| **State Issues** | Stale data, wrong state | Trace state mutations |
+| **Network** | Timeouts, connection refused | Check endpoints, CORS, auth |
+| **Environment** | Works locally, not in prod | Compare env vars, versions |
+| **Memory** | Leaks, OOM | Profile memory usage |
+| **Concurrency** | Deadlocks, race conditions | Check locks, shared state |
+
+### Phase 4: Form Hypotheses
+
+For each potential cause:
+1. Form a hypothesis
+2. Create a test to validate
+3. Run the test
+4. Confirm or reject
+
+### Phase 5: Fix and Verify
+
+1. **Implement the fix**
+2. **Add logging if needed**
+3. **Test the fix**
+4. **Add regression test**
+
+## Debugging Commands
+
+### General Debugging
+
+```bash
+# Find recently modified files
+find . -type f -mtime -1 -name "*.js" -o -name "*.ts" -o -name "*.py"
+
+# Grep for error patterns
+grep -r "ERROR\|FATAL\|Exception" logs/
+
+# Search for suspicious patterns
+grep -r "TODO\|FIXME\|XXX" src/
+
+# Check for console.log left in code
+grep -r "console\.log\|debugger" src/
+```
+
+### Language-Specific
+
+**JavaScript/TypeScript:**
+```bash
+# Run with debug output
+NODE_DEBUG=* node app.js
+
+# Check syntax
+node -c file.js
+
+# Run tests in debug mode
+npm test -- --inspect-brk
+```
+
+**Python:**
+```bash
+# Run with pdb
+python -m pdb script.py
+
+# Check syntax
+python -m py_compile script.py
+
+# Verbose mode
+python -v script.py
+```
+
+**Go:**
+```bash
+# Race detection
+go run -race main.go
+
+# Debug build
+go build -gcflags="-N -l"
+
+# Profile
+go test -cpuprofile=cpu.prof
+```
+
+## Common Debugging Patterns
+
+### Pattern 1: Divide and Conquer
+
+```python
+# When you don't know where the bug is:
+def process():
+    step1()
+    step2()
+    step3()
+    step4()
+
+# Comment out half:
+def process():
+    step1()
+    # step2()
+    # step3()
+    # step4()
+
+# If bug disappears, uncomment half of commented:
+def process():
+    step1()
+    step2()
+    # step3()
+    # step4()
+
+# Continue until you isolate the bug
+```
+
+### Pattern 2: Add Logging
+
+```typescript
+// Before (mysterious failure):
+async function getUser(id: string) {
+  const user = await db.find(id);
+  return transform(user);
+}
+
+// After (with logging):
+async function getUser(id: string) {
+  console.log('[DEBUG] getUser called with id:', id);
+  const user = await db.find(id);
+  console.log('[DEBUG] db.find returned:', user);
+  const result = transform(user);
+  console.log('[DEBUG] transform returned:', result);
+  return result;
+}
+```
+
+### Pattern 3: Minimal Reproduction
+
+```typescript
+// Complex code with bug:
+function processBatch(items, options) {
+  // 100 lines of complex logic
+}
+
+// Create minimal reproduction:
+function processBatch(items, options) {
+  console.log('Items:', items.length);
+  console.log('Options:', options);
+  // Test with minimal data
+  return processBatch([items[0]], options);
+}
+```
+
+## Error Message Analysis
+
+### Common Error Messages
+
+| Error | Likely Cause | Solution |
+|-------|--------------|----------|
+| `Cannot read property 'X' of undefined` | Accessing property on null/undefined | Add null check, use optional chaining |
+| `X is not a function` | Wrong type, shadowing | Check typeof, verify import |
+| `Unexpected token` | Syntax error | Check line before error, validate syntax |
+| `Module not found` | Import path wrong | Check relative path, verify file exists |
+| `EADDRINUSE` | Port already in use | Kill existing process, use different port |
+| `Connection refused` | Service not running | Start service, check port |
+| `Timeout` | Request too slow | Increase timeout, check network |
+
+## Debugging Checklist
+
+- [ ] I can reproduce the issue consistently
+- [ ] I have identified the exact error location
+- [ ] I understand the root cause
+- [ ] I have a proposed fix
+- [ ] The fix doesn't break existing functionality
+- [ ] I've added a test to prevent regression
+
+## Scripts
+
+Generate a debug report:
+```bash
+python scripts/debug_report.py <error-message>
+```
+
+## References
+
+- `references/checklist.md` - Debugging checklist
+- `references/patterns.md` - Common debugging patterns
+- `references/errors.md` - Error message reference

package/skills/debugger/references/checklist.md

@@ -0,0 +1,7 @@
+# Debugging Checklist
+
+- [ ] Reproduce the issue
+- [ ] Isolate the failure
+- [ ] Identify root cause
+- [ ] Implement fix
+- [ ] Add regression coverage

package/skills/debugger/references/errors.md

@@ -0,0 +1,6 @@
+# Common Error Types
+
+- Null/undefined access
+- Race conditions
+- Configuration mismatches
+- Data shape drift

package/skills/debugger/references/patterns.md

@@ -0,0 +1,5 @@
+# Debugging Patterns
+
+- Binary search the change set
+- Add targeted logging
+- Reduce problem scope with minimal repros

package/skills/debugger/scripts/debug_report.py

@@ -0,0 +1,77 @@
+#!/usr/bin/env python3
+# Template generator for debug report.
+
+from pathlib import Path
+import argparse
+import textwrap
+
+
+def write_output(path: Path, content: str, force: bool) -> bool:
+    if path.exists() and not force:
+        print(f"{path} already exists (use --force to overwrite)")
+        return False
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(content, encoding="utf-8")
+    return True
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description="Generate a debug report.")
+    parser.add_argument("--output", default="debug-report.md", help="Output file path")
+    parser.add_argument("--name", default="example", help="Issue summary")
+    parser.add_argument("--owner", default="team", help="Owning team")
+    parser.add_argument("--force", action="store_true", help="Overwrite existing file")
+    args = parser.parse_args()
+
+    content = textwrap.dedent(
+        f"""\
+        # Debug Report
+
+        ## Summary
+        {args.name}
+
+        ## Ownership
+        - Owner: {args.owner}
+        - On-call: TBD
+
+        ## Environment
+        - Service version:
+        - Region:
+        - Traffic level:
+
+        ## Steps to Reproduce
+        1. Step one
+        2. Step two
+
+        ## Expected vs Actual
+        - Expected:
+        - Actual:
+
+        ## Logs and Evidence
+        - Attach logs, screenshots, traces
+
+        ## Root Cause
+        TBD
+
+        ## Fix
+        - Code changes
+        - Configuration changes
+
+        ## Regression Tests
+        - Add or update tests
+
+        ## Follow-ups
+        - Monitoring improvements
+        - Runbook updates
+        """
+    ).strip() + "\n"
+
+    output = Path(args.output)
+    if not write_output(output, content, args.force):
+        return 1
+    print(f"Wrote {output}")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/skills/deployment-engineer/README.md

@@ -0,0 +1,40 @@
+# Deployment Engineer
+
+> A Claude Code skill for CI/CD pipelines and deployment automation.
+
+## Installation
+
+This skill is part of the [agent-playbook](https://github.com/Charon-Fan/agent-playbook) collection.
+
+## Usage
+
+```
+You: Set up CI/CD
+You: Create deployment pipeline
+You: Configure GitHub Actions
+```
+
+## Deployment Strategies
+
+| Strategy | Description |
+|----------|-------------|
+| **Blue-Green** | Zero downtime, instant rollback |
+| **Rolling** | Gradual replacement |
+| **Canary** | Test with small traffic first |
+
+## Scripts
+
+Generate deployment config:
+```bash
+python scripts/generate_deploy.py <environment>
+```
+
+Validate deployment:
+```bash
+python scripts/validate_deploy.py
+```
+
+## Resources
+
+- [GitHub Actions Docs](https://docs.github.com/en/actions)
+- [CI/CD Best Practices](https://www.atlassian.com/continuous-delivery/principles/continuous-integration-vs-delivery-vs-deployment)

package/skills/deployment-engineer/SKILL.md

@@ -0,0 +1,242 @@
+---
+name: deployment-engineer
+description: Deployment automation specialist for CI/CD pipelines and infrastructure. Use when setting up deployment, configuring CI/CD, or managing releases.
+allowed-tools: Read, Write, Edit, Bash, Grep, Glob
+---
+
+# Deployment Engineer
+
+Specialist in deployment automation, CI/CD pipelines, and infrastructure management.
+
+## When This Skill Activates
+
+Activates when you:
+- Set up deployment pipeline
+- Configure CI/CD
+- Manage releases
+- Automate infrastructure
+
+## CI/CD Pipeline
+
+### Pipeline Stages
+
+```yaml
+stages:
+  - lint
+  - test
+  - build
+  - security
+  - deploy-dev
+  - deploy-staging
+  - deploy-production
+```
+
+### GitHub Actions Example
+
+```yaml
+name: CI/CD
+
+on:
+  push:
+    branches: [main, develop]
+  pull_request:
+    branches: [main]
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+      - run: npm ci
+      - run: npm run lint
+
+  test:
+    runs-on: ubuntu-latest
+    needs: lint
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+      - run: npm ci
+      - run: npm test
+
+  build:
+    runs-on: ubuntu-latest
+    needs: test
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+      - run: npm ci
+      - run: npm run build
+      - uses: actions/upload-artifact@v4
+        with:
+          name: build
+          path: dist/
+
+  deploy-production:
+    runs-on: ubuntu-latest
+    needs: build
+    if: github.ref == 'refs/heads/main'
+    environment: production
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/download-artifact@v4
+        with:
+          name: build
+          path: dist/
+      - run: npm run deploy
+```
+
+## Deployment Strategies
+
+### 1. Blue-Green Deployment
+
+```
+         ┌─────────┐
+         │  Load   │
+         │ Balancer│
+         └────┬────┘
+              │
+     ┌────────┴────────┐
+     │    Switch       │
+     ├────────┬────────┤
+     ▼        ▼        ▼
+  ┌─────┐ ┌─────┐ ┌─────┐
+  │Blue │ │Green│ │     │
+  └─────┘ └─────┘ └─────┘
+```
+
+### 2. Rolling Deployment
+
+```
+┌─────────────────────────────────────┐
+│ v1  v1  v1  v1  v1  v1  v1  v1  v1 │ → Old
+│ v2  v2  v2  v2  v2  v2  v2  v2  v2 │ → New
+└─────────────────────────────────────┘
+    ▲                       ▲
+    │                       │
+  Start                  End
+```
+
+### 3. Canary Deployment
+
+```
+┌──────────────────────────────────────┐
+│ v1  v1  v1  v1  v1  v1  v1  v1  v1  v1 │ → Old
+│ v2  v2  v2  v2                        │ → Canary (5%)
+└──────────────────────────────────────┘
+
+Monitor metrics, then:
+│ v1  v1  v1  v1                        │ → Old (50%)
+│ v2  v2  v2  v2  v2  v2  v2  v2  v2  v2 │ → New (50%)
+```
+
+## Environment Configuration
+
+### Environment Variables
+
+```bash
+# Production
+NODE_ENV=production
+DATABASE_URL=postgresql://...
+API_KEY=sk-...
+SENTRY_DSN=https://example.com/123
+
+# Development
+NODE_ENV=development
+DATABASE_URL=postgresql://localhost:5432/dev
+```
+
+### Configuration Management
+
+```typescript
+// config/production.ts
+export default {
+  database: {
+    url: process.env.DATABASE_URL,
+    poolSize: 20,
+  },
+  redis: {
+    url: process.env.REDIS_URL,
+  },
+};
+```
+
+## Health Checks
+
+```typescript
+// GET /health
+app.get('/health', (req, res) => {
+  const health = {
+    status: 'ok',
+    timestamp: new Date().toISOString(),
+    checks: {
+      database: 'ok',
+      redis: 'ok',
+      external_api: 'ok',
+    },
+  };
+
+  if (Object.values(health.checks).some(v => v !== 'ok')) {
+    health.status = 'degraded';
+    return res.status(503).json(health);
+  }
+
+  res.json(health);
+});
+```
+
+## Rollback Strategy
+
+```bash
+# Kubernetes
+kubectl rollout undo deployment/app
+
+# Docker
+docker-compose down
+docker-compose up -d --scale app=<previous-version>
+
+# Git
+git revert HEAD
+git push
+```
+
+## Monitoring & Logging
+
+### Metrics to Track
+
+- Deployment frequency
+- Lead time for changes
+- Mean time to recovery (MTTR)
+- Change failure rate
+
+### Logging
+
+```typescript
+// Structured logging
+logger.info('Deployment started', {
+  version: process.env.VERSION,
+  environment: process.env.NODE_ENV,
+  timestamp: new Date().toISOString(),
+});
+```
+
+## Scripts
+
+Generate deployment config:
+```bash
+python scripts/generate_deploy.py <environment>
+```
+
+Validate deployment:
+```bash
+python scripts/validate_deploy.py
+```
+
+## References
+
+- `references/pipelines.md` - CI/CD pipeline examples
+- `references/kubernetes.md` - K8s deployment configs
+- `references/monitoring.md` - Monitoring setup

package/skills/deployment-engineer/references/kubernetes.md

@@ -0,0 +1,23 @@
+# Kubernetes Deployment Skeleton
+
+```yaml
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: app
+spec:
+  replicas: 2
+  selector:
+    matchLabels:
+      app: app
+  template:
+    metadata:
+      labels:
+        app: app
+    spec:
+      containers:
+        - name: app
+          image: example/app:latest
+          ports:
+            - containerPort: 8080
+```

package/skills/deployment-engineer/references/monitoring.md

@@ -0,0 +1,14 @@
+# Monitoring Checklist
+
+## Metrics
+- Request rate
+- Error rate
+- Latency (p50/p95/p99)
+
+## Logs
+- Structured logs with request IDs
+- Include error context and stack traces
+
+## Alerts
+- Define SLO-based alerts
+- Avoid noisy, low-signal alerts

package/skills/deployment-engineer/references/pipelines.md

@@ -0,0 +1,12 @@
+# CI/CD Pipeline Patterns
+
+## Recommended Stages
+- lint
+- test
+- build
+- security
+- deploy
+
+## Notes
+- Keep pipelines fast and deterministic
+- Fail fast on lint and unit tests