@cubis/foundry 0.3.70 → 0.3.72

package/workflows/powers/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/powers/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/powers/openai-docs/POWER.md

@@ -0,0 +1,61 @@
+````markdown
+---
+inclusion: manual
+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/powers/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/powers/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/powers/performance-profiling/POWER.md

@@ -2,145 +2,92 @@
 ---
 inclusion: manual
 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"
 ````