@ketecode/loom 0.1.0 → 0.2.0

package/skills/network-design/SKILL.md

@@ -0,0 +1,98 @@
+---
+name: network-design
+description: Produces a vendor-neutral design for an enterprise campus or multi-site network before anything is configured, from requirements and an aggregatable IPv4 and IPv6 addressing plan through OSPF area layout, the BGP edge to ISPs, VLANs, VRFs and segmentation zones, first-hop redundancy and dual uplinks, WAN or SD-WAN topology, and a staged cutover plan with rollback points and validation tests. Use when planning a new office, data centre or branch network, redesigning a flat or outgrown network, merging two company networks, choosing between MPLS, internet VPN and SD-WAN, or writing the migration plan for a network change that must not cause an outage.
+license: MIT
+compatibility: Any Agent Skills host. Produces design documents and plans; no device access needed. Device configuration belongs to the vendor or automation skills.
+metadata:
+  kete-loom/version: "0.1.0"
+  kete-loom/category: devops
+  kete-loom/risk: read-only
+  kete-loom/owner: "Kete-org"
+---
+
+# Network design
+
+Turn requirements into a network design someone can build and migrate to safely. This skill decides what the network should be. Typing the config is for the Cisco IOS or network automation skills, diagnosing faults is for network troubleshooting or BGP diagnostics, and a home lab is for the homelab skill.
+
+## 0. Gather requirements (stop and ask for anything missing)
+
+Write down, per site: users and devices now and in three years, critical applications and where they run (on site, data centre, cloud), required uptime, existing hardware and contracts, ISPs and circuits, compliance zones (card data, OT/industrial, guest), and the team's operational skills. Ask for the existing addressing and any overlapping ranges from partners or acquired companies.
+
+Do not design until you know the growth figure, the uptime target and which systems must be isolated.
+
+## 1. Addressing plan
+
+1. Pick a private IPv4 supernet per organisation from RFC 1918 (`10.0.0.0/8`, `172.16.0.0/12`, `192.168.0.0/16`) and give each site one contiguous block so it summarises to a single route (for example `10.<site>.0.0/16`). Avoid `192.168.0.0/24` and `192.168.1.0/24` (home VPN clashes) and anything a partner or cloud VPC already uses.
+2. Inside a site, carve by function in fixed positions so every site looks alike: infrastructure (loopbacks `/32`, point-to-points `/31` per RFC 3021), management, users, voice, wireless, servers, IoT, guest.
+3. Size each subnet for the three-year count plus 30 to 50 percent; prefer `/24` for user VLANs for readability unless hosts exceed it.
+4. IPv6: get a provider-independent or provider-assigned prefix, give each site a `/48` (or `/56` for small sites), each VLAN a `/64`. Map the VLAN ID into the IPv6 subnet ID where it fits so addresses are readable.
+5. Reserve blocks for future sites and for NAT, VPN client pools and cloud.
+6. Record the plan as a table: site, function, VLAN ID, IPv4 prefix, IPv6 prefix, gateway, DHCP scope, zone.
+
+## 2. Routing design
+
+- **Interior:** use OSPF (or IS-IS) with area 0 as the backbone. Put each site or region in its own area attached to area 0, and summarise at the area border routers. Use stub or totally stubby areas for branches with one way out. Keep area 0 small and contiguous.
+- **Static routes** only for stub edges with no alternative path, and always with a tracked next hop or floating backup.
+- **BGP edge:** needs your own public ASN and provider-independent (or ISP-assigned and portable) address space; without them, use each ISP's default route with tracked failover and NAT per ISP, and ask the user before planning an ASN or PI request. With them: eBGP to each ISP. Advertise only your own aggregates (inbound and outbound prefix lists, max-prefix limits), register ROAs for RPKI, use local preference to choose the primary exit and AS-path prepending or provider communities to steer inbound traffic. Take default routes, or full tables only if the routers have the memory and you need the path choice. Use iBGP between edge routers.
+- **Cloud and partners:** BGP over IPsec or the provider's private interconnect; filter what each side may send.
+- Make the failure behaviour explicit: for each link and device, write which path traffic takes when it fails and how long convergence takes (BFD where sub-second matters).
+
+## 3. Layer 2 and segmentation
+
+1. Use a collapsed core (core plus access) for one building, three tiers (core, distribution, access) for campuses. Route at the distribution or core; keep VLANs local to an access block, never stretched across the campus or between sites without a clear need (and then use EVPN/VXLAN, not spanning tree across a WAN).
+2. One VLAN per function per access block. Disable unused ports into a parking VLAN; never carry user traffic on VLAN 1; native VLAN unused.
+3. Spanning tree: rapid PVST+ or MST, root bridge pinned on the distribution pair, BPDU guard on edge ports.
+4. Segment by zone (users, servers, management, guest, IoT, card data, OT) with VRFs or firewall zones. Write the inter-zone policy as a matrix (source zone, destination zone, allowed services) with default deny.
+5. Management network out of band or in its own VRF; only jump hosts reach it.
+6. Port security with 802.1X/NAC where the organisation can operate it; otherwise MAC limits and DHCP snooping with dynamic ARP inspection.
+
+## 4. Redundancy
+
+- Gateways: a first-hop redundancy protocol (VRRP per RFC 5798 is the open standard; HSRP or GLBP on Cisco) or an active-active design such as anycast gateways in EVPN, or multi-chassis link aggregation (vPC, MLAG, StackWise Virtual) with LACP uplinks.
+- Every access switch dual-homed to two distribution switches; every distribution switch to two core switches.
+- Two ISPs with different physical paths into the building, on two edge routers and two firewalls in an HA pair.
+- Power: dual PSUs on separate feeds, UPS for core, edge and wireless controllers.
+- Write down single points of failure that remain and why they are accepted.
+
+## 5. WAN and SD-WAN
+
+| Option | Choose when |
+|---|---|
+| MPLS L3VPN | strict latency or SLA needs, carrier-managed QoS, budget allows |
+| Internet with IPsec (hub and spoke or full mesh) | few sites, cost first, team can run VPNs |
+| SD-WAN | many sites, mixed circuits (broadband, LTE/5G, MPLS), need application-aware path choice and central policy |
+
+For SD-WAN: two transports per important site, central controller design and its failure mode, local internet breakout with security (SSE/firewall), QoS classes for voice and critical apps, and how SD-WAN routes are redistributed into OSPF/BGP without loops (tags, filters). Confirm vendor features and licensing with the vendor; do not assume them.
+
+## 6. Migration plan
+
+Write a staged plan. Every stage has: scope, prerequisites, a maintenance window, exact steps, validation tests, a go/no-go decision, and a rollback that is tested and timed.
+
+1. Stage 0: document the current state (configs backed up, current routing tables and traffic baselines captured).
+2. Build the new core or edge in parallel where possible; connect it with a temporary routed link.
+3. Move one low-risk segment or pilot site first; run it for a defined soak period.
+4. Move remaining segments in batches, critical systems last, never all in one window.
+5. Decommission old paths only after the soak and after removing their routes.
+6. Rollback triggers: name them up front (for example, a critical app unreachable for 5 minutes, routing table size off by more than 10 percent).
+
+Validation per stage: reachability between every zone pair the policy allows (and denial for the ones it blocks), gateway failover by shutting one device, ISP failover, DNS and DHCP from each VLAN, application tests by their owners.
+
+## Never
+
+- Never reuse an address range that overlaps another site, partner or cloud network.
+- Never advertise more than your own aggregates to an ISP or accept routes without filters.
+- Never plan a cutover without a tested rollback and a named person who decides go or no-go.
+- Never stretch Layer 2 between sites to avoid re-addressing without the user accepting the risk.
+
+## Report back
+
+```
+Requirements and assumptions: <list, with what the user still has to confirm>
+Addressing plan: <table>
+Routing: <IGP areas, BGP edge, failure paths>
+Segmentation: <zones, VRFs, policy matrix>
+Redundancy: <per layer; remaining single points of failure>
+WAN: <choice and why>
+Migration: <stages with validation and rollback>
+Risks and open questions: <list>
+```

package/skills/network-design/evals/triggers.json

@@ -0,0 +1,16 @@
+{
+  "should_trigger": [
+    "Design the network for our new three-floor office and two branches: addressing, VLANs, routing and redundancy",
+    "We acquired a company whose 10.0.0.0/16 overlaps ours, plan how to merge the two networks",
+    "Should our 40 retail sites use MPLS, IPsec over broadband, or SD-WAN? Lay out the trade-offs",
+    "Write a staged migration plan with rollback for moving our flat /16 network to segmented VLANs and VRFs",
+    "Plan the OSPF area layout and the BGP edge to two ISPs for our campus and data centre"
+  ],
+  "should_not_trigger": [
+    "Our BGP session with the ISP keeps flapping between Active and Idle, why?",
+    "Give me the IOS commands to configure a trunk port on a Catalyst 9300",
+    "Write an Ansible playbook to push NTP config to 200 switches",
+    "Set up VLANs for IoT devices on my home lab with a Pi-hole",
+    "Users at the branch can't reach the file server, it times out"
+  ]
+}

package/skills/observability/SKILL.md

@@ -0,0 +1,125 @@
+---
+name: observability
+description: OpenTelemetry-first service instrumentation that adds structured JSON logs carrying trace IDs, RED metrics with bounded-cardinality labels and distributed traces (SDK and exporter setup, semantic conventions, W3C traceparent propagation, head and tail sampling), then turns them into SLIs, SLOs, multi-window burn-rate alerts and on-call dashboards in Grafana, Prometheus or a vendor backend. Use when instrumenting a service with OpenTelemetry, traces break across service hops, logs cannot be joined to a request, defining an SLO or error budget, replacing noisy threshold alerts with burn-rate alerts, or building the operational board on-call opens first.
+license: MIT
+compatibility: Any Agent Skills host. Works with any OpenTelemetry SDK (Java, Python, Go, Node, .NET and others) and any OTLP backend; examples use Prometheus query syntax and Grafana.
+metadata:
+  kete-loom/version: "0.1.0"
+  kete-loom/category: devops
+  kete-loom/risk: writes-files
+  kete-loom/owner: "Kete-org"
+---
+
+# Observability
+
+Make every request answerable: which one failed, where it spent its time, and whether users are hurting enough to wake someone. Logs, metrics and traces share one resource identity and one trace ID, and alerts fire on user-facing SLO burn, not on CPU.
+
+This skill is for operational telemetry. Business KPI boards belong to `metrics-dashboards`; what the on-call person does once paged belongs to `runbook-writing`.
+
+## 0. Before you start
+
+1. Find what is already there: search for `opentelemetry`, `prometheus`, `statsd`, `datadog`, `newrelic`, `logging.basicConfig`, `winston`, `zap`, `slog`, `logback`. Keep one telemetry stack; do not add a second SDK beside an existing one.
+2. Find the backend: an OpenTelemetry Collector, Grafana stack (Tempo, Loki, Mimir or Prometheus), or a vendor. If none exists and the user has not picked one, **stop and ask**; the backend decides exporters and query syntax.
+3. List the service's entry points (HTTP routes, queue consumers, cron jobs) and its outbound calls (databases, HTTP clients, queues). These are where spans and metrics go.
+
+## 1. Resource identity
+
+Set these once, through environment variables so every signal shares them:
+
+- `OTEL_SERVICE_NAME` (required; the same name in logs, metrics and traces)
+- `OTEL_RESOURCE_ATTRIBUTES=service.version=<git sha or release>,deployment.environment.name=<env>`
+- `OTEL_EXPORTER_OTLP_ENDPOINT` pointing at the Collector, not straight at a vendor, so sampling and routing can change without a redeploy.
+
+Per-language SDK bootstrap and Collector config are in `references/otel-setup.md`.
+
+## 2. Traces
+
+1. Prefer the language's auto-instrumentation (HTTP server and client, database drivers, messaging) before writing manual spans.
+2. Add manual spans only around meaningful units of work the auto layer cannot see (a pricing calculation, a batch step). Name spans by operation, low cardinality: `GET /orders/{id}`, never `GET /orders/8812`.
+3. Use the semantic conventions for attributes (`http.request.method`, `http.route`, `http.response.status_code`, `db.system.name`, `server.address`); custom attributes get your own namespace (`app.order.tier`).
+4. Record errors: set span status to error and record the exception on the span that failed.
+5. Propagation: W3C `traceparent`/`tracestate` is the default. Check every hop: async queues need the context injected into message headers and extracted in the consumer; thread pools and background tasks need the context carried explicitly.
+6. Sampling:
+   - Start with `OTEL_TRACES_SAMPLER=parentbased_traceidratio` and `OTEL_TRACES_SAMPLER_ARG` (for example `0.1`) so children follow the root's decision.
+   - To keep all errors and slow requests, do tail sampling in the Collector (`tail_sampling` processor), and make sure all spans of a trace reach the same Collector instance.
+   - Never sample metrics. Rates come from metrics, not from sampled traces.
+
+## 3. Metrics
+
+1. Per entry point, emit RED: request rate, errors, duration as a histogram (`http.server.request.duration` in seconds from auto-instrumentation, or your own). Per dependency, the same on the client side. Per queue: depth and age of oldest message.
+2. Labels must be bounded. Never put user IDs, emails, raw URLs, order IDs or error messages in a label. Use the route template and the status code class.
+3. A latency SLI counts requests under the threshold, so the histogram needs a bucket boundary exactly at it. The default OpenTelemetry HTTP buckets are 0.005, 0.01, 0.025, 0.05, 0.075, 0.1, 0.25, 0.5, 0.75, 1, 2.5, 5, 7.5, 10 s: pick an SLO threshold on one of them, or add the boundary with a metrics view (or use exponential histograms if the backend supports them).
+4. Add saturation for whatever runs out first: connection pool in use, worker queue, memory against limit.
+
+## 4. Logs
+
+1. Structured JSON, one event per line, to stdout. Fields: `timestamp`, `severity`, `message`, `service.name`, `trace_id`, `span_id`, plus event fields.
+2. Inject `trace_id`/`span_id` with the SDK's log bridge or logging instrumentation, so a log line links to its trace.
+3. Log events, not narration: one line per failed operation with its cause and inputs that are safe to log. Never log secrets, tokens, passwords, full card numbers or request bodies containing personal data; redact at the logger, not at query time.
+4. Default level INFO in production; DEBUG behind a runtime switch.
+
+## 5. SLIs and SLOs
+
+1. Pick 1 to 3 SLIs per user journey, each a ratio of good events to valid events:
+   - Availability: non-5xx responses / all responses (decide whether 429 and 4xx count; write it down).
+   - Latency: requests faster than the threshold / all requests, measured at the edge closest to the user you can instrument.
+2. Set the SLO target with the owner (for example 99.9% over 28 or 30 days). **Stop and ask** if no one owns the number; never invent a target.
+3. Error budget = 1 − target. Write the SLO as a file in the repo (definition, query, window, owner, what happens when the budget is spent).
+
+## 6. Burn-rate alerts
+
+Page on how fast the budget burns, using a long and a short window together so alerts fire fast and reset fast. The standard pairs for a 30-day SLO (from the Google SRE Workbook):
+
+| Severity | Long window | Short window | Burn rate | Budget spent at trigger |
+|---|---|---|---|---|
+| Page | 1h | 5m | 14.4 | 2% |
+| Page | 6h | 30m | 6 | 5% |
+| Ticket | 3d | 6h | 1 | 10% |
+
+Query templates (Prometheus recording rules and alert rules) are in `references/slo-alerts.md`.
+
+Alert rules:
+
+- Every paging alert links to a runbook and a dashboard.
+- Remove or demote cause-based alerts (CPU, memory, single pod restart) to tickets unless they predict an SLO breach no other alert catches.
+- Low-traffic services: burn-rate alerts flap on few requests; add a minimum request count or use synthetic probes.
+
+## 7. On-call dashboard
+
+One board per service, top to bottom:
+
+1. SLO status and remaining error budget, with the burn rate.
+2. RED for the entry points: rate, error ratio, p50/p95/p99 latency.
+3. Dependencies: the same RED, client side, per dependency.
+4. Saturation: pools, queues, memory and CPU against limits.
+5. Deploy and feature-flag annotations on every time series.
+6. Links: logs filtered to the service, trace search, runbook.
+
+Use template variables for environment and instance; keep it under about 20 panels. Panel and query guidance is in `references/slo-alerts.md`.
+
+## 8. Verify
+
+1. Run the service locally or in a test environment with the Collector's `debug` exporter (or the backend) and send a request.
+2. Confirm: one trace spans every hop, including through a queue; the log line for that request carries the same `trace_id`; the RED metrics appear with only bounded labels.
+3. Evaluate each alert expression against recent data and check it would not have fired continuously.
+
+## Never
+
+- Never put unbounded values in metric labels or span names.
+- Never log secrets or personal data, or ship telemetry to a third party the user has not approved.
+- Never page on a symptom with no user impact and no runbook.
+- Never set an SLO target without an owner agreeing to it.
+
+## Report back
+
+```
+## Observability: <service>
+Instrumented: <entry points, dependencies, signals>
+Resource: service.name=<>, version source, environment
+Sampling: <head ratio, tail policy>
+SLOs: <SLI, target, window> per journey
+Alerts: <name, windows, burn rate, runbook link>
+Dashboard: <file or URL>
+Verified: <trace across hops yes/no, logs joined yes/no, alert dry run>
+Open questions: <owner, targets, backend>
+```

package/skills/observability/evals/triggers.json

@@ -0,0 +1,17 @@
+{
+  "should_trigger": [
+    "Add OpenTelemetry tracing to our Python and Go services and send it to a Collector",
+    "Our traces stop at the Kafka consumer, the span context isn't carried across the queue. Fix the propagation.",
+    "Define an availability SLO for the checkout API and write multi-window burn-rate alerts in Prometheus",
+    "Build the Grafana board on-call should open first when the payments service pages",
+    "Our log lines can't be matched to a request; add trace_id and span_id to the JSON logs",
+    "We get paged for CPU spikes nobody cares about, replace them with error budget alerts"
+  ],
+  "should_not_trigger": [
+    "Design a KPI dashboard for the sales team showing monthly recurring revenue and churn",
+    "Write a runbook for the HighErrorRate alert with diagnosis steps and escalation contacts",
+    "Write a blameless postmortem for yesterday's database outage",
+    "Plan a canary rollout with automatic rollback for the new pricing service",
+    "Set up a Helm chart and liveness probes for our API on Kubernetes"
+  ]
+}

package/skills/observability/references/otel-setup.md

@@ -0,0 +1,87 @@
+# OpenTelemetry setup
+
+Read this when bootstrapping an SDK or a Collector. Package names and flags move between releases: check the language's page under opentelemetry.io/docs/languages/ for the current version before pinning.
+
+## Standard environment variables
+
+| Variable | Example | Notes |
+|---|---|---|
+| `OTEL_SERVICE_NAME` | `checkout-api` | Same name in every signal |
+| `OTEL_RESOURCE_ATTRIBUTES` | `service.version=4f2c1a9,deployment.environment.name=prod` | Comma-separated key=value |
+| `OTEL_EXPORTER_OTLP_ENDPOINT` | `http://otel-collector:4318` | 4317 gRPC, 4318 HTTP |
+| `OTEL_EXPORTER_OTLP_PROTOCOL` | `http/protobuf` | or `grpc` |
+| `OTEL_TRACES_SAMPLER` | `parentbased_traceidratio` | |
+| `OTEL_TRACES_SAMPLER_ARG` | `0.1` | Ratio for the root sampler |
+| `OTEL_PROPAGATORS` | `tracecontext,baggage` | The default |
+
+## Auto-instrumentation by language
+
+- **Java**: attach the agent, `java -javaagent:opentelemetry-javaagent.jar -jar app.jar`.
+- **Python**: `pip install opentelemetry-distro opentelemetry-exporter-otlp`, then `opentelemetry-bootstrap -a install`, run with `opentelemetry-instrument python app.py`.
+- **Node.js**: `npm install @opentelemetry/sdk-node @opentelemetry/auto-instrumentations-node`, start with `node --require @opentelemetry/auto-instrumentations-node/register app.js` (the SDK must load before the app's own imports).
+- **.NET**: the `OpenTelemetry.Extensions.Hosting` package plus `OpenTelemetry.Instrumentation.AspNetCore` and `.Http`, registered with `services.AddOpenTelemetry().WithTracing(...).WithMetrics(...)`; or the zero-code automatic instrumentation.
+- **Go**: no agent; wire `otelhttp` handlers and transports and the `otel/sdk` trace and metric providers in `main`, and call `Shutdown` on exit so the last spans flush.
+
+Flush on shutdown in every language; short-lived jobs lose their spans otherwise.
+
+## Manual span (pattern)
+
+```python
+from opentelemetry import trace
+tracer = trace.get_tracer("app.pricing")
+
+with tracer.start_as_current_span("price_quote") as span:
+    span.set_attribute("app.quote.items", len(items))
+    try:
+        quote = compute(items)
+    except Exception as exc:
+        span.record_exception(exc)
+        span.set_status(trace.Status(trace.StatusCode.ERROR))
+        raise
+```
+
+## Propagating through a queue
+
+Producer: `propagate.inject(headers)` into the message headers. Consumer: `ctx = propagate.extract(headers)` and start the consumer span with that context (as a child, or as a new trace with a span link for batch consumers).
+
+## Minimal Collector config
+
+```yaml
+receivers:
+  otlp:
+    protocols:
+      grpc:
+        endpoint: 0.0.0.0:4317
+      http:
+        endpoint: 0.0.0.0:4318
+processors:
+  memory_limiter:
+    check_interval: 1s
+    limit_percentage: 80
+  batch: {}
+  tail_sampling:
+    decision_wait: 10s
+    policies:
+      - name: errors
+        type: status_code
+        status_code: { status_codes: [ERROR] }
+      - name: slow
+        type: latency
+        latency: { threshold_ms: 1000 }
+      - name: baseline
+        type: probabilistic
+        probabilistic: { sampling_percentage: 10 }
+exporters:
+  debug: {}
+  otlp:
+    endpoint: tempo:4317
+    tls: { insecure: true }   # only inside a private network
+service:
+  pipelines:
+    traces:
+      receivers: [otlp]
+      processors: [memory_limiter, tail_sampling, batch]
+      exporters: [otlp]
+```
+
+`tail_sampling` ships in the Collector contrib distribution, not core. With several Collector replicas, route by trace ID (the `loadbalancing` exporter) in a first tier so one instance sees the whole trace.

package/skills/observability/references/slo-alerts.md

@@ -0,0 +1,70 @@
+# SLO queries, burn-rate alerts and dashboard panels
+
+Read this when writing recording rules, alert rules or dashboard queries. Metric names below assume OpenTelemetry HTTP server metrics exported to Prometheus (`http_server_request_duration_seconds_*`); rename to what the service actually exposes. When OTLP metrics reach Prometheus, `service.name` becomes the `job` label (`<service.namespace>/<service.name>` if a namespace is set) and `service.instance.id` becomes `instance`; resource attributes are not copied to labels unless the exporter is configured to (for example `resource_to_telemetry_conversion` or `target_info` joins). Check the real label names in the backend before writing rules.
+
+## Recording rules (availability SLI)
+
+```yaml
+groups:
+  - name: slo-checkout
+    rules:
+      - record: slo:errors:ratio_rate5m
+        expr: |
+          sum(rate(http_server_request_duration_seconds_count{job="checkout-api",http_response_status_code=~"5.."}[5m]))
+          /
+          sum(rate(http_server_request_duration_seconds_count{job="checkout-api"}[5m]))
+      # repeat with [30m], [1h], [6h], [3d] and [30d] as slo:errors:ratio_rate30m, ... (the 30d one feeds the budget panel)
+```
+
+Latency SLI (good = faster than 0.25 s; the `le` value must be an existing bucket boundary, an approximate one silently measures a different threshold):
+
+```
+1 - (
+  sum(rate(http_server_request_duration_seconds_bucket{job="checkout-api",le="0.25"}[5m]))
+  /
+  sum(rate(http_server_request_duration_seconds_count{job="checkout-api"}[5m]))
+)
+```
+
+## Multi-window burn-rate alerts (SLO 99.9%, budget 0.001)
+
+```yaml
+      - alert: CheckoutErrorBudgetBurnFast
+        expr: |
+          slo:errors:ratio_rate1h > (14.4 * 0.001)
+          and
+          slo:errors:ratio_rate5m > (14.4 * 0.001)
+        labels: { severity: page }
+        annotations:
+          summary: "checkout-api burning error budget 14x"
+          runbook_url: "https://<runbooks>/checkout-api/error-budget"
+          dashboard: "https://<grafana>/d/checkout-api"
+      - alert: CheckoutErrorBudgetBurnMedium
+        expr: |
+          slo:errors:ratio_rate6h > (6 * 0.001)
+          and
+          slo:errors:ratio_rate30m > (6 * 0.001)
+        labels: { severity: page }
+      - alert: CheckoutErrorBudgetBurnSlow
+        expr: |
+          slo:errors:ratio_rate3d > (1 * 0.001)
+          and
+          slo:errors:ratio_rate6h > (1 * 0.001)
+        labels: { severity: ticket }
+```
+
+Burn rate = observed error ratio / error budget. A burn rate of 1 spends exactly the budget over the SLO window. Tools such as Sloth or Pyrra generate these rules from a short SLO spec; use one if the team already does.
+
+## Dashboard panels (Grafana)
+
+| Panel | Query sketch | Visual |
+|---|---|---|
+| Error budget remaining | `1 - (slo:errors:ratio_rate30d / 0.001)` | Stat, red under 25% |
+| Burn rate 1h | `slo:errors:ratio_rate1h / 0.001` | Stat with thresholds 1, 6, 14.4 |
+| Request rate | `sum by (http_route) (rate(..._count[5m]))` | Time series |
+| Error ratio | `sum by (http_route) (rate(..._count{http_response_status_code=~"5.."}[5m])) / sum by (http_route) (rate(..._count[5m]))` | Time series |
+| Latency p95/p99 | `histogram_quantile(0.99, sum by (le) (rate(..._bucket[5m])))` | Time series |
+| Dependency latency | same on `http_client_request_duration_seconds` by `server_address` | Time series |
+| Saturation | pool in use / pool max, queue depth | Time series with limit line |
+
+Add annotations from the deploy pipeline (Grafana annotations API or a `deployments` metric), and data links from latency panels to the trace backend filtered by service and time range. Keep dashboards as JSON in the repo, provisioned from files, so changes are reviewed.

package/skills/open-source-release/SKILL.md

@@ -0,0 +1,107 @@
+---
+name: open-source-release
+description: Takes a private or internal codebase public safely by scanning the working tree and full git history for secrets, personal data and internal hostnames with gitleaks and trufflehog, rewriting history with git filter-repo or starting a fresh history, choosing an outbound licence and checking third-party licence compatibility, adding README, CONTRIBUTING, SECURITY and CODE_OF_CONDUCT files and public CI, then walking a pre-publish checklist with explicit sign-off points. Use when someone wants to open-source an internal project, flip a private GitHub repository to public, or publish company code under an open licence for the first time.
+license: MIT
+compatibility: Any Agent Skills host. Needs git; secret scanning uses gitleaks or trufflehog, history rewriting uses git-filter-repo. Licence scanners depend on the ecosystem.
+metadata:
+  kete-loom/version: "0.1.0"
+  kete-loom/category: devops
+  kete-loom/risk: runs-commands
+  kete-loom/requires: "git, gitleaks, git-filter-repo"
+  kete-loom/owner: "Kete-org"
+---
+
+# Open-source release
+
+Make a private repository safe to publish. Once a repository is public, anything in its history is copied by forks, mirrors and scrapers within minutes, so every check happens **before** the visibility flip, and none of it can be undone afterwards.
+
+This skill is engineering preparation, not legal advice. The owner of the code (usually the employer) must approve the release and the licence; a lawyer or the company's open-source programme office should review licence and trademark questions.
+
+## 0. Stop and ask first
+
+Before doing any work, confirm with the user:
+
+1. Who owns the code and has approved publishing it (name the person or the approval record).
+2. Whether contributors outside the company ever committed (their rights matter for relicensing).
+3. Whether to **keep history** (rewrite and scrub it) or **publish a fresh history** (one squashed initial commit). A fresh history is the safest default for internal code; keep history only if the user wants it and the scan in step 1 is clean or fully remediated.
+
+Work in a **fresh clone** (`git clone --mirror` for scanning and rewriting history, a normal clone for the fresh-history route) so you never rewrite the team's working copy.
+
+**Publish to a new public repository by default** rather than flipping the existing private one to public. Flipping visibility also exposes everything attached to the repository: issues, pull requests and their review comments, wiki, releases, Actions logs and artifacts, and `refs/pull/*` commits that a history rewrite cannot remove. Flip the existing repository only if the user explicitly wants that and has reviewed all of it.
+
+## 1. Scan for secrets, personal data and internal details
+
+Scan the full history of every ref, not just the tip:
+
+- `gitleaks git -v --log-opts="--all" --report-path gitleaks-history.json .`
+- `gitleaks dir -v --report-path gitleaks-tree.json .` (working tree, including untracked files you plan to publish)
+- `trufflehog git file://<path-to-clone> --results=verified,unknown` (run from outside the repo; it tries keys against providers, so tell the user it makes network calls)
+
+Then search the codebase and history (`git log -p --all -S <term>` / `git grep`) for what scanners miss, including commit metadata (`git log --all --format='%an <%ae> %cn <%ce>' | sort -u` and commit messages), which can carry personal emails, ticket links and customer names:
+
+- internal hostnames and domains (`*.internal`, `*.corp`, `*.local`, VPN and intranet names), private IP ranges, cloud account and project IDs, S3 bucket names;
+- customer names, employee names and emails, phone numbers, real data in fixtures, seeds, test snapshots and screenshots;
+- committed `.env`, `*.pem`, `*.p12`, `id_rsa`, kubeconfig, `terraform.tfstate`, database dumps, `.npmrc`/`.pypirc` with tokens;
+- comments with security issues, incident details, unreleased product names, profanity about customers;
+- vendored proprietary code, internal packages pulled from a private registry, licensed fonts or images.
+
+Triage each hit as **live secret**, **dead secret**, **PII**, **internal detail** or **false positive**.
+
+## 2. Remediate
+
+1. **Rotate every real secret first**, live or "probably dead". Scrubbing history does not un-leak a key someone already copied. Record who rotated what.
+2. Remove PII and internal details from the current tree with normal commits.
+3. Then deal with history, following `references/history-scrub.md`:
+   - fresh history: copy the cleaned tree into a new repository with one initial commit;
+   - keep history: `git filter-repo --sensitive-data-removal --replace-text replacements.txt` and `--invert-paths --path <file>` for whole files; `--replace-message` for commit messages and `--mailmap` for author identities; then re-run every scan from step 1 until it is clean.
+4. Add the remaining false positives to a `.gitleaksignore` (fingerprints) so CI starts clean.
+
+## 3. Licence
+
+1. Ask the user which outbound licence the owner has chosen. If undecided, lay out the usual options without deciding for them: permissive (MIT, Apache-2.0 which adds an explicit patent grant, BSD-3-Clause), weak copyleft (MPL-2.0), strong copyleft (GPL-3.0, AGPL-3.0 for network services).
+2. Add the full licence text as `LICENSE` and an SPDX identifier in the package manifest (`"license": "Apache-2.0"`, `license = "MIT"`). Optional per-file `SPDX-License-Identifier` headers; `reuse lint` checks them if the project adopts REUSE.
+3. Inventory third-party licences with the ecosystem's tool (`references/history-scrub.md` lists them) and flag: no licence, unknown licence, copyleft dependencies incompatible with the chosen licence, and copied-in code whose origin is unclear. **Stop and ask** on any flag; a qualified person decides compatibility.
+4. If outside contributors will be accepted, ask whether the owner wants a DCO sign-off or a CLA. Don't pick one for them.
+
+## 4. Community and security files
+
+Add or update, matching the project's real process (never promise response times nobody agreed to):
+
+- `README.md`: what it is, status (experimental / stable), install, a working quick-start, how to run tests, licence.
+- `CONTRIBUTING.md`: dev setup, test and lint commands, branch and PR rules, DCO/CLA if any.
+- `SECURITY.md`: how to report a vulnerability privately (enable GitHub private vulnerability reporting, or a monitored address), supported versions. Ask the user for the contact.
+- `CODE_OF_CONDUCT.md`: usually the Contributor Covenant (3.0 is current); fill in a real enforcement contact the user gives you.
+- Issue and PR templates, `CODEOWNERS` if the team uses it.
+- Remove internal-only files: deploy scripts for company infrastructure, internal runbooks, `.github/workflows` that use self-hosted runners or internal secrets.
+
+## 5. Public CI
+
+- A workflow that builds, lints and tests on pull requests from forks, using no repository secrets on `pull_request` events.
+- A secret scan on every push and PR (gitleaks action or `gitleaks git` in a job).
+- Least-privilege `permissions:` on the token; for depth on workflow hardening use the `github-actions-ci` skill if installed.
+- Enable secret scanning and push protection, Dependabot or equivalent, and branch protection on the default branch.
+
+## 6. Pre-publish checklist
+
+Go through `references/history-scrub.md` "Final checklist" with the user. **Stop and ask for explicit sign-off** before:
+
+- force-pushing rewritten history anywhere;
+- creating the public repository or changing visibility to public;
+- publishing to a package registry.
+
+Never flip visibility yourself without that sign-off, and never publish while any scan finding is unresolved.
+
+## Report
+
+```
+## Open-source readiness: <repo>
+Approval: <who approved, or MISSING>
+History: fresh | rewritten (<tool>, first changed commit <sha>)
+Secrets: <n found> / <n rotated> / <n remaining>
+PII and internal details: <removed items, or none>
+Licence: <SPDX id> | third-party flags: <list or none>
+Files added: README, CONTRIBUTING, SECURITY, CODE_OF_CONDUCT, ...
+CI: <workflow names> | secret scan in CI: yes/no
+Blocking before publish: <list, or none>
+Needs human sign-off: <owner approval, licence review, visibility flip>
+```

package/skills/open-source-release/evals/triggers.json

@@ -0,0 +1,15 @@
+{
+  "should_trigger": [
+    "We want to open-source our internal CLI tool. What do we need to do before making the repo public?",
+    "Make sure there are no old API keys or internal hostnames anywhere in the git history before we flip this GitHub repo to public",
+    "Prepare this company project for its first public release under an open licence, with SECURITY.md and a code of conduct",
+    "Use git filter-repo to strip the customer data that was committed three years ago, then check we can publish the repo"
+  ],
+  "should_not_trigger": [
+    "Cut version 2.3.0 and write the release notes from the merged PRs",
+    "Scan the current change for vulnerabilities and leaked secrets before I push",
+    "Audit our npm dependencies for known CVEs and typosquatted packages",
+    "Rewrite the README so new users can get started faster",
+    "Squash my last five commits into one before I open the pull request"
+  ]
+}

package/skills/open-source-release/references/history-scrub.md

@@ -0,0 +1,65 @@
+# History scrubbing, licence tools and final checklist
+
+## Fresh history (safest)
+
+```sh
+git clone <private-url> work && cd work
+# after cleaning the tree and committing:
+rm -rf .git && git init -b main && git add -A
+gitleaks dir -v .            # must be clean before the first commit
+git commit -m "Initial public release"
+```
+
+Keep the private repository as the archive of old history.
+
+## Rewriting history with git filter-repo
+
+Rotate secrets before you start. Work in a fresh clone.
+
+`replacements.txt`, one expression per line (literal by default; `regex:` and `glob:` prefixes allowed; `==>` sets the replacement, otherwise matches become `***REMOVED***`):
+
+```
+AKIAEXAMPLEKEY==>REDACTED
+regex:[a-z0-9-]+\.corp\.example\.com==>internal.example
+```
+
+```sh
+git filter-repo --sensitive-data-removal --replace-text ../replacements.txt
+git filter-repo --sensitive-data-removal --invert-paths --path config/prod.env --path dumps/
+git filter-repo --replace-message ../message-replacements.txt   # same format, for commit messages
+git filter-repo --mailmap ../mailmap                             # rewrite author/committer names and emails
+```
+
+- `--sensitive-data-removal` fetches all refs first, reports the first changed commits and orphaned LFS objects, and prints cleanup steps for the remote and other clones.
+- Keep `replacements.txt` outside the repository; it contains the secrets.
+- Re-run `gitleaks git -v --log-opts="--all"` and the manual searches until clean.
+- If the private remote must also be cleaned: `git push --force --mirror origin` only with the user's sign-off; hosts block some refs (`refs/pull/*`) and keep cached views, so follow the host's sensitive-data removal guide and contact its support to purge them. Every other clone must be re-cloned or cleaned.
+
+## Third-party licence inventory
+
+| Ecosystem | Tool |
+|---|---|
+| npm / pnpm / Yarn | `npx license-checker-rseidelsohn --summary` (or the maintained checker the project uses) |
+| Python | `pip-licenses --format=markdown` in the project's environment |
+| Go | `go-licenses report ./...` |
+| Rust | `cargo deny check licenses` with an allow-list in `deny.toml` |
+| Java / Kotlin | Gradle or Maven licence plugins the build already uses |
+| Any | `licensee detect` for the repository's own licence; `reuse lint` for REUSE compliance |
+
+Also check for an SBOM requirement; `syft` or the ecosystem's SBOM tool can produce one.
+
+## Final checklist (all must be yes)
+
+- [ ] Owner approval recorded
+- [ ] Every found secret rotated, and scans of tree and full history are clean
+- [ ] No PII, customer data, internal hostnames, IPs, account IDs or internal URLs remain
+- [ ] `LICENSE` present, SPDX id in manifests, third-party licence flags resolved by a qualified person
+- [ ] README quick-start works from a clean clone on a machine without internal network access
+- [ ] Build and tests pass without private registries, internal services or company VPN
+- [ ] CONTRIBUTING, SECURITY (with a real contact), CODE_OF_CONDUCT (with a real contact)
+- [ ] Public CI green; secret scanning, push protection and branch protection enabled
+- [ ] Internal-only workflows, runbooks and deploy config removed
+- [ ] Trademarks and project name cleared by the owner
+- [ ] Publishing to a new public repository, or, if flipping the existing one, issues, PRs, wiki, releases and Actions logs reviewed
+- [ ] Commit authors, emails and messages reviewed (fresh history, or `--mailmap` / `--replace-message` applied)
+- [ ] User gave explicit sign-off to change visibility