zoe-agent 0.3.1

package/skills/docker-ops/SKILL.md

@@ -0,0 +1,329 @@
+---
+name: docker-ops
+description: >
+  Docker container operations for production and development environments.
+  Activates when the user asks to build, run, stop, or remove Docker containers;
+  manage Docker images; write or debug Dockerfiles or docker-compose.yml files;
+  troubleshoot container failures, networking, or volumes; inspect container logs
+  or resource usage; push or pull images from registries; prune unused Docker
+  resources; set up multi-stage builds; configure container health checks;
+  manage Docker networks and persistent storage; run docker-compose up, down,
+  or ps; debug "container won't start", "image build fails", "port already in
+  use", "volume mount not working", or "container keeps restarting" issues.
+  Also triggers on mentions of Docker Swarm, Docker secret management, or
+  container orchestration at the single-host level.
+version: 1.0.0
+tags:
+  - docker
+  - containers
+  - devops
+  - docker-compose
+  - dockerfile
+  - containerization
+  - images
+  - volumes
+  - networking
+allowedTools:
+  - execute_shell_command
+  - read_file
+  - write_file
+---
+
+# Docker Operations Skill
+
+This skill provides procedures for building, running, managing, and troubleshooting
+Docker containers and Docker Compose stacks. It assumes Docker is available in the
+execution environment and the agent has shell access.
+
+## Constraints
+
+- **Never use `:latest` tag in production** -- always pin a specific version or digest.
+- **Never run containers as root in production** -- add `USER` directive to Dockerfiles.
+- **Never store secrets in Dockerfiles or compose files** -- use Docker secrets, environment
+  variables passed at runtime, or external secret managers.
+- **Never use `docker system prune -f` without user confirmation** -- it deletes all unused
+  data indiscriminately.
+- **Always use `--rm` for ephemeral containers** to prevent accumulation.
+- **Never expose the Docker daemon socket (`/var/run/docker.sock`) to containers** unless
+  explicitly requested by the user.
+
+## Building Images
+
+### Standard Dockerfile Structure
+
+Follow this order for cache efficiency:
+
+```
+# 1. Base image (pinned version)
+FROM node:20.11-alpine AS base
+
+# 2. System dependencies (rarely change)
+RUN apk add --no-cache curl
+
+# 3. Workdir
+WORKDIR /app
+
+# 4. Copy dependency manifests first (cache layer)
+COPY package.json pnpm-lock.yaml ./
+
+# 5. Install dependencies
+RUN corepack enable && pnpm install --frozen-lockfile --prod
+
+# 6. Copy application code
+COPY . .
+
+# 7. Non-root user
+USER node
+
+# 8. Health check
+HEALTHCHECK --interval=30s --timeout=5s --retries=3 \
+  CMD curl -f http://localhost:3000/health || exit 1
+
+# 9. Expose port and entrypoint
+EXPOSE 3000
+CMD ["node", "dist/index.js"]
+```
+
+### Multi-Stage Builds
+
+Use multi-stage builds to keep final images small. A typical pattern:
+
+1. **Build stage**: Full SDK, compile source, run tests.
+2. **Runtime stage**: Minimal base image, copy only compiled output and production deps.
+
+```dockerfile
+FROM node:20.11-alpine AS builder
+WORKDIR /app
+COPY package.json pnpm-lock.yaml ./
+RUN corepack enable && pnpm install --frozen-lockfile
+COPY . .
+RUN pnpm run build
+
+FROM node:20.11-alpine AS runtime
+WORKDIR /app
+COPY package.json pnpm-lock.yaml ./
+RUN corepack enable && pnpm install --frozen-lockfile --prod
+COPY --from=builder /app/dist ./dist
+USER node
+CMD ["node", "dist/index.js"]
+```
+
+### Build Commands
+
+```bash
+# Build with explicit tag and no cache
+docker build --no-cache -t myapp:1.2.0 .
+
+# Build with build arguments
+docker build --build-arg NODE_ENV=production -t myapp:1.2.0 .
+
+# Build for multiple platforms
+docker buildx build --platform linux/amd64,linux/arm64 -t myapp:1.2.0 .
+```
+
+## Running Containers
+
+### Common Run Patterns
+
+```bash
+# Run detached with auto-restart and resource limits
+docker run -d \
+  --name myapp \
+  --restart unless-stopped \
+  --memory 512m --cpus 1.0 \
+  -p 3000:3000 \
+  -e NODE_ENV=production \
+  -v myapp-data:/app/data \
+  myapp:1.2.0
+
+# Run interactively for debugging
+docker run -it --rm \
+  -v $(pwd):/app \
+  --entrypoint /bin/sh \
+  myapp:1.2.0
+
+# Run with health check override
+docker run -d \
+  --name myapp \
+  --health-cmd "curl -f http://localhost:3000/health" \
+  --health-interval 10s \
+  --health-timeout 3s \
+  myapp:1.2.0
+```
+
+### Inspecting Running Containers
+
+```bash
+# Check resource usage (all running containers)
+docker stats --no-stream
+
+# Detailed container info (IP, mounts, env vars)
+docker inspect myapp --format '{{ .NetworkSettings.IPAddress }}'
+
+# Follow logs with timestamps
+docker logs -f --since 1h --timestamps myapp
+
+# List containers with size
+docker ps -s
+```
+
+## Docker Compose
+
+### Compose File Best Practices
+
+```yaml
+services:
+  app:
+    build:
+      context: .
+      dockerfile: Dockerfile
+      args:
+        NODE_ENV: production
+    image: myapp:1.2.0
+    restart: unless-stopped
+    ports:
+      - "3000:3000"
+    environment:
+      NODE_ENV: production
+      DATABASE_URL: ${DATABASE_URL}
+    volumes:
+      - app-data:/app/data
+    depends_on:
+      db:
+        condition: service_healthy
+    deploy:
+      resources:
+        limits:
+          memory: 512M
+          cpus: "1.0"
+    healthcheck:
+      test: ["CMD", "curl", "-f", "http://localhost:3000/health"]
+      interval: 30s
+      timeout: 5s
+      retries: 3
+
+  db:
+    image: postgres:16.2-alpine
+    restart: unless-stopped
+    environment:
+      POSTGRES_DB: myapp
+      POSTGRES_USER: ${DB_USER}
+      POSTGRES_PASSWORD: ${DB_PASSWORD}
+    volumes:
+      - db-data:/var/lib/postgresql/data
+    healthcheck:
+      test: ["CMD-SHELL", "pg_isready -U $$POSTGRES_USER"]
+      interval: 10s
+      timeout: 5s
+      retries: 5
+
+volumes:
+  app-data:
+  db-data:
+```
+
+### Compose Commands
+
+```bash
+# Start stack in detached mode
+docker compose up -d
+
+# Rebuild and restart a single service
+docker compose up -d --build app
+
+# View logs for a specific service
+docker compose logs -f app
+
+# Scale a service
+docker compose up -d --scale worker=3
+
+# Tear down with volumes
+docker compose down -v
+```
+
+## Troubleshooting Decision Tree
+
+### Container exits immediately
+
+1. Check exit code: `docker inspect myapp --format '{{ .State.ExitCode }}'`
+2. Exit code 0: Process completed -- likely a missing foreground process or CMD issue.
+3. Exit code 1: Application error -- check logs with `docker logs myapp`.
+4. Exit code 137: OOM killed -- increase memory limit or investigate memory leaks.
+5. Exit code 139: Segfault -- check base image compatibility (glibc vs musl).
+
+### Container won't start / keeps restarting
+
+1. `docker logs --tail 50 myapp` -- look for error messages.
+2. `docker inspect myapp --format '{{ json .State }}'` -- check restart count and status.
+3. Verify port is not already in use: `ss -tlnp | grep <port>`.
+4. Verify volume mounts exist and have correct permissions.
+5. Check if health check is failing too aggressively -- widen intervals.
+
+### Networking issues
+
+1. List networks: `docker network ls`
+2. Inspect a network: `docker network inspect bridge`
+3. Test connectivity from inside a container: `docker exec myapp ping db`
+4. DNS resolution in Docker: containers on the same custom network resolve by
+   service name automatically.
+5. Port mapping issues: use `docker port myapp` to verify published ports.
+
+### Volume mount problems
+
+1. Check mount points: `docker inspect myapp --format '{{ json .Mounts }}'`
+2. File permissions: the host directory's UID/GID must match what the container
+   process expects. This is common with Alpine images running as non-root users.
+3. SELinux (on RHEL/CentOS): append `:z` or `:Z` to volume mounts.
+4. Named volumes vs bind mounts: named volumes are managed by Docker, bind mounts
+   map directly to host paths.
+
+## Image Management
+
+```bash
+# List images with dangling filter
+docker images -f dangling=true
+
+# Remove dangling images
+docker image prune
+
+# Tag and push to registry
+docker tag myapp:1.2.0 registry.example.com/myapp:1.2.0
+docker push registry.example.com/myapp:1.2.0
+
+# Inspect image layers
+docker history myapp:1.2.0 --no-trunc
+
+# Save/load image for air-gapped transfer
+docker save myapp:1.2.0 | gzip > myapp-1.2.0.tar.gz
+docker load < myapp-1.2.0.tar.gz
+```
+
+## Cleanup Procedures
+
+```bash
+# Remove stopped containers
+docker container prune
+
+# Remove unused images
+docker image prune -a --filter "until=168h"
+
+# Remove unused volumes (CAUTION: data loss)
+docker volume prune
+
+# Full cleanup (ask user first)
+docker system prune --volumes
+```
+
+## Registry Operations
+
+```bash
+# Login to a private registry
+docker login registry.example.com
+
+# List tags in a registry (via API)
+curl -s -u "$USER:$PASS" https://registry.example.com/v2/myapp/tags/list | jq .
+
+# Remove a manifest by digest (garbage collection required on registry)
+curl -s -u "$USER:$PASS" -X DELETE \
+  https://registry.example.com/v2/myapp/manifests/$DIGEST
+```

package/skills/k8s-deploy/SKILL.md

@@ -0,0 +1,397 @@
+---
+name: k8s-deploy
+description: >
+  Kubernetes deployment operations using kubectl and helm. Activates when the user
+  asks to deploy applications to Kubernetes clusters; create or update Deployments,
+  Services, ConfigMaps, Secrets, Ingress resources, or PersistentVolumeClaims;
+  manage rollouts, rollbacks, and scaling; troubleshoot pod failures, CrashLoopBackOff,
+  ImagePullBackOff, or pending pods; inspect cluster resources and events; work with
+  Namespaces, Labels, and Selectors; configure resource limits, requests, and
+  horizontal pod autoscalers (HPA); manage helm charts and releases; perform canary
+  or blue-green deployments; debug service discovery, DNS resolution, or network
+  policies; review or generate Kubernetes manifests; manage ServiceAccounts, RBAC,
+  and PodSecurityPolicies; handle node maintenance, cordoning, and draining; run
+  kubectl exec, logs, port-forward, or describe commands.
+version: 1.0.0
+tags:
+  - kubernetes
+  - k8s
+  - kubectl
+  - helm
+  - deployment
+  - pods
+  - services
+  - devops
+  - orchestration
+  - rollout
+  - rollback
+allowedTools:
+  - execute_shell_command
+  - read_file
+  - write_file
+---
+
+# Kubernetes Deployment Skill
+
+This skill covers deploying, managing, and troubleshooting applications on
+Kubernetes clusters using kubectl and helm. It assumes kubectl is configured
+with appropriate kubeconfig access and the agent has shell access.
+
+## Constraints
+
+- **Never use `:latest` tag in production Deployments** -- always pin a specific
+  container image tag or digest.
+- **Never run pods as root in production** -- set `securityContext.runAsNonRoot: true`
+  and `runAsUser: 1000+`.
+- **Always set resource requests and limits** -- unbounded pods can starve other
+  workloads and trigger node-level OOM.
+- **Never expose the Kubernetes API server to the public internet** without
+  authentication.
+- **Never delete Namespaces without user confirmation** -- cascading deletes are
+  irreversible.
+- **Always use `--dry-run=client -o yaml` before applying** to preview manifests.
+- **Prefer `kubectl apply` over `kubectl create`** for idempotent operations.
+- **Never modify resources in `kube-system` namespace** unless explicitly asked.
+
+## Pre-Flight Checks
+
+Before any deployment, verify cluster access and context:
+
+```bash
+# Verify connectivity
+kubectl cluster-info
+
+# Check current context (never deploy to the wrong cluster)
+kubectl config current-context
+
+# List available namespaces
+kubectl get namespaces
+
+# Check node health
+kubectl get nodes -o wide
+```
+
+If the context points to a production cluster, **warn the user and confirm
+before proceeding**.
+
+## Deployment Manifests
+
+### Standard Deployment Template
+
+```yaml
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: myapp
+  namespace: production
+  labels:
+    app: myapp
+    version: "1.2.0"
+spec:
+  replicas: 3
+  strategy:
+    type: RollingUpdate
+    rollingUpdate:
+      maxSurge: 1
+      maxUnavailable: 0
+  selector:
+    matchLabels:
+      app: myapp
+  template:
+    metadata:
+      labels:
+        app: myapp
+        version: "1.2.0"
+    spec:
+      serviceAccountName: myapp
+      securityContext:
+        runAsNonRoot: true
+        runAsUser: 1000
+        fsGroup: 1000
+      containers:
+        - name: myapp
+          image: registry.example.com/myapp:1.2.0
+          ports:
+            - containerPort: 3000
+          env:
+            - name: NODE_ENV
+              value: "production"
+            - name: DATABASE_URL
+              valueFrom:
+                secretKeyRef:
+                  name: myapp-secrets
+                  key: database-url
+          resources:
+            requests:
+              memory: "128Mi"
+              cpu: "100m"
+            limits:
+              memory: "512Mi"
+              cpu: "500m"
+          readinessProbe:
+            httpGet:
+              path: /health
+              port: 3000
+            initialDelaySeconds: 5
+            periodSeconds: 10
+          livenessProbe:
+            httpGet:
+              path: /health
+              port: 3000
+            initialDelaySeconds: 15
+            periodSeconds: 20
+          volumeMounts:
+            - name: config
+              mountPath: /app/config
+              readOnly: true
+      volumes:
+        - name: config
+          configMap:
+            name: myapp-config
+```
+
+### Service Template
+
+```yaml
+apiVersion: v1
+kind: Service
+metadata:
+  name: myapp
+  namespace: production
+spec:
+  selector:
+    app: myapp
+  ports:
+    - port: 80
+      targetPort: 3000
+      protocol: TCP
+  type: ClusterIP
+```
+
+### Ingress Template
+
+```yaml
+apiVersion: networking.k8s.io/v1
+kind: Ingress
+metadata:
+  name: myapp
+  namespace: production
+  annotations:
+    cert-manager.io/cluster-issuer: letsencrypt-prod
+spec:
+  ingressClassName: nginx
+  tls:
+    - hosts:
+        - myapp.example.com
+      secretName: myapp-tls
+  rules:
+    - host: myapp.example.com
+      http:
+        paths:
+          - path: /
+            pathType: Prefix
+            backend:
+              service:
+                name: myapp
+                port:
+                  number: 80
+```
+
+## Deployment Workflow
+
+### 1. Deploy or Update an Application
+
+```bash
+# Apply manifests
+kubectl apply -f deployment.yaml -f service.yaml -f ingress.yaml
+
+# Check rollout status
+kubectl rollout status deployment/myapp -n production
+
+# Verify pods are running
+kubectl get pods -n production -l app=myapp
+```
+
+### 2. Rolling Update (Image Change)
+
+```bash
+# Update the image
+kubectl set image deployment/myapp myapp=registry.example.com/myapp:1.3.0 \
+  -n production
+
+# Monitor rollout
+kubectl rollout status deployment/myapp -n production
+
+# Check revision history
+kubectl rollout history deployment/myapp -n production
+```
+
+### 3. Rollback
+
+```bash
+# Check rollout history
+kubectl rollout history deployment/myapp -n production
+
+# Rollback to previous revision
+kubectl rollout undo deployment/myapp -n production
+
+# Rollback to a specific revision
+kubectl rollout undo deployment/myapp --to-revision=2 -n production
+```
+
+### 4. Scale
+
+```bash
+# Scale manually
+kubectl scale deployment/myapp --replicas=5 -n production
+
+# Check HPA status
+kubectl get hpa -n production
+```
+
+## Helm Operations
+
+### Install and Upgrade
+
+```bash
+# Install a chart
+helm install myapp ./charts/myapp -n production -f values-production.yaml
+
+# Upgrade with new values or image tag
+helm upgrade myapp ./charts/myapp -n production \
+  -f values-production.yaml \
+  --set image.tag=1.3.0
+
+# Dry-run to preview changes
+helm upgrade myapp ./charts/myapp -n production \
+  -f values-production.yaml \
+  --dry-run --debug
+
+# Rollback a helm release
+helm rollback myapp 2 -n production
+
+# List releases
+helm list -n production
+
+# Show rendered templates without applying
+helm template myapp ./charts/myapp -f values-production.yaml
+```
+
+### Values File Best Practices
+
+```yaml
+# values-production.yaml
+replicaCount: 3
+
+image:
+  repository: registry.example.com/myapp
+  tag: "1.2.0"   # never "latest"
+  pullPolicy: IfNotPresent
+
+resources:
+  requests:
+    memory: "128Mi"
+    cpu: "100m"
+  limits:
+    memory: "512Mi"
+    cpu: "500m"
+
+autoscaling:
+  enabled: true
+  minReplicas: 3
+  maxReplicas: 10
+  targetCPUUtilizationPercentage: 70
+  targetMemoryUtilizationPercentage: 80
+```
+
+## Troubleshooting Decision Tree
+
+### Pod is Pending
+
+1. `kubectl describe pod <pod> -n <ns>` -- check the Events section at the bottom.
+2. Common causes:
+   - Insufficient resources: check `kubectl describe node <node>` for allocatable
+     capacity and existing requests.
+   - PersistentVolumeClaim not bound: `kubectl get pvc -n <ns>`.
+   - NodeSelector or affinity rules too restrictive: verify matching node labels.
+   - Taints preventing scheduling: `kubectl describe node <node> | grep Taints`.
+
+### Pod is CrashLoopBackOff
+
+1. `kubectl logs <pod> -n <ns> --previous` -- logs from the last failed container.
+2. `kubectl describe pod <pod> -n <ns>` -- check last state and exit code.
+3. Common causes:
+   - Exit code 1: Application error -- check config, env vars, missing secrets.
+   - Exit code 137: OOMKilled -- increase memory limit or investigate memory usage.
+   - Exit code 139: Segfault -- architecture mismatch (e.g., ARM image on AMD64 node).
+   - Application crashes on startup: probe too aggressive, missing init dependencies.
+
+### Pod is ImagePullBackOff
+
+1. `kubectl describe pod <pod> -n <ns>` -- check the exact error message.
+2. Common causes:
+   - Image does not exist: verify tag name and registry path.
+   - Registry requires authentication: create a `docker-registry` secret and
+     reference it as `imagePullSecrets`.
+   - Private registry unreachable from cluster: check network policies and firewall.
+
+### Service Discovery Issues
+
+1. Verify the Service selector matches pod labels:
+   `kubectl get pods -n <ns> --show-labels`
+2. Test DNS resolution from inside the cluster:
+   `kubectl run tmp --rm -it --image=busybox --restart=Never -- nslookup myapp.production.svc.cluster.local`
+3. Check endpoints: `kubectl get endpoints myapp -n <ns>`
+4. If endpoints are empty, the selector is wrong or pods are not ready.
+
+### High Restart Count
+
+```bash
+# Check restart counts
+kubectl get pods -n <ns> -o wide
+
+# Get detailed pod metrics
+kubectl top pods -n <ns>
+
+# Check events sorted by time
+kubectl get events -n <ns> --sort-by='.lastTimestamp'
+```
+
+## Useful Diagnostic Commands
+
+```bash
+# Exec into a running pod
+kubectl exec -it <pod> -n <ns> -- /bin/sh
+
+# Port-forward for local debugging
+kubectl port-forward svc/myapp 8080:80 -n <ns>
+
+# Copy files from/to a pod
+kubectl cp <pod>:/app/logs/app.log ./app.log -n <ns>
+
+# Watch resources in real-time
+kubectl get pods -n <ns> -w
+
+# Get resource usage
+kubectl top nodes
+kubectl top pods -n <ns>
+
+# Extract a secret (base64 decoded)
+kubectl get secret myapp-secrets -n <ns> -o jsonpath='{.data.database-url}' | base64 -d
+
+# Check cluster-level events
+kubectl get events -A --sort-by='.lastTimestamp' --field-selector type=Warning
+```
+
+## Node Maintenance
+
+```bash
+# Cordon a node (prevent new pods)
+kubectl cordon <node>
+
+# Drain a node (evict pods gracefully)
+kubectl drain <node> --ignore-daemonsets --delete-emptydir-data
+
+# Uncordon after maintenance
+kubectl uncordon <node>
+```