@codeharbor/agent-playbook 0.1.0 → 0.1.1

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

package/skills/deployment-engineer/scripts/generate_deploy.py

@@ -0,0 +1,72 @@
+#!/usr/bin/env python3
+# Template generator for deployment plan.
+
+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 deployment plan.")
+    parser.add_argument("--output", default="deploy-plan.md", help="Output file path")
+    parser.add_argument("--name", default="example", help="Service or app name")
+    parser.add_argument("--env", default="production", help="Target environment")
+    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"""\
+        # Deployment Plan
+
+        ## Overview
+        - Service: {args.name}
+        - Environment: {args.env}
+        - Owner: {args.owner}
+
+        ## Preconditions
+        - Release approved
+        - Change window confirmed
+        - Backups verified
+
+        ## Steps
+        1. Build and publish artifacts
+        2. Deploy to staging and run smoke tests
+        3. Run migrations (if needed)
+        4. Deploy to {args.env}
+        5. Verify health checks and dashboards
+
+        ## Verification
+        - Health endpoint returns 200
+        - Key metrics within baseline
+        - Error budget stable
+
+        ## Rollback
+        - Revert to last known good release
+        - Disable feature flags
+        - Communicate rollback status
+
+        ## Observability
+        - Dashboard links
+        - Alert channels
+        """
+    ).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/scripts/validate_deploy.py

@@ -0,0 +1,46 @@
+#!/usr/bin/env python3
+# Template validator for deployment plan.
+
+from pathlib import Path
+import argparse
+
+DEFAULT_REQUIRED = [
+    "## Overview",
+    "## Preconditions",
+    "## Steps",
+    "## Verification",
+    "## Rollback",
+    "## Observability",
+]
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description="Validate a generated artifact.")
+    parser.add_argument("--input", default="deploy-plan.md", help="Input file path")
+    parser.add_argument(
+        "--require",
+        action="append",
+        default=[],
+        help="Additional required section heading",
+    )
+    args = parser.parse_args()
+
+    path = Path(args.input)
+    if not path.exists():
+        print(f"Missing file: {path}")
+        return 1
+
+    text = path.read_text(encoding="utf-8", errors="ignore")
+    text_lower = text.lower()
+    required = DEFAULT_REQUIRED + args.require
+    missing = [section for section in required if section.lower() not in text_lower]
+    if missing:
+        print("Missing required sections: " + ", ".join(missing))
+        return 1
+
+    print(f"Validated {path}")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/skills/documentation-engineer/README.md

@@ -0,0 +1,41 @@
+# Documentation Engineer
+
+> A Claude Code skill for creating clear, comprehensive documentation.
+
+## Installation
+
+This skill is part of the [agent-playbook](https://github.com/Charon-Fan/agent-playbook) collection.
+
+## Usage
+
+```
+You: Write documentation for this API
+You: Create a README
+You: Document this code
+```
+
+## Documentation Types
+
+| Type | Description |
+|------|-------------|
+| **README** | Project overview and quick start |
+| **API Docs** | Endpoint/function documentation |
+| **Code Comments** | Inline explanations |
+| **Architecture** | System design documentation |
+
+## Scripts
+
+Generate documentation structure:
+```bash
+python scripts/generate_docs.py
+```
+
+Validate documentation:
+```bash
+python scripts/validate_docs.py
+```
+
+## Resources
+
+- [Google Developer Documentation Style Guide](https://developers.google.com/tech-writing/one)
+- [Diátaxis Framework](https://diataxis.fr/)