autodoc-agent-kit 1.0.0

package/src/modules/devops/skills/k8s-helm/SKILL.md

@@ -0,0 +1,360 @@
+---
+name: k8s-helm
+description: Kubernetes and Helm deployment patterns. Trigger when writing Kubernetes manifests, creating Helm charts, configuring deployments/services/ingress, or managing cluster resources.
+---
+
+# Kubernetes & Helm
+
+Deploy applications on Kubernetes with production-ready configurations. Use Helm for templating and managing releases.
+
+## Core Kubernetes Resources
+
+### Deployment
+
+```yaml
+# deployment.yaml
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: api
+  labels:
+    app: api
+spec:
+  replicas: 3
+  selector:
+    matchLabels:
+      app: api
+  strategy:
+    type: RollingUpdate
+    rollingUpdate:
+      maxSurge: 1
+      maxUnavailable: 0       # zero downtime
+  template:
+    metadata:
+      labels:
+        app: api
+    spec:
+      containers:
+        - name: api
+          image: myapp/api:1.2.3   # always use specific tags, never :latest
+          ports:
+            - containerPort: 3000
+          env:
+            - name: NODE_ENV
+              value: production
+            - name: DATABASE_URL
+              valueFrom:
+                secretKeyRef:
+                  name: api-secrets
+                  key: database-url
+          resources:
+            requests:
+              memory: "128Mi"
+              cpu: "100m"
+            limits:
+              memory: "512Mi"
+              cpu: "500m"
+          readinessProbe:
+            httpGet:
+              path: /health/ready
+              port: 3000
+            initialDelaySeconds: 10
+            periodSeconds: 5
+            failureThreshold: 3
+          livenessProbe:
+            httpGet:
+              path: /health/live
+              port: 3000
+            initialDelaySeconds: 30
+            periodSeconds: 10
+          securityContext:
+            runAsNonRoot: true
+            runAsUser: 1000
+            allowPrivilegeEscalation: false
+            readOnlyRootFilesystem: true
+      topologySpreadConstraints:
+        - maxSkew: 1
+          topologyKey: kubernetes.io/hostname
+          whenUnsatisfiable: DoNotSchedule
+          labelSelector:
+            matchLabels:
+              app: api
+```
+
+### Service
+
+```yaml
+# service.yaml
+apiVersion: v1
+kind: Service
+metadata:
+  name: api
+spec:
+  selector:
+    app: api
+  ports:
+    - port: 80
+      targetPort: 3000
+  type: ClusterIP   # internal only; use LoadBalancer for external
+```
+
+### Ingress
+
+```yaml
+# ingress.yaml
+apiVersion: networking.k8s.io/v1
+kind: Ingress
+metadata:
+  name: api
+  annotations:
+    nginx.ingress.kubernetes.io/rate-limit: "100"
+    cert-manager.io/cluster-issuer: letsencrypt-prod
+spec:
+  ingressClassName: nginx
+  tls:
+    - hosts:
+        - api.example.com
+      secretName: api-tls
+  rules:
+    - host: api.example.com
+      http:
+        paths:
+          - path: /
+            pathType: Prefix
+            backend:
+              service:
+                name: api
+                port:
+                  number: 80
+```
+
+### ConfigMap and Secrets
+
+```yaml
+# configmap.yaml
+apiVersion: v1
+kind: ConfigMap
+metadata:
+  name: api-config
+data:
+  LOG_LEVEL: info
+  CACHE_TTL: "300"
+
+# secret.yaml — store in Vault or external secret manager, not in Git
+apiVersion: v1
+kind: Secret
+metadata:
+  name: api-secrets
+type: Opaque
+stringData:
+  database-url: "postgresql://user:pass@db:5432/app"
+  api-key: "sk-..."
+```
+
+### HorizontalPodAutoscaler
+
+```yaml
+# hpa.yaml
+apiVersion: autoscaling/v2
+kind: HorizontalPodAutoscaler
+metadata:
+  name: api
+spec:
+  scaleTargetRef:
+    apiVersion: apps/v1
+    kind: Deployment
+    name: api
+  minReplicas: 2
+  maxReplicas: 20
+  metrics:
+    - type: Resource
+      resource:
+        name: cpu
+        target:
+          type: Utilization
+          averageUtilization: 70
+    - type: Resource
+      resource:
+        name: memory
+        target:
+          type: Utilization
+          averageUtilization: 80
+```
+
+## Helm Charts
+
+### Chart Structure
+
+```
+my-app/
+├── Chart.yaml          # chart metadata
+├── values.yaml         # default values
+├── values-staging.yaml # environment overrides
+├── values-prod.yaml
+└── templates/
+    ├── _helpers.tpl    # named templates
+    ├── deployment.yaml
+    ├── service.yaml
+    ├── ingress.yaml
+    ├── hpa.yaml
+    └── secret.yaml
+```
+
+### Chart.yaml
+
+```yaml
+apiVersion: v2
+name: my-app
+description: My application Helm chart
+type: application
+version: 0.1.0        # chart version
+appVersion: "1.2.3"   # app version
+```
+
+### values.yaml
+
+```yaml
+replicaCount: 2
+
+image:
+  repository: myapp/api
+  tag: ""            # defaults to Chart.appVersion
+  pullPolicy: IfNotPresent
+
+service:
+  type: ClusterIP
+  port: 80
+
+ingress:
+  enabled: true
+  host: api.example.com
+  tls: true
+
+resources:
+  requests:
+    cpu: 100m
+    memory: 128Mi
+  limits:
+    cpu: 500m
+    memory: 512Mi
+
+autoscaling:
+  enabled: true
+  minReplicas: 2
+  maxReplicas: 10
+  targetCPUUtilizationPercentage: 70
+
+env: {}
+secrets: {}
+```
+
+### Template with Helpers
+
+```yaml
+# templates/_helpers.tpl
+{{- define "myapp.fullname" -}}
+{{- printf "%s-%s" .Release.Name .Chart.Name | trunc 63 | trimSuffix "-" }}
+{{- end }}
+
+{{- define "myapp.labels" -}}
+helm.sh/chart: {{ .Chart.Name }}-{{ .Chart.Version }}
+app.kubernetes.io/name: {{ .Chart.Name }}
+app.kubernetes.io/instance: {{ .Release.Name }}
+app.kubernetes.io/version: {{ .Chart.AppVersion | quote }}
+{{- end }}
+
+# templates/deployment.yaml
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: {{ include "myapp.fullname" . }}
+  labels:
+    {{- include "myapp.labels" . | nindent 4 }}
+spec:
+  replicas: {{ .Values.replicaCount }}
+  template:
+    spec:
+      containers:
+        - name: {{ .Chart.Name }}
+          image: "{{ .Values.image.repository }}:{{ .Values.image.tag | default .Chart.AppVersion }}"
+          resources:
+            {{- toYaml .Values.resources | nindent 12 }}
+```
+
+## Common kubectl Commands
+
+```bash
+# View all resources in a namespace
+kubectl get all -n my-namespace
+
+# Describe a pod (events, resource usage)
+kubectl describe pod <pod-name> -n my-namespace
+
+# View logs
+kubectl logs <pod-name> -n my-namespace
+kubectl logs -l app=api -n my-namespace --tail=100 -f  # follow all pods
+
+# Execute into pod
+kubectl exec -it <pod-name> -n my-namespace -- sh
+
+# Port forward for local debugging
+kubectl port-forward svc/api 3000:80 -n my-namespace
+
+# Apply manifests
+kubectl apply -f manifests/ -n my-namespace
+
+# Scale deployment manually
+kubectl scale deployment api --replicas=5 -n my-namespace
+
+# View rollout status
+kubectl rollout status deployment/api -n my-namespace
+
+# Rollback
+kubectl rollout undo deployment/api -n my-namespace
+kubectl rollout history deployment/api -n my-namespace
+
+# Resource usage
+kubectl top pods -n my-namespace
+kubectl top nodes
+```
+
+## Common Helm Commands
+
+```bash
+# Add a chart repository
+helm repo add bitnami https://charts.bitnami.com/bitnami
+helm repo update
+
+# Install a chart
+helm install my-release ./my-app -n my-namespace --create-namespace
+
+# Upgrade with new values
+helm upgrade my-release ./my-app -n my-namespace \
+  -f values-prod.yaml \
+  --set image.tag=1.2.4
+
+# Preview rendered templates (dry run)
+helm template my-release ./my-app -f values-prod.yaml
+
+# Rollback
+helm rollback my-release 1 -n my-namespace
+
+# List releases
+helm list -n my-namespace
+
+# Uninstall
+helm uninstall my-release -n my-namespace
+```
+
+## Production Best Practices
+
+1. **Never use `:latest` image tags** — use specific SHAs or version tags
+2. **Always set resource requests and limits** — prevents noisy neighbor issues
+3. **Configure readiness probes** — prevents traffic to not-ready pods
+4. **Set `minReplicas: 2` for HA** — single pod = single point of failure
+5. **Use `maxUnavailable: 0`** for zero-downtime deployments
+6. **Store secrets in Vault/AWS SSM**, sync with External Secrets Operator
+7. **Set `topologySpreadConstraints`** to spread pods across nodes
+8. **Run as non-root user** in all containers
+9. **Set `readOnlyRootFilesystem: true`** where possible
+10. **Use namespaces** for environment isolation (dev, staging, prod)

package/src/modules/devops/skills/monitoring-observability/SKILL.md

@@ -0,0 +1,240 @@
+---
+name: monitoring-observability
+description: Logging, metrics, tracing, and alerting for production systems. Trigger when setting up observability infrastructure, adding logging to services, configuring metrics, or diagnosing production incidents.
+---
+
+# Monitoring & Observability
+
+Observability is the ability to understand a system's state from its outputs. The three pillars: **Logs** (what happened), **Metrics** (how much/how often), **Traces** (why it's slow).
+
+## The Three Pillars
+
+### Logs — What Happened
+
+Structured JSON logs are searchable and parseable by log aggregation systems.
+
+```ts
+// Use a structured logger — never console.log in production
+import pino from 'pino';
+
+const logger = pino({
+  level: process.env.LOG_LEVEL ?? 'info',
+  ...(process.env.NODE_ENV === 'development' && {
+    transport: { target: 'pino-pretty' }, // human-readable in dev
+  }),
+});
+
+// Always include context
+logger.info({ userId, action: 'checkout.started', cartItems: 3 }, 'Checkout initiated');
+logger.error({ err, orderId, userId }, 'Payment processing failed');
+logger.warn({ latencyMs: 1500, threshold: 1000 }, 'Slow database query detected');
+```
+
+**Log Levels:**
+
+| Level | Use for |
+|-------|---------|
+| `error` | Unrecoverable errors, requires immediate attention |
+| `warn` | Degraded behavior, approaching limits |
+| `info` | Normal operations, key business events |
+| `debug` | Detailed troubleshooting (disabled in prod) |
+
+**What to always include:**
+- `requestId` / `traceId` — correlation across services
+- `userId` — for user-impacting issues
+- `service` / `version` — which service logged this
+- `err` — full error object (not just message)
+- Relevant entity IDs (`orderId`, `productId`, etc.)
+
+### Metrics — How Much / How Often
+
+```ts
+// Prometheus with prom-client
+import { Counter, Histogram, Gauge, register } from 'prom-client';
+
+// Request counter
+const httpRequests = new Counter({
+  name: 'http_requests_total',
+  help: 'Total HTTP requests',
+  labelNames: ['method', 'route', 'status_code'],
+});
+
+// Latency histogram
+const httpLatency = new Histogram({
+  name: 'http_request_duration_ms',
+  help: 'HTTP request duration in milliseconds',
+  labelNames: ['method', 'route'],
+  buckets: [5, 10, 25, 50, 100, 250, 500, 1000, 2500],
+});
+
+// Active connections gauge
+const activeConnections = new Gauge({
+  name: 'active_connections',
+  help: 'Number of active connections',
+});
+
+// Middleware usage
+function metricsMiddleware(req, res, next) {
+  const timer = httpLatency.startTimer({ method: req.method, route: req.route?.path });
+  res.on('finish', () => {
+    timer();
+    httpRequests.inc({ method: req.method, route: req.route?.path, status_code: res.statusCode });
+  });
+  next();
+}
+
+// Expose metrics endpoint
+app.get('/metrics', async (req, res) => {
+  res.set('Content-Type', register.contentType);
+  res.end(await register.metrics());
+});
+```
+
+**Key Metrics to Track (RED method):**
+- **R**ate: requests per second
+- **E**rrors: error rate (%)
+- **D**uration: p50, p95, p99 latency
+
+**Business Metrics:**
+- Signups, purchases, conversions per hour
+- Feature usage counts
+- Queue depth, job processing rate
+
+### Traces — Why It's Slow
+
+```ts
+// OpenTelemetry — vendor-neutral tracing
+import { NodeSDK } from '@opentelemetry/sdk-node';
+import { OTLPTraceExporter } from '@opentelemetry/exporter-trace-otlp-http';
+import { HttpInstrumentation } from '@opentelemetry/instrumentation-http';
+import { ExpressInstrumentation } from '@opentelemetry/instrumentation-express';
+import { PrismaInstrumentation } from '@prisma/instrumentation';
+
+const sdk = new NodeSDK({
+  traceExporter: new OTLPTraceExporter({
+    url: process.env.OTEL_EXPORTER_OTLP_ENDPOINT,
+  }),
+  instrumentations: [
+    new HttpInstrumentation(),
+    new ExpressInstrumentation(),
+    new PrismaInstrumentation(),
+  ],
+});
+
+sdk.start(); // Must be called before importing app code
+```
+
+```ts
+// Custom spans for business logic
+import { trace } from '@opentelemetry/api';
+const tracer = trace.getTracer('my-service');
+
+async function processOrder(orderId: string) {
+  return tracer.startActiveSpan('processOrder', async (span) => {
+    span.setAttributes({ 'order.id': orderId });
+    try {
+      const result = await doWork(orderId);
+      span.setStatus({ code: SpanStatusCode.OK });
+      return result;
+    } catch (err) {
+      span.recordException(err);
+      span.setStatus({ code: SpanStatusCode.ERROR });
+      throw err;
+    } finally {
+      span.end();
+    }
+  });
+}
+```
+
+## Alerting
+
+### Alert Philosophy
+
+Alert on **symptoms** (user impact), not causes (CPU usage).
+
+```yaml
+# Prometheus alerting rules
+groups:
+  - name: api
+    rules:
+      # Error rate > 5% for 5 minutes
+      - alert: HighErrorRate
+        expr: |
+          sum(rate(http_requests_total{status_code=~"5.."}[5m]))
+          / sum(rate(http_requests_total[5m])) > 0.05
+        for: 5m
+        labels:
+          severity: critical
+        annotations:
+          summary: "High error rate: {{ $value | humanizePercentage }}"
+
+      # p99 latency > 2 seconds
+      - alert: HighLatency
+        expr: |
+          histogram_quantile(0.99, rate(http_request_duration_ms_bucket[5m])) > 2000
+        for: 10m
+        labels:
+          severity: warning
+
+      # Service down
+      - alert: ServiceDown
+        expr: up == 0
+        for: 1m
+        labels:
+          severity: critical
+```
+
+### Runbook Template
+
+Every alert should link to a runbook:
+
+```markdown
+# Alert: HighErrorRate
+
+## Impact
+Users are seeing 5xx errors. Checkout and API calls may be failing.
+
+## Diagnosis Steps
+1. Check error logs: `kubectl logs -l app=api --tail=100`
+2. Check recent deploys: `kubectl rollout history deployment/api`
+3. Check database connectivity: `kubectl exec -it <pod> -- psql $DATABASE_URL -c '\l'`
+
+## Resolution
+- If recent deploy: `kubectl rollout undo deployment/api`
+- If DB issue: check RDS console for CPU/connections
+- If memory: `kubectl top pods`
+```
+
+## Health Checks
+
+```ts
+// Kubernetes-compatible health endpoints
+app.get('/health/live', (req, res) => {
+  // Liveness: is the process running? Return 200 if so.
+  res.json({ status: 'ok' });
+});
+
+app.get('/health/ready', async (req, res) => {
+  // Readiness: can the service handle traffic?
+  try {
+    await db.$queryRaw`SELECT 1`;
+    await redis.ping();
+    res.json({ status: 'ready', checks: { database: 'ok', cache: 'ok' } });
+  } catch (err) {
+    res.status(503).json({ status: 'not ready', error: err.message });
+  }
+});
+```
+
+## Production Checklist
+
+- [ ] Structured logging (JSON) with consistent fields
+- [ ] Request ID propagated across all service calls
+- [ ] `/health/live` and `/health/ready` endpoints
+- [ ] Metrics exposed at `/metrics` (Prometheus format)
+- [ ] Distributed tracing configured (OpenTelemetry)
+- [ ] Alerts for error rate, latency, and uptime
+- [ ] Runbooks linked from alerts
+- [ ] Log retention policy set (30-90 days typical)
+- [ ] Sensitive data excluded from logs (passwords, tokens, PII)

package/src/modules/devops/skills/security-auditor/SKILL.md

@@ -0,0 +1,105 @@
+---
+name: security-auditor
+description: Security vulnerability scanning and remediation for web applications and APIs. Use when you need a security review of code, dependencies, or infrastructure configuration. Triggers on "check for security issues", "audit my code", "is this secure", "review for vulnerabilities", "OWASP check", or "find security bugs".
+---
+
+You are a security specialist focused on identifying and remediating vulnerabilities in application code.
+
+## Audit Scope
+
+### OWASP Top 10 Checks
+
+**A01 - Broken Access Control**
+- Missing authorization checks on endpoints
+- IDOR (Insecure Direct Object Reference) — can users access others' resources?
+- Missing function-level access control
+- CORS misconfiguration allowing unauthorized origins
+- JWT validation gaps (missing expiry check, weak signing)
+
+**A02 - Cryptographic Failures**
+- Sensitive data transmitted over HTTP
+- Weak hashing algorithms (MD5, SHA1 for passwords)
+- Hardcoded secrets, API keys, or credentials
+- Missing encryption for PII at rest
+
+**A03 - Injection**
+- SQL injection via string concatenation
+- XSS via unescaped user input in HTML
+- Command injection via shell execution with user input
+- Path traversal in file operations
+- Template injection
+
+**A04 - Insecure Design**
+- Missing rate limiting on authentication endpoints
+- No account lockout after failed attempts
+- Predictable resource IDs
+- Missing CSRF protection on state-changing operations
+
+**A05 - Security Misconfiguration**
+- Debug mode enabled in production configs
+- Default credentials or configurations
+- Unnecessary HTTP headers exposed
+- Directory listing enabled
+- Stack traces exposed in error responses
+
+**A06 - Vulnerable Components**
+- Known CVEs in dependencies (check package.json / requirements.txt)
+- Outdated frameworks with known vulnerabilities
+- Unmaintained dependencies
+
+**A07 - Authentication Failures**
+- Weak password policies
+- Missing MFA support
+- Session tokens in URLs
+- Tokens not invalidated on logout
+
+**A08 - Data Integrity Failures**
+- Unsigned or unverified data from external sources
+- Missing integrity checks on CI/CD pipeline
+- Deserialization of untrusted data
+
+**A09 - Logging & Monitoring Failures**
+- Sensitive data logged (passwords, tokens, PII)
+- Missing audit logs for sensitive operations
+- No alerting on suspicious activity patterns
+
+**A10 - SSRF**
+- Unvalidated URLs in server-side requests
+- Internal network exposure via URL parameters
+
+## Process
+
+### Step 1: Scan
+1. Map all entry points (API routes, form handlers, webhooks)
+2. Identify data flows from user input to storage/output
+3. Check authentication and authorization on every endpoint
+4. Review dependency versions for known vulnerabilities
+
+### Step 2: Analyze
+For each finding:
+- **Severity**: Critical / High / Medium / Low
+- **Evidence**: Exact file and line
+- **Exploitation**: How it could be exploited
+- **Remediation**: Specific code fix
+
+### Step 3: Report
+```
+## Security Audit Report
+
+### Critical
+- [file:line] [vulnerability type] — [description] — [fix]
+
+### High
+- [file:line] [vulnerability type] — [description] — [fix]
+
+### Medium / Low
+- [file:line] [vulnerability type] — [description] — [fix]
+
+### Recommendations
+- [general security improvements]
+```
+
+## Rules
+- Never disclose exploitation details in ways that could be misused
+- Prioritize by actual risk, not theoretical possibility
+- Include concrete remediation code, not just descriptions