@cubis/foundry 0.3.67 → 0.3.68

package/workflows/workflows/agent-environment-setup/platforms/claude/skills/observability/SKILL.md

@@ -0,0 +1,106 @@
+---
+name: observability
+description: "Use when designing or reviewing logging, monitoring, tracing, and alerting for production services. Covers structured logging, distributed tracing, metric collection, dashboard design, alert hygiene, SLO definition, and incident readiness across application and infrastructure layers."
+license: MIT
+metadata:
+  author: cubis-foundry
+  version: "1.0"
+compatibility: Claude Code, Codex, GitHub Copilot
+---
+
+# Observability
+
+## Purpose
+
+Use when designing or reviewing logging, monitoring, tracing, and alerting for production services. Covers structured logging, distributed tracing, metric collection, dashboard design, alert hygiene, SLO definition, and incident readiness across application and infrastructure layers.
+
+## When to Use
+
+- Working on observability related tasks
+
+## Instructions
+
+1. **Define SLOs first** — decide what "healthy" means before instrumenting. SLOs drive alerting, not the other way around.
+2. **Instrument the golden signals** — latency, traffic, errors, saturation. Every service must expose these four.
+3. **Structured logging** — JSON to stdout. Include request ID, user context, operation name, and outcome. Never log secrets or PII.
+4. **Distributed tracing** — propagate trace context across service boundaries. Instrument entry points, database calls, and external API calls.
+5. **Alert on symptoms, not causes** — alert on SLO burn rate, not on CPU percentage. Alerts must be actionable.
+
+### Three pillars
+
+### Logs
+
+- Write structured JSON logs to stdout/stderr. Let the platform handle collection.
+- Include: timestamp (ISO 8601), level, service name, trace ID, span ID, message, and relevant context fields.
+- Log levels: ERROR for failures requiring attention, WARN for degraded but functional, INFO for key business events, DEBUG for development only (disabled in production).
+- Never log: passwords, tokens, credit card numbers, PII, or full request/response bodies in production.
+- Correlation: every log line must include the request/trace ID for cross-referencing with traces and metrics.
+
+### Metrics
+
+- Use RED method for request-driven services: Rate, Errors, Duration.
+- Use USE method for resources: Utilization, Saturation, Errors.
+- Histogram for latency (not averages — p50/p95/p99 matter).
+- Counter for request counts, error counts, and throughput.
+- Gauge for current state (queue depth, active connections, cache size).
+- Label cardinality: keep label values bounded. Never use user IDs or request IDs as metric labels.
+
+### Traces
+
+- Use OpenTelemetry SDK for instrumentation — vendor-neutral, industry standard.
+- Auto-instrument HTTP clients, database drivers, and message consumers.
+- Add custom spans for significant business operations.
+- Propagate W3C Trace Context headers across all service boundaries.
+- Sample appropriately: 100% for errors, tail-sampled for high-volume happy paths.
+
+### SLO design
+
+- Define SLIs (Service Level Indicators) from the user's perspective — e.g., "percentage of requests completing in under 200ms."
+- Set SLOs at realistic targets — 99.9% is very different from 99.99%.
+- Calculate error budget: `1 - SLO target`. When budget is consumed, prioritize reliability over features.
+- Review SLOs quarterly. Adjust based on actual user impact data.
+
+### Alerting hygiene
+
+- Every alert must have: a clear title, expected impact, runbook link, and escalation path.
+- Use multi-window burn rate alerts for SLO-based alerting.
+- Suppress alerts during maintenance windows.
+- Page only for user-facing impact. Use tickets for slow-burn degradation.
+- Review alert fatigue monthly. If an alert fires more than weekly without action, fix or remove it.
+
+### Dashboard design
+
+- Start with a service overview dashboard: golden signals, SLO status, recent deployments.
+- Use consistent time ranges and refresh intervals across dashboards.
+- Top-to-bottom layout: high-level health → request flow → resource utilization → dependencies.
+- Every graph must have: title, unit, and a brief description of what abnormal looks like.
+- Avoid vanity dashboards — every panel must answer a question someone would ask during an incident.
+
+### Constraints
+
+- Avoid logging at DEBUG level in production — volume overwhelms analysis.
+- Avoid high-cardinality metric labels (user ID, IP address, full URL path).
+- Avoid alert on every error — alert on error rate exceeding SLO budget.
+- Avoid dashboard sprawl — ten dashboards nobody checks are worse than two good ones.
+- Avoid instrumenting everything with traces — sample and focus on critical paths.
+- Avoid using averages instead of percentiles for latency metrics.
+
+## Output Format
+
+Provide implementation guidance, code examples, and configuration as appropriate to the task.
+
+## References
+
+| File                                       | Purpose                                                                                         |
+| ------------------------------------------ | ----------------------------------------------------------------------------------------------- |
+| `references/opentelemetry-setup-guide.md`  | OTel SDK setup, auto-instrumentation, exporter configuration, and sampling strategy.            |
+| `references/alerting-and-slo-checklist.md` | SLO definition template, burn-rate alert formulas, runbook structure, and alert review process. |
+
+## Scripts
+
+No helper scripts are required for this skill right now. Keep execution in `SKILL.md` and `references/` unless repeated automation becomes necessary.
+
+## Examples
+
+- "Help me with observability best practices in this project"
+- "Review my observability implementation for issues"

package/workflows/workflows/agent-environment-setup/platforms/claude/skills/observability/references/alerting-and-slo-checklist.md

@@ -0,0 +1,87 @@
+# Alerting and SLO Checklist
+
+## SLO definition template
+
+```yaml
+slo:
+  name: "API request success rate"
+  service: my-service
+  sli:
+    type: availability
+    metric: "http_requests_total{status!~'5..'} / http_requests_total"
+  target: 99.9%
+  window: 30d
+  error_budget: 0.1% # ~43 minutes of downtime per 30 days
+  owner: platform-team
+  review_cadence: quarterly
+```
+
+## SLI types
+
+| Type         | Definition                              | Example metric                              |
+| ------------ | --------------------------------------- | ------------------------------------------- |
+| Availability | Proportion of successful requests       | `successful_requests / total_requests`      |
+| Latency      | Proportion of requests within threshold | `requests_under_200ms / total_requests`     |
+| Correctness  | Proportion of correct results           | `valid_responses / total_responses`         |
+| Freshness    | Proportion of data within age threshold | `records_updated_within_1h / total_records` |
+
+## Multi-window burn rate alerts
+
+Use burn rate to detect SLO violations early without false positives.
+
+| Alert severity             | Burn rate | Short window | Long window | Response              |
+| -------------------------- | --------- | ------------ | ----------- | --------------------- |
+| Page (immediate)           | 14.4x     | 5 min        | 1 hour      | Wake someone up       |
+| Page (urgent)              | 6x        | 30 min       | 6 hours     | Respond within 30 min |
+| Ticket (next business day) | 3x        | 2 hours      | 1 day       | Fix during work hours |
+| Ticket (low priority)      | 1x        | 6 hours      | 3 days      | Schedule in sprint    |
+
+Formula: `burn_rate = error_rate_in_window / (1 - slo_target)`
+
+Both short and long windows must exceed the burn rate threshold to fire.
+
+## Alert specification template
+
+```yaml
+alert:
+  name: "High error rate - API"
+  severity: page
+  condition: "burn rate > 14.4x for 5m AND burn rate > 14.4x for 1h"
+  impact: "Users experiencing API failures above SLO budget"
+  runbook: "https://wiki.internal/runbooks/api-high-error-rate"
+  escalation:
+    - primary: on-call-engineer
+    - secondary: team-lead (after 15 min)
+    - tertiary: engineering-manager (after 30 min)
+  silence_during:
+    - maintenance windows
+    - planned deployments
+```
+
+## Alert review process (monthly)
+
+- [ ] List all alerts that fired in the past 30 days
+- [ ] For each alert: was it actionable? Did someone respond?
+- [ ] Identify noisy alerts (fired >5 times without requiring action) — fix or remove
+- [ ] Identify missing alerts (incidents not caught by alerts) — add coverage
+- [ ] Verify all alerts have current runbook links
+- [ ] Verify escalation paths are up to date
+- [ ] Check that alert thresholds still match current SLO targets
+
+## Runbook structure
+
+Every alert must link to a runbook with:
+
+1. **What is this alert?** — one-sentence description
+2. **Why does it matter?** — user impact
+3. **First response** — immediate triage steps (check dashboards, recent deploys, dependencies)
+4. **Common causes** — ranked by frequency with fix instructions
+5. **Escalation** — when and who to escalate to
+6. **Post-incident** — link to post-mortem template
+
+## Error budget policy
+
+- **Budget remaining > 50%**: normal feature velocity
+- **Budget remaining 25-50%**: reduce risky changes, add reliability work to sprint
+- **Budget remaining < 25%**: freeze non-critical deploys, prioritize reliability
+- **Budget exhausted**: stop feature work, all hands on reliability until budget recovers

package/workflows/workflows/agent-environment-setup/platforms/claude/skills/observability/references/opentelemetry-setup-guide.md

@@ -0,0 +1,121 @@
+# OpenTelemetry Setup Guide
+
+## SDK initialization (Node.js)
+
+```typescript
+import { NodeSDK } from "@opentelemetry/sdk-node";
+import { getNodeAutoInstrumentations } from "@opentelemetry/auto-instrumentations-node";
+import { OTLPTraceExporter } from "@opentelemetry/exporter-trace-otlp-http";
+import { OTLPMetricExporter } from "@opentelemetry/exporter-metrics-otlp-http";
+import { PeriodicExportingMetricReader } from "@opentelemetry/sdk-metrics";
+import { Resource } from "@opentelemetry/resources";
+import {
+  ATTR_SERVICE_NAME,
+  ATTR_SERVICE_VERSION,
+} from "@opentelemetry/semantic-conventions";
+
+const sdk = new NodeSDK({
+  resource: new Resource({
+    [ATTR_SERVICE_NAME]: "my-service",
+    [ATTR_SERVICE_VERSION]: "1.0.0",
+  }),
+  traceExporter: new OTLPTraceExporter({
+    url: process.env.OTEL_EXPORTER_OTLP_ENDPOINT + "/v1/traces",
+  }),
+  metricReader: new PeriodicExportingMetricReader({
+    exporter: new OTLPMetricExporter({
+      url: process.env.OTEL_EXPORTER_OTLP_ENDPOINT + "/v1/metrics",
+    }),
+    exportIntervalMillis: 60_000,
+  }),
+  instrumentations: [getNodeAutoInstrumentations()],
+});
+
+sdk.start();
+process.on("SIGTERM", () => sdk.shutdown());
+```
+
+- Initialize the SDK before any other imports that need instrumentation.
+- Use environment variables for endpoint configuration — do not hardcode.
+
+## SDK initialization (Python)
+
+```python
+from opentelemetry import trace
+from opentelemetry.sdk.trace import TracerProvider
+from opentelemetry.sdk.trace.export import BatchSpanProcessor
+from opentelemetry.exporter.otlp.proto.grpc.trace_exporter import OTLPSpanExporter
+from opentelemetry.sdk.resources import Resource
+from opentelemetry.instrumentation.flask import FlaskInstrumentor
+from opentelemetry.instrumentation.requests import RequestsInstrumentor
+
+resource = Resource.create({"service.name": "my-service", "service.version": "1.0.0"})
+provider = TracerProvider(resource=resource)
+provider.add_span_processor(BatchSpanProcessor(OTLPSpanExporter()))
+trace.set_tracer_provider(provider)
+
+FlaskInstrumentor().instrument()
+RequestsInstrumentor().instrument()
+```
+
+## Auto-instrumentation coverage
+
+| Library                              | What it captures                                             |
+| ------------------------------------ | ------------------------------------------------------------ |
+| HTTP server (Express, Flask, etc.)   | Inbound request spans with method, route, status             |
+| HTTP client (fetch, axios, requests) | Outbound request spans with URL, status, duration            |
+| Database (pg, mysql2, pymongo)       | Query spans with statement, parameters (sanitized), duration |
+| Message queues (amqplib, kafkajs)    | Produce/consume spans with topic, partition, offset          |
+| gRPC                                 | Client and server call spans with method, status             |
+
+## Custom span creation
+
+```typescript
+import { trace } from "@opentelemetry/api";
+
+const tracer = trace.getTracer("my-service");
+
+async function processOrder(orderId: string) {
+  return tracer.startActiveSpan("process-order", async (span) => {
+    span.setAttribute("order.id", orderId);
+    try {
+      const result = await chargePayment(orderId);
+      span.setAttribute("order.status", "completed");
+      return result;
+    } catch (error) {
+      span.recordException(error as Error);
+      span.setStatus({ code: 2, message: (error as Error).message });
+      throw error;
+    } finally {
+      span.end();
+    }
+  });
+}
+```
+
+## Sampling strategy
+
+- **Development**: 100% sampling — capture everything.
+- **Staging**: 100% sampling — reproduce production-like trace volume.
+- **Production**:
+  - Always sample errors and slow requests (tail-based sampling).
+  - Sample 1-10% of successful requests depending on volume.
+  - Use parent-based sampling to preserve complete traces.
+
+## Exporter configuration
+
+| Backend       | Protocol  | Endpoint pattern               |
+| ------------- | --------- | ------------------------------ |
+| Jaeger        | OTLP/gRPC | `http://jaeger:4317`           |
+| Grafana Tempo | OTLP/HTTP | `http://tempo:4318/v1/traces`  |
+| Datadog       | OTLP/gRPC | `http://datadog-agent:4317`    |
+| Honeycomb     | OTLP/gRPC | `https://api.honeycomb.io:443` |
+
+Set via `OTEL_EXPORTER_OTLP_ENDPOINT` environment variable for portability.
+
+## Context propagation
+
+- Use W3C Trace Context (`traceparent`, `tracestate` headers) — this is the default in OTel.
+- Ensure all HTTP clients and servers propagate context headers.
+- For message queues, inject trace context into message headers/attributes.
+- For background jobs, pass trace parent as a job metadata field.

package/workflows/workflows/agent-environment-setup/platforms/claude/skills/openai-docs/SKILL.md

@@ -0,0 +1,58 @@
+---
+name: openai-docs
+description: "Use when the task depends on current OpenAI platform or product documentation: API usage, model behavior, tool features, SDK guidance, or version-sensitive OpenAI docs that should be verified from official sources."
+license: MIT
+metadata:
+  author: cubis-foundry
+  version: "1.0"
+compatibility: Claude Code, Codex, GitHub Copilot
+---
+
+# OpenAI Docs
+
+## Purpose
+
+You are the specialist for current OpenAI documentation lookup and citation discipline.
+
+Your job is to force official-source verification when OpenAI guidance may be stale, version-sensitive, or product-specific.
+
+## When to Use
+
+- The task depends on current OpenAI docs, product behavior, SDK guidance, or API surface.
+- The user asks for latest OpenAI information, official docs, or source-backed answers.
+- Version-sensitive or product-specific OpenAI behavior materially affects the answer.
+
+## Instructions
+
+### STANDARD OPERATING PROCEDURE (SOP)
+
+1. Identify the exact OpenAI surface in question.
+2. Prefer official OpenAI documentation and official OpenAI repos first.
+3. Cite the current source rather than relying on recalled behavior.
+4. Separate documented facts from inference.
+5. State uncertainty if the docs do not fully answer the question.
+
+### Constraints
+
+- Do not answer OpenAI product questions from memory when current docs are needed.
+- Do not use community summaries as primary sources when official docs exist.
+- Do not broaden into general web research when the task is specifically OpenAI guidance.
+
+## Output Format
+
+Provide implementation guidance, code examples, and configuration as appropriate to the task.
+
+## References
+
+| File                                     | Load when                                                                       |
+| ---------------------------------------- | ------------------------------------------------------------------------------- |
+| `references/official-source-playbook.md` | You need the source-selection and citation rules for OpenAI documentation work. |
+
+## Scripts
+
+No helper scripts are required for this skill right now. Keep execution in `SKILL.md` and `references/` unless repeated automation becomes necessary.
+
+## Examples
+
+- "Help me with openai docs best practices in this project"
+- "Review my openai docs implementation for issues"

package/workflows/workflows/agent-environment-setup/platforms/claude/skills/openai-docs/references/official-source-playbook.md

@@ -0,0 +1,10 @@
+# Official Source Playbook
+
+Load this when answering OpenAI-specific questions or refreshing OpenAI-facing skills.
+
+## Source Rules
+
+- Prefer official OpenAI docs and official OpenAI repos first.
+- Use community material only when it adds context the official docs do not cover.
+- Mark inferences clearly when the source does not state something outright.
+- If current product behavior may have changed, verify before answering.

package/workflows/workflows/agent-environment-setup/platforms/claude/skills/performance-profiling/SKILL.md

@@ -1,143 +1,90 @@
 ---
 name: performance-profiling
-description: Performance profiling principles. Measurement, analysis, and optimization techniques.
-allowed-tools: Read, Glob, Grep, Bash
+description: "Use when measuring, analyzing, and optimizing application performance with Core Web Vitals, bundle analysis, runtime profiling, and lighthouse audits."
+license: MIT
+metadata:
+  author: cubis-foundry
+  version: "1.0"
+compatibility: Claude Code, Codex, GitHub Copilot
 ---
 
 # Performance Profiling
 
-> Measure, analyze, optimize - in that order.
+## Purpose
 
-## 🔧 Runtime Scripts
+Use when measuring, analyzing, and optimizing application performance with Core Web Vitals, bundle analysis, runtime profiling, and lighthouse audits.
 
-**Execute these for automated profiling:**
+## When to Use
 
-| Script | Purpose | Usage |
-|--------|---------|-------|
-| `scripts/lighthouse_audit.py` | Lighthouse performance audit | `python scripts/lighthouse_audit.py https://example.com` |
+- Measuring and improving Core Web Vitals (LCP, INP, CLS).
+- Analyzing bundle size, finding large dependencies, and code splitting.
+- Profiling runtime performance in browser Performance or Memory tabs.
+- Diagnosing performance bottlenecks (slow API, large payload, memory leak, layout thrash).
+- Planning performance optimization with measurement-first discipline.
 
----
-
-## 1. Core Web Vitals
-
-### Targets
-
-| Metric | Good | Poor | Measures |
-|--------|------|------|----------|
-| **LCP** | < 2.5s | > 4.0s | Loading |
-| **INP** | < 200ms | > 500ms | Interactivity |
-| **CLS** | < 0.1 | > 0.25 | Stability |
-
-### When to Measure
-
-| Stage | Tool |
-|-------|------|
-| Development | Local Lighthouse |
-| CI/CD | Lighthouse CI |
-| Production | RUM (Real User Monitoring) |
-
----
-
-## 2. Profiling Workflow
-
-### The 4-Step Process
-
-```
-1. BASELINE → Measure current state
-2. IDENTIFY → Find the bottleneck
-3. FIX → Make targeted change
-4. VALIDATE → Confirm improvement
-```
-
-### Profiling Tool Selection
+## Instructions
 
-| Problem | Tool |
-|---------|------|
-| Page load | Lighthouse |
-| Bundle size | Bundle analyzer |
-| Runtime | DevTools Performance |
-| Memory | DevTools Memory |
-| Network | DevTools Network |
+1. Baseline — measure current performance with Lighthouse, WebPageTest, or browser DevTools.
+2. Identify — find the biggest bottleneck using profiling data, not assumptions.
+3. Fix — apply targeted optimization for the measured bottleneck.
+4. Validate — re-measure to confirm improvement and check for regressions.
 
----
-
-## 3. Bundle Analysis
-
-### What to Look For
-
-| Issue | Indicator |
-|-------|-----------|
-| Large dependencies | Top of bundle |
-| Duplicate code | Multiple chunks |
-| Unused code | Low coverage |
-| Missing splits | Single large chunk |
-
-### Optimization Actions
-
-| Finding | Action |
-|---------|--------|
-| Big library | Import specific modules |
-| Duplicate deps | Dedupe, update versions |
-| Route in main | Code split |
-| Unused exports | Tree shake |
+### Core Web Vitals targets
 
----
-
-## 4. Runtime Profiling
+| Metric | Good    | Needs Improvement | Poor    |
+| ------ | ------- | ----------------- | ------- |
+| LCP    | < 2.5s  | 2.5s – 4.0s       | > 4.0s  |
+| INP    | < 200ms | 200ms – 500ms     | > 500ms |
+| CLS    | < 0.1   | 0.1 – 0.25        | > 0.25  |
 
-### Performance Tab Analysis
+### Baseline standards
 
-| Pattern | Meaning |
-|---------|---------|
-| Long tasks (>50ms) | UI blocking |
-| Many small tasks | Possible batching opportunity |
-| Layout/paint | Rendering bottleneck |
-| Script | JavaScript execution |
+- Always measure before optimizing — intuition is unreliable for performance.
+- Use real user metrics (RUM) alongside synthetic benchmarks.
+- Profile on representative hardware, not just developer machines.
+- Address the largest bottleneck first for maximum impact.
+- Verify optimizations don't introduce regressions elsewhere.
 
-### Memory Tab Analysis
+### Quick wins priority
 
-| Pattern | Meaning |
-|---------|---------|
-| Growing heap | Possible leak |
-| Large retained | Check references |
-| Detached DOM | Not cleaned up |
+| Priority | Action                           | Typical Impact            |
+| -------- | -------------------------------- | ------------------------- |
+| 1        | Enable compression (gzip/brotli) | 60-80% transfer reduction |
+| 2        | Lazy load below-fold images      | LCP improvement           |
+| 3        | Code split routes                | Initial load reduction    |
+| 4        | Set proper cache headers         | Repeat visit speed        |
+| 5        | Optimize images (WebP/AVIF)      | Transfer size reduction   |
 
----
+### Common bottlenecks by symptom
 
-## 5. Common Bottlenecks
+| Symptom           | Likely Cause                            | Investigation                      |
+| ----------------- | --------------------------------------- | ---------------------------------- |
+| Slow initial load | Large bundle, render-blocking resources | Bundle analysis, waterfall         |
+| Janky scrolling   | Layout thrash, paint storms             | Performance tab, layers panel      |
+| Memory growth     | Detached DOM, event listener leaks      | Memory tab, heap snapshots         |
+| Slow interaction  | Long tasks, main thread blocking        | Performance tab, long task markers |
 
-### By Symptom
+### Constraints
 
-| Symptom | Likely Cause |
-|---------|--------------|
-| Slow initial load | Large JS, render blocking |
-| Slow interactions | Heavy event handlers |
-| Jank during scroll | Layout thrashing |
-| Growing memory | Leaks, retained refs |
+- Never optimize without measuring first.
+- Never assume a change improved performance — always validate with data.
+- Never sacrifice correctness for performance.
+- Avoid premature optimization of code paths that aren't bottlenecks.
 
----
+## Output Format
 
-## 6. Quick Win Priorities
+Provide measurement data, identified bottlenecks with evidence, optimization recommendations, and before/after comparisons.
 
-| Priority | Action | Impact |
-|----------|--------|--------|
-| 1 | Enable compression | High |
-| 2 | Lazy load images | High |
-| 3 | Code split routes | High |
-| 4 | Cache static assets | Medium |
-| 5 | Optimize images | Medium |
+## References
 
----
+No reference files for this skill right now.
 
-## 7. Anti-Patterns
+## Scripts
 
-| ❌ Don't | ✅ Do |
-|----------|-------|
-| Guess at problems | Profile first |
-| Micro-optimize | Fix biggest issue |
-| Optimize early | Optimize when needed |
-| Ignore real users | Use RUM data |
+No helper scripts are required for this skill right now.
 
----
+## Examples
 
-> **Remember:** The fastest code is code that doesn't run. Remove before optimizing.
+- "Profile and optimize the Core Web Vitals for our landing page"
+- "Analyze our bundle and recommend code splitting strategy"
+- "Find and fix the memory leak in our real-time dashboard"