@ketecode/loom 0.0.0-stage → 0.2.0

package/skills/aws-patterns/SKILL.md

@@ -0,0 +1,91 @@
+---
+name: aws-patterns
+description: Designs and reviews workloads on Amazon Web Services, covering least-privilege IAM roles and policies, picking Lambda versus ECS Fargate versus EC2, S3 bucket hardening, RDS and Aurora setup, VPC subnets and security groups, Secrets Manager and Parameter Store, and the bill surprises that come from NAT gateways, public IPv4 and idle resources. Use when building or changing something on AWS, writing an IAM policy, choosing an AWS compute service, or asking why an AWS account costs more than expected.
+license: MIT
+compatibility: Any Agent Skills host. Live checks need the AWS CLI with credentials for the target account. Infrastructure code may be Terraform, CloudFormation, CDK or SAM.
+metadata:
+  kete-loom/version: "0.1.0"
+  kete-loom/category: devops
+  kete-loom/risk: network
+  kete-loom/requires: "aws"
+  kete-loom/owner: "Kete-org"
+---
+
+# AWS patterns
+
+Build on AWS so that every principal has only the access it needs, nothing is public by accident, secrets never sit in code, and the monthly bill holds no surprises. Terraform syntax itself belongs to `terraform-patterns`; container image detail to `docker-patterns`; CI wiring to `github-actions-ci`.
+
+## Ground rules
+
+1. **Everything is code.** Create resources through the project's IaC (Terraform, CloudFormation, CDK or SAM). Console changes are for exploring only; if you find drift, report it, don't "fix" it by clicking.
+2. **Roles, not users.** Workloads get IAM roles (Lambda execution role, ECS task role, EC2 instance profile). People sign in through IAM Identity Center. Never create long-lived access keys for an app or a CI system; CI uses OIDC federation (see `github-actions-ci`).
+3. **Least privilege, scoped by resource.** No `"Action": "*"` or `"Resource": "*"` on write actions. Name the ARNs. Use conditions (`aws:SourceArn`, `aws:PrincipalOrgID`, `s3:prefix`) when a service or cross-account principal is involved.
+4. **Private by default.** S3 Block Public Access stays on at account and bucket level. Databases live in private subnets with no public endpoint. Serve public content through CloudFront with origin access control, not a public bucket.
+5. **Secrets in Secrets Manager or SSM Parameter Store (`SecureString`).** Never in environment variables committed to the repo, task definitions in git, or user data. Grant `secretsmanager:GetSecretValue` on that one secret ARN only.
+6. **Encrypt and log.** Encryption at rest on S3, EBS, RDS (default keys are fine unless compliance asks for customer-managed KMS keys). CloudTrail on in every region for the account.
+7. **Tag everything** with at least owner, environment and cost centre so cost reports mean something.
+
+## Choosing compute
+
+| Need | Pick | Watch out for |
+|---|---|---|
+| Event-driven, spiky, short tasks (API, queue consumer, cron) | Lambda | 15-minute maximum run time; cold starts; database connection storms (use RDS Proxy) |
+| Long-running containers without managing servers | ECS on Fargate | Pay per vCPU/memory even when idle; right-size tasks |
+| Many services, team already runs Kubernetes | EKS | Control-plane fee per cluster plus node cost; operational load. See `kubernetes-patterns` |
+| GPUs, special kernels, licensed software, steady high load | EC2 (Auto Scaling group) | You patch the OS; use SSM Session Manager instead of SSH keys and open port 22 |
+| Static site | S3 + CloudFront | Bucket stays private behind origin access control |
+
+Decision rule: start with the simplest option that meets the run-time and scaling need. If the user wants EKS for one or two services, ask whether they have Kubernetes experience before committing.
+
+## Networking basics
+
+1. One VPC per environment, spread across at least two Availability Zones.
+2. Public subnets hold only load balancers and NAT gateways. App and database subnets are private.
+3. Security groups reference other security groups, not CIDR ranges: the database SG allows port 5432 from the app SG only. Never `0.0.0.0/0` on anything but 80/443 on a load balancer.
+4. Add a gateway VPC endpoint for S3 (and DynamoDB if used): it costs nothing and keeps that traffic off the NAT gateway.
+5. Use interface endpoints for other heavy AWS API traffic (ECR, Secrets Manager, CloudWatch Logs) when NAT data charges are high.
+
+## Data
+
+- **S3:** versioning on for anything you can't regenerate; lifecycle rules to move or expire old objects and abort incomplete multipart uploads; bucket policy that denies non-TLS requests (`aws:SecureTransport` = false).
+- **RDS / Aurora:** Multi-AZ for production, automated backups with a retention that matches the recovery need, deletion protection on, storage encrypted, credentials managed by Secrets Manager (RDS can manage and rotate the master password). Connect with IAM auth or a secret, never a password in config.
+- **DynamoDB:** design keys around access patterns first; on-demand capacity until traffic is predictable.
+
+## Cost traps to check every time
+
+- NAT gateway hourly charge plus per-GB processing; one per AZ multiplies it. Traffic to S3 through NAT is the classic waste.
+- Public IPv4 addresses are billed per hour, including ones attached to running instances and idle Elastic IPs.
+- Cross-AZ and internet data transfer.
+- Unattached EBS volumes, old snapshots, idle load balancers, forgotten dev RDS instances.
+- CloudWatch Logs with no retention set (the default is never expire).
+- Lambda with oversized memory or a retry loop on a failing event source.
+
+Set an AWS Budgets alert on every account before building anything else.
+
+## Steps for a change
+
+1. Read the existing IaC and identify the account, region and environment. If you can't tell which account a change targets, **stop and ask**.
+2. Write the change in IaC following the ground rules.
+3. Validate it: `terraform plan`, `cdk diff`, `sam validate` or `aws cloudformation validate-template`. For IAM, run `aws accessanalyzer validate-policy --policy-type IDENTITY_POLICY --policy-document file://policy.json` and fix every error and security warning.
+4. Show the user the plan. **Stop and ask before** any apply that deletes or replaces a stateful resource (database, bucket, volume), widens a security group to the internet, or touches production.
+5. After apply, verify: `aws sts get-caller-identity` for identity, the service's health check, and that no new resource is public.
+
+## Never
+
+- Commit access keys, or put them in `.env` files that reach git.
+- Use the root user for anything except the few tasks that require it; root has MFA and no access keys.
+- Attach `AdministratorAccess` to a workload role "to get it working".
+- Run destructive CLI commands (`aws s3 rm --recursive`, `delete-db-instance`) without the user confirming the exact target.
+
+## Review output
+
+When asked to review AWS setup, report:
+
+```
+AWS review: <account/env>
+Critical: <public data, admin roles, leaked keys>
+High: <missing encryption, open security groups, no backups>
+Cost: <each trap found, rough monthly impact if known>
+Suggested IaC changes: <file: change>
+Not checked: <what you had no access to>
+```

package/skills/aws-patterns/evals/triggers.json

@@ -0,0 +1,16 @@
+{
+  "should_trigger": [
+    "Write a least-privilege IAM policy so our Lambda can only read one S3 bucket and one secret",
+    "Should this background worker run on Lambda, ECS Fargate or plain EC2?",
+    "Our AWS bill doubled and most of it is NAT gateway data processing, what are we doing wrong?",
+    "Set up a VPC with private subnets for RDS Postgres and security groups that only let the app in",
+    "Where should our app's database password live on AWS instead of the task definition env vars?"
+  ],
+  "should_not_trigger": [
+    "Configure GitHub Actions to assume an AWS role with OIDC instead of access keys",
+    "Refactor our Terraform modules to use for_each instead of count",
+    "Deploy the service to Google Cloud Run with its own service account",
+    "Plan a canary rollout for the new checkout service with automatic rollback",
+    "Write a Kubernetes Deployment manifest with resource limits and probes"
+  ]
+}

package/skills/azure-patterns/SKILL.md

@@ -0,0 +1,86 @@
+---
+name: azure-patterns
+description: Sets up and audits Microsoft Azure workloads with Entra ID and managed identities instead of stored credentials, Azure RBAC at resource scope, a reasoned choice among App Service, Container Apps, Azure Functions and AKS, Azure SQL and Cosmos DB configuration, Key Vault references, virtual networks with private endpoints and NSGs, and Azure spending pitfalls like idle App Service plans and over-provisioned RUs. Use when building on Azure, wiring a managed identity, deciding where an Azure app should run, or explaining an Azure invoice.
+license: MIT
+compatibility: Any Agent Skills host. Live checks need the Azure CLI signed in to the target subscription. Infrastructure code may be Bicep, ARM or Terraform.
+metadata:
+  kete-loom/version: "0.1.0"
+  kete-loom/category: devops
+  kete-loom/risk: network
+  kete-loom/requires: "az"
+  kete-loom/owner: "Kete-org"
+---
+
+# Azure patterns
+
+Build on Azure so apps authenticate with managed identities, secrets live in Key Vault, data services sit behind private endpoints, and costs are predictable. Terraform detail is in `terraform-patterns`, Kubernetes manifests in `kubernetes-patterns`, CI login in `github-actions-ci`, .NET code in `aspnet-core-patterns`.
+
+## Ground rules
+
+1. **Structure:** management groups, then one subscription per environment (or at least per prod / non-prod), then resource groups per application and environment. Resource groups share a lifecycle: everything in one is deployed and deleted together.
+2. **Managed identities for workloads.** Use a system-assigned identity when one resource needs access; a user-assigned identity when several resources share it or it must exist before the resource. In code use `DefaultAzureCredential` (or the language's equivalent) so the same code works locally with a developer sign-in and in Azure with the identity.
+3. **No client secrets in apps.** If an app registration secret seems needed, **stop and ask** whether a managed identity or workload identity federation (for CI and for AKS) works instead. If a secret is unavoidable, store it in Key Vault and set an expiry reminder.
+4. **Azure RBAC, narrowest scope, data-plane roles.** Grant `Key Vault Secrets User` on the vault, `Storage Blob Data Reader` on the storage account or container. Never Owner or Contributor on a subscription for a workload.
+5. **Key Vault for secrets, keys and certificates.** Use the RBAC permission model, soft delete and purge protection. App Service and Functions read secrets through Key Vault references in app settings; Container Apps through secret references to Key Vault.
+6. **Everything in IaC** (Bicep, ARM or Terraform). Preview with `az deployment group what-if` or `terraform plan`.
+
+## Choosing compute
+
+| Need | Pick | Watch out for |
+|---|---|---|
+| Web app or API, code or container, simple ops | App Service | The App Service plan bills while running even with zero traffic; deployment slots for zero-downtime swaps |
+| Containerised microservices, scale to zero, Dapr or KEDA scaling | Container Apps | Set min replicas deliberately; workload profiles for dedicated capacity |
+| Event-driven functions (queues, timers, HTTP) | Azure Functions, Flex Consumption plan for new serverless apps | Linux Consumption is legacy and scheduled for retirement; check timeouts per plan |
+| Full Kubernetes control, many teams, custom operators | AKS | You own upgrades and node pools; use workload identity, not pod-managed identity |
+| Lift-and-shift VM software | Virtual Machines / scale sets | Patch management; Bastion instead of public RDP/SSH |
+
+Decision rule: App Service or Container Apps first. Choose AKS only when the user names a requirement those can't meet.
+
+## Networking basics
+
+1. One virtual network per environment (or hub-and-spoke for larger estates), with subnets per tier.
+2. Data services (Azure SQL, Cosmos DB, Storage, Key Vault) get **private endpoints** and public network access disabled; add the matching Private DNS zones so names resolve to the private IP.
+3. App Service and Functions reach the VNet through VNet integration; Container Apps run in a VNet-integrated environment.
+4. NSGs on subnets allow only the ports each tier needs, by service tag or application security group. Never open RDP (3389) or SSH (22) to the internet; use Azure Bastion.
+5. Public HTTP goes through Application Gateway or Front Door, with WAF if the user needs it.
+
+## Data
+
+- **Azure SQL Database:** Entra ID authentication with the app's managed identity (no SQL passwords in connection strings), Entra-only auth where possible; geo-redundant backups and point-in-time restore configured; serverless tier with auto-pause for dev.
+- **Cosmos DB:** choose the partition key from the dominant query; serverless or autoscale throughput rather than high fixed RU/s; use data-plane RBAC with the managed identity instead of account keys, and disable key-based auth when nothing needs it.
+- **Storage accounts:** disable anonymous blob access and shared key auth where clients support Entra; soft delete for blobs and containers; lifecycle management to cool or archive tiers.
+
+## Cost traps
+
+- App Service plans and Premium Functions plans that keep billing for apps nobody uses; several small plans that could share one.
+- Cosmos DB provisioned RU/s far above actual use; one container per tenant with minimum RU each.
+- AKS node pools that never scale down; forgotten dev clusters.
+- Log Analytics ingestion with no daily cap or retention policy.
+- Unattached managed disks, public IPs, idle Application Gateways, VMs stopped but not deallocated.
+
+Create a budget with alerts on each subscription first.
+
+## Steps for a change
+
+1. Confirm the subscription and resource group: `az account show`. If it is not the one the user means, **stop and ask**.
+2. Write the change in IaC with identities, RBAC assignments and private endpoints in the same change.
+3. Preview: `az deployment group what-if` or `terraform plan`. Read every delete and replace line.
+4. **Stop and ask before** any deployment in `Complete` mode, any delete or replace of a database, storage account or vault, any role assignment at subscription scope, or any production change.
+5. After deploying, verify the app's health endpoint, that the identity has exactly the intended role assignments (`az role assignment list --assignee <principalId>`), and that public network access is off where intended.
+
+## Never
+
+- Put storage account keys, Cosmos keys or SQL passwords in app settings or source.
+- Purge a soft-deleted Key Vault or delete a resource group without the user confirming the exact name.
+- Grant Owner to a service principal used by CI "to save time".
+
+## Review output
+
+```
+Azure review: <subscription/env>
+Critical: <secrets in config, public data endpoints, Owner on workloads>
+High: <no managed identity, missing backups, open NSG rules>
+Cost: <each trap found>
+Suggested IaC changes: <file: change>
+Not checked: <what you had no access to>
+```

package/skills/azure-patterns/evals/triggers.json

@@ -0,0 +1,16 @@
+{
+  "should_trigger": [
+    "Give our App Service a managed identity so it can read secrets from Key Vault without a client secret",
+    "Should we host these microservices on Azure Container Apps or AKS?",
+    "Lock down Azure SQL and the storage account with private endpoints and disable public access",
+    "Our Cosmos DB costs are huge, how do we cut the provisioned RU/s spend?",
+    "We still run Azure Functions on the Linux Consumption plan, what should we move to?"
+  ],
+  "should_not_trigger": [
+    "Use azure/login in a GitHub Actions workflow with a federated credential",
+    "Set up IAM roles and a VPC for an ECS service on AWS",
+    "Configure Entity Framework Core migrations for our ASP.NET Core app",
+    "Pick between Cloud Run and GKE for a new service on Google Cloud",
+    "Write a blue-green deployment plan for the billing API"
+  ]
+}

package/skills/benchmark-methodology/SKILL.md

@@ -0,0 +1,88 @@
+---
+name: benchmark-methodology
+description: Designs and runs performance benchmarks whose numbers hold up, with warmup, enough iterations, medians and p95/p99 with spread, a quiet and pinned machine, interleaved before/after comparison with a significance check, and guards against dead-code elimination and other microbenchmark traps in Go, JMH, BenchmarkDotNet, Criterion, pytest-benchmark and JS. Use when measuring whether a change made code faster or slower, writing a microbenchmark, or judging a performance claim.
+license: MIT
+compatibility: Any Agent Skills host. Needs the project's language toolchain; hyperfine is optional for command-level timing.
+metadata:
+  kete-loom/version: "0.1.0"
+  kete-loom/category: testing
+  kete-loom/risk: runs-commands
+  kete-loom/owner: "Kete-org"
+---
+
+# Benchmark methodology
+
+A benchmark is an experiment. Its job is to answer one question ("is B faster than A for this workload, by how much, and are we sure?") with numbers someone else can reproduce. Most bad benchmarks measure the wrong thing, too few times, on a noisy machine.
+
+## 1. Write down the question
+
+Before any code, state:
+
+1. **What is measured**: a function, an endpoint, a CLI command, a whole job.
+2. **The metric**: latency per operation, throughput, allocations, peak memory, startup time.
+3. **The workload**: realistic input sizes and shapes. Use production-like data, not `n = 10`. If you don't know the real sizes, **ask the user**.
+4. **The decision**: what result would change what we do ("ship if p95 improves by 10 % or more with no regression in allocations").
+
+If the user wants to know why the app is slow rather than compare versions, profile first (CPU profiler, flame graph) and benchmark the hot spot after.
+
+## 2. Pick the level and the tool
+
+- **Microbenchmark** (a function, nanoseconds to milliseconds): use the language harness, never a hand-rolled timer loop. See `references/language-harnesses.md`.
+- **Command or process** (a CLI, a build step): `hyperfine --warmup 3 --runs 20 'old-cmd' 'new-cmd'`; add `--prepare` to reset caches or state between runs and `--export-json` to keep raw data.
+- **Service** (an HTTP endpoint): a load tool at a fixed request rate, measuring latency percentiles at that rate. Measuring at maximum throughput hides latency problems.
+
+## 3. Control the environment
+
+- Same machine, same build flags (release / optimised), same runtime version, same input for A and B.
+- Close other heavy work. On laptops, plug in power and disable low-power modes. In CI, shared runners are noisy: use a dedicated runner, or only trust large differences.
+- Where possible, disable CPU frequency boost and pin to cores (Linux: `taskset -c 2 <cmd>`). Record if you could not.
+- Warm up: JIT compilation, caches, connection pools and lazy initialisation make first runs slow. Discard warmup iterations, or measure cold start separately on purpose.
+- Note the hardware, OS, runtime version and commit for every run.
+
+## 4. Run enough and keep the raw data
+
+- At least 10 samples per variant for microbenchmarks the harness doesn't already repeat (Go: `-count=10`); 20 or more for noisy ones.
+- **Interleave** A and B (A, B, A, B...) or alternate whole runs so thermal drift and background jobs hit both equally. Never run all of A in the morning and all of B after lunch.
+- Keep the raw samples, not only the mean.
+
+## 5. Summarise honestly
+
+- Report the **median** and **p95 / p99** for latency; the mean hides tail latency and is pulled by outliers.
+- Report spread: standard deviation, median absolute deviation or a confidence interval.
+- Compare with a significance test, not by eye. Go: `benchstat old.txt new.txt`. JMH and BenchmarkDotNet print error margins; differences inside the error bars are noise. For raw samples, a Mann-Whitney U test is a safe default.
+- Say "no measurable difference" when that is the result. A 2 % change with 5 % noise is not a win.
+- Check memory too: allocations per op (`-benchmem` in Go, `[MemoryDiagnoser]` in BenchmarkDotNet, `-prof gc` in JMH). A faster version that allocates far more may be slower in production.
+
+## 6. Microbenchmark traps
+
+Check each before trusting a number:
+
+1. **Dead-code elimination**: the compiler removes work whose result is unused. Consume results (`Blackhole` in JMH, `std::hint::black_box` in Rust, return the value from a BenchmarkDotNet method, `b.Loop()` in Go 1.24+).
+2. **Constant folding**: inputs known at compile time get precomputed. Load inputs from a variable or setup step.
+3. **Measuring setup**: allocating the input inside the timed region. Do setup outside it.
+4. **Caches too warm**: the same small input every iteration stays in L1 and branch predictors learn it. Use realistic sizes and varied data.
+5. **Timer resolution**: timing a 20 ns operation once is noise; harnesses batch iterations for this reason.
+6. **GC and JIT pauses** landing in one variant only. Run long enough and check variance.
+7. **Debug builds**: `cargo bench` and `go test -bench` optimise by default; for C and C++ check optimisation flags (`-O2`, CMake `Release`), for .NET build with `-c Release`; on the JVM, use JMH so the JIT has warmed up.
+
+Language-specific details and example code are in `references/language-harnesses.md`.
+
+## Rules
+
+- Never claim a speed-up from a single run, a debug build, or a different input.
+- Never tune the benchmark until it shows the result you hoped for; fix the method, then accept the answer.
+- Never commit benchmark code that makes network calls or depends on wall-clock time of day.
+- If results contradict across runs, **stop and report the noise** instead of picking the best run.
+
+## Report back
+
+```
+Question: <what was compared, workload>
+Environment: <CPU, OS, runtime version, commit A, commit B, noise controls>
+Method: <tool, warmup, samples per variant, interleaved yes/no>
+Results:
+| Variant | median | p95 | spread | allocs/op |
+Verdict: <B is X% faster (p < 0.05) | no measurable difference | B regressed>
+Caveats: <what could still skew it>
+Commands: <exact commands to reproduce>
+```

package/skills/benchmark-methodology/evals/triggers.json

@@ -0,0 +1,16 @@
+{
+  "should_trigger": [
+    "Write a Go benchmark comparing the old and new JSON decoder and tell me if the new one is actually faster",
+    "My JMH numbers swing 30% between runs, how do I get results I can trust?",
+    "Is my refactor of the tokenizer a performance regression? Measure it properly before and after",
+    "Set up BenchmarkDotNet for our hashing code with allocation stats",
+    "Someone claims the Rust rewrite is 3x faster, check whether their benchmark is valid"
+  ],
+  "should_not_trigger": [
+    "Profile the API and fix whatever is making the orders endpoint slow",
+    "Our Lighthouse score dropped, improve the page load time",
+    "Raise the unit test coverage of the parser package to 80%",
+    "Write Playwright tests for the search page",
+    "Run the test suite and lint before I push"
+  ]
+}

package/skills/benchmark-methodology/references/language-harnesses.md

@@ -0,0 +1,130 @@
+# Benchmark harnesses by language
+
+Read this when writing a microbenchmark. Use the harness the project already has; add a new one only with the user's agreement.
+
+## Go (`testing`)
+
+```go
+func BenchmarkParse(b *testing.B) {
+    input := loadFixture(b) // setup is outside the timed loop with b.Loop
+    for b.Loop() {
+        Parse(input)
+    }
+}
+```
+
+- `b.Loop()` (Go 1.24+) times only the loop body and stops the compiler from optimising the body away. On older Go, use `for i := 0; i < b.N; i++`, call `b.ResetTimer()` after setup, and assign results to a package-level sink variable.
+- Run: `go test -run '^$' -bench BenchmarkParse -benchmem -count=10 ./pkg/parse > new.txt`.
+- Compare: `go install golang.org/x/perf/cmd/benchstat@latest`, then `benchstat old.txt new.txt`. It prints the change with a p-value; "~" means no significant difference.
+- Pitfalls: `-run '^$'` stops unit tests from running alongside; `-cpu 1,4` shows scaling.
+
+## Java and Kotlin (JMH)
+
+```java
+@State(Scope.Benchmark)
+@BenchmarkMode(Mode.AverageTime)
+@OutputTimeUnit(TimeUnit.NANOSECONDS)
+@Warmup(iterations = 5) @Measurement(iterations = 10) @Fork(3)
+public class ParseBench {
+    String input;
+    @Setup public void setup() { input = Fixtures.load(); }
+    @Benchmark public void parse(Blackhole bh) { bh.consume(Parser.parse(input)); }
+}
+```
+
+- Never benchmark the JVM with `System.nanoTime()` loops: JIT tiers, on-stack replacement and dead-code elimination make them meaningless.
+- `@Fork` of 2 or more runs separate JVMs so one JIT profile doesn't decide the result.
+- `-prof gc` reports allocation rate; `-prof async` (async-profiler) shows where time goes.
+- Use `@Param` for input sizes so you see how cost scales.
+
+## C# / .NET (BenchmarkDotNet)
+
+```csharp
+[MemoryDiagnoser]
+public class ParseBench {
+    private string _input = default!;
+    [GlobalSetup] public void Setup() => _input = Fixtures.Load();
+    [Benchmark(Baseline = true)] public Result Old() => OldParser.Parse(_input);
+    [Benchmark] public Result New() => NewParser.Parse(_input);
+}
+// Program.cs: BenchmarkRunner.Run<ParseBench>();
+```
+
+- Run in Release: `dotnet run -c Release`. BenchmarkDotNet warns when it detects a debug build or an attached debugger.
+- Return the result from the method so it isn't eliminated.
+- `Baseline = true` adds a Ratio column for before/after.
+
+## Rust (Criterion or `cargo bench`)
+
+```rust
+use criterion::{criterion_group, criterion_main, Criterion};
+use std::hint::black_box;
+
+fn bench(c: &mut Criterion) {
+    let input = load_fixture();
+    c.bench_function("parse", |b| b.iter(|| parse(black_box(&input))));
+}
+criterion_group!(benches, bench);
+criterion_main!(benches);
+```
+
+- Needs `[[bench]] name = "parse" harness = false` in `Cargo.toml`.
+- Criterion saves a baseline and reports change and significance against the previous run; `cargo bench -- --save-baseline before` then `--baseline before` compares named baselines.
+- `black_box` on inputs prevents constant folding; Criterion handles the output.
+
+## Python (pytest-benchmark, pyperf, timeit)
+
+```python
+def test_parse(benchmark):
+    data = load_fixture()
+    result = benchmark(parse, data)
+    assert result.ok
+```
+
+- Run: `pytest --benchmark-only --benchmark-autosave`, then compare saved runs with `pytest-benchmark compare`.
+- For stand-alone scripts, `pyperf` handles warmup, multiple processes and system tuning advice (`python -m pyperf system tune` on Linux).
+- `python -m timeit -s 'setup' 'stmt'` is fine for a quick check, not for a decision.
+- Interpreter version matters a lot between releases; record it.
+
+## JavaScript and TypeScript (tinybench, mitata, Vitest bench)
+
+```ts
+import { Bench } from 'tinybench';
+const bench = new Bench({ time: 1000 }); // warmup option names differ between tinybench majors; check the installed version's docs
+const input = loadFixture();
+bench.add('old', () => oldParse(input)).add('new', () => newParse(input));
+await bench.run();
+console.table(bench.table());
+```
+
+- V8 optimises and deoptimises based on observed types; feed realistic, varied inputs or one shape will look unrealistically fast.
+- Keep the result reachable (return it, or push into an array checked after the run).
+- Vitest has `bench()` in `*.bench.ts` files, run with `npx vitest bench`.
+- Node version and flags change results; record `node --version`.
+
+## C and C++ (Google Benchmark)
+
+```cpp
+static void BM_Parse(benchmark::State& state) {
+  auto input = LoadFixture();
+  for (auto _ : state) benchmark::DoNotOptimize(Parse(input));
+}
+BENCHMARK(BM_Parse);
+BENCHMARK_MAIN();
+```
+
+- Build with optimisations (`-O2` or `-DCMAKE_BUILD_TYPE=Release`); the library warns if it was built as debug.
+- `--benchmark_repetitions=10 --benchmark_report_aggregates_only=true` gives mean, median and stddev.
+- `benchmark::ClobberMemory()` forces pending writes to be treated as observable.
+
+## Commands and processes (hyperfine)
+
+```sh
+# build both versions first (e.g. ./old-bin from main, ./new-bin from the branch)
+hyperfine --warmup 3 --runs 30 --export-json bench.json \
+  './old-bin input.txt' './new-bin input.txt'
+```
+
+- `--prepare 'cmd'` runs before each timing run (for example, clearing a cache directory).
+- Never put state-changing commands (`git stash`, `git checkout`) inside a timed command; build each variant once, then time the binaries.
+- hyperfine reports mean, standard deviation, min/max and a relative comparison; it warns about statistical outliers.

package/skills/bgp-diagnostics/SKILL.md

@@ -0,0 +1,84 @@
+---
+name: bgp-diagnostics
+description: Diagnoses Border Gateway Protocol problems on Cisco, Juniper, Arista and FRR routers by reading neighbor state (Idle, Active, OpenSent, Established) and NOTIFICATION codes, checking which prefixes are received, accepted and advertised through prefix-lists, route-maps and max-prefix limits, walking best-path selection, decoding standard and large communities, spotting RPKI-invalid or leaked routes, and confirming what the internet sees from RIPEstat, RouteViews and other looking glasses. Use when a BGP session will not come up or keeps flapping, a prefix is missing, not propagating or taking the wrong path, a provider says they are not receiving an announcement, or traffic shifted after a routing change or an upstream incident.
+license: MIT
+compatibility: Any Agent Skills host. Works from pasted router output; live checks need read-only CLI access to the router and web access to public looking glasses and route collectors.
+metadata:
+  kete-loom/version: "0.1.0"
+  kete-loom/category: devops
+  kete-loom/risk: read-only
+  kete-loom/owner: "Kete-org"
+---
+
+# BGP diagnostics
+
+Find out why a BGP session or route is not doing what the operator expects, using read-only commands and public data, and hand back a cause with evidence and a proposed fix the operator applies.
+
+For NOTIFICATION codes, best-path order, well-known communities and per-vendor command equivalents, read `references/bgp-reference.md`.
+
+## Ground rules
+
+1. **Read-only.** Use `show`/`display` commands and public looking glasses. Never run `clear ip bgp`, `clear bgp`, `neighbor ... shutdown`, policy edits or `soft` resets yourself; propose them and let the operator run them in a window. A hard reset drops every route from that peer.
+2. Work from evidence: ask for the exact command output, router platform and OS version, local AS, peer AS and peer address.
+3. Separate the two questions: **is the session up?** and **is the route right?** Fix the first before the second.
+4. Treat every public looking-glass result as a sample from one vantage point. Check at least two sources before telling the user "the internet can't see it".
+
+## 1. Session not Established
+
+Get `show bgp summary` (or `show ip bgp summary`, Junos `show bgp summary`, FRR `vtysh -c "show bgp summary"`) and `show bgp neighbors <peer>`.
+
+| State seen | Usual cause | Check |
+|---|---|---|
+| `Idle` | Admin shutdown, no route to peer, max-prefix tripped, or waiting after errors | `show bgp neighbors` last reset reason; `Idle (Admin)` / `Idle (PfxCt)` on IOS |
+| `Active` / `Connect` cycling | TCP 179 never completes: wrong peer IP, ACL or firewall, peer not configured, wrong source interface | Ping the peer from the configured source; `update-source` on loopback peers; ACLs and CoPP for TCP 179 |
+| `OpenSent` / `OpenConfirm` then reset | OPEN rejected: wrong remote AS, bad router ID, capability or hold-time mismatch, MD5/TCP-AO password mismatch | Logs for NOTIFICATION code 2/x; on IOS `%TCP-6-BADAUTH` means password mismatch |
+| Up then flaps every ~3 min | Hold timer expiry: loss, CPU, MTU problems on large updates | NOTIFICATION 4; interface errors; ping with DF at full MTU |
+| Up then drops at a prefix count | Max-prefix limit | Cease subcode 1; compare received count to `maximum-prefix` |
+
+Also check:
+- eBGP to a non-directly-connected address needs `ebgp-multihop` (or `ttl-security` on both sides), because eBGP packets default to TTL 1.
+- Some platforms refuse to send or accept eBGP routes with no policy configured (RFC 8212): IOS-XR ("no policy; defaults to 'drop'", overridable with `bgp unsafe-ebgp-policy`) and FRR in its default traditional profile (`bgp ebgp-requires-policy`, shown as `(Policy)` in `show bgp summary`). Session `Established` with 0 prefixes both ways often means this.
+- Address family activated on both sides (`address-family ipv6` + `neighbor ... activate`).
+
+## 2. Prefix missing or wrong
+
+Walk the path step by step and stop at the first step that fails.
+
+1. **Originated?** The prefix is in the local BGP table: `show bgp ipv4 unicast <prefix>`. A `network` statement needs an exact match in the RIB (same mask); otherwise use a static to Null0 or an aggregate.
+2. **Advertised?** `show bgp ipv4 unicast neighbors <peer> advertised-routes`. If absent, check outbound prefix-list, route-map, `no-export`/`no-advertise` communities, and iBGP split-horizon (iBGP-learned routes are not sent to other iBGP peers without a route reflector).
+3. **Received by the peer?** Ask the peer, or use their looking glass. On your side for inbound routes: `received-routes` needs `soft-reconfiguration inbound` on IOS; otherwise use `show bgp ... neighbors <peer> routes` for accepted routes only.
+4. **Accepted?** Inbound filters, max-prefix, AS-path loop (own AS in path; `allowas-in` only if the design needs it), RPKI-invalid dropped by ROV, or IRR-based filters at the provider missing your route object.
+5. **Best?** `show bgp ipv4 unicast <prefix>` lists all paths; walk the best-path order in the reference and name the step that decided. Common surprises: weight set on one neighbor, local-pref from a route-map, MED compared only within one neighbor AS, IGP metric to next hop.
+6. **Installed?** `show ip route <prefix>`: an IGP or static with lower administrative distance wins; next hop unreachable makes the path invalid (`inaccessible`).
+
+## 3. What the internet sees
+
+For a public prefix or ASN:
+- RIPEstat (`stat.ripe.net`): Routing Status, Looking Glass and BGPlay widgets show visibility across RIS collectors and the history of announcements and withdrawals.
+- RouteViews collectors (`route-views.routeviews.org` and others) and bgp.tools or bgp.he.net for origin AS, upstreams and visibility.
+- RPKI: check the prefix and origin pair is Valid in the RIPEstat RPKI widget or your RIR portal. An Invalid (wrong origin or max-length too short) is dropped by many networks.
+- IRR: `whois -h whois.radb.net <prefix>` or the provider's IRR; missing or wrong `route`/`route6` objects cause providers to filter you.
+- PeeringDB for the peer's NOC contact, prefix limits they expect, and IX details.
+
+## 4. Common outage causes to rule out
+
+1. ROA created with a max-length shorter than the announced more-specific, or for the wrong origin AS.
+2. A route leak: your prefix seen with an unexpected AS in the path, or you announcing learned routes to another provider (missing outbound filter). Check outbound policy matches only your own prefixes.
+3. Hijack or more-specific announced by someone else: a different origin AS for your prefix or a longer prefix inside it.
+4. Max-prefix tripped after a peer sent a full table.
+5. Password, AS or IP changed on one side during maintenance.
+6. Policy change applied without a soft refresh, so the new policy never took effect; or a soft reset expected to fix something it cannot.
+7. Upstream incident: check the provider status page and RIPEstat for many prefixes moving at once.
+
+**Stop and tell the user to contact the provider or a qualified network engineer** when evidence points at the upstream, a suspected hijack, or a change that would affect transit for the whole network.
+
+## Report back
+
+```
+Session: <peer IP / AS> state <state>, last reset <reason/code>
+Prefix: <prefix> originated <y/n> advertised <y/n> seen by peer <y/n/unknown> best <y/n, decided at step N>
+External view: <sources checked, visibility, RPKI status, IRR status>
+Cause: <one sentence>, evidence: <command output lines>
+Proposed fix: <exact commands for the operator>, impact: <soft refresh vs session reset>
+Not verified: <what was not checked>
+```

package/skills/bgp-diagnostics/evals/triggers.json

@@ -0,0 +1,18 @@
+{
+  "should_trigger": [
+    "show ip bgp summary says our neighbor 203.0.113.1 is stuck in Active, what does that mean?",
+    "Our transit provider says they don't see our /24 but it's in our BGP table, where is it getting dropped?",
+    "BGP session with the IX route server goes down every few minutes with hold timer expired",
+    "Why is the router choosing the path through ISP B when we set local-pref 200 on ISP A?",
+    "RIPEstat shows our prefix with a different origin AS since this morning, is this a hijack?",
+    "The peer sent a NOTIFICATION cease subcode 1 and the session dropped, how do I read that?"
+  ],
+  "should_not_trigger": [
+    "Write a Nornir task that renders BGP neighbor config from NetBox and pushes it to all edge routers",
+    "Configure an extended ACL on the Cisco switch to block telnet to the management VLAN",
+    "My laptop can reach google.com by IP but DNS lookups fail on the office Wi-Fi",
+    "Plan an address scheme and VLANs for a new branch office network",
+    "Review this firewall ruleset before I load it on the edge gateway",
+    "Write the OSPF config for three Cisco routers sharing area 0 over point-to-point links"
+  ]
+}

package/skills/bgp-diagnostics/references/bgp-reference.md

@@ -0,0 +1,81 @@
+# BGP reference
+
+## FSM states (RFC 4271)
+
+`Idle` → `Connect` → `Active` → `OpenSent` → `OpenConfirm` → `Established`. `Connect` and `Active` mean TCP to port 179 has not completed. `OpenSent`/`OpenConfirm` mean TCP is up and OPEN messages are being exchanged.
+
+## NOTIFICATION error codes (RFC 4271)
+
+| Code | Meaning | Typical subcodes |
+|---|---|---|
+| 1 | Message Header Error | bad length or type |
+| 2 | OPEN Message Error | 2 Bad Peer AS, 3 Bad BGP Identifier, 4 Unsupported Optional Parameter, 6 Unacceptable Hold Time, 7 Unsupported Capability (RFC 5492) |
+| 3 | UPDATE Message Error | malformed attribute list, invalid next hop, malformed AS_PATH |
+| 4 | Hold Timer Expired | no keepalive or update within the hold time |
+| 5 | Finite State Machine Error | |
+| 6 | Cease | see below |
+
+Cease subcodes (RFC 4486): 1 Maximum Number of Prefixes Reached, 2 Administrative Shutdown, 3 Peer De-configured, 4 Administrative Reset, 5 Connection Rejected, 6 Other Configuration Change, 7 Connection Collision Resolution, 8 Out of Resources.
+
+Cisco IOS default timers: keepalive 60 s, hold 180 s. The negotiated hold time is the lower of the two sides.
+
+## Best-path selection, Cisco IOS/IOS-XE order
+
+A path whose next hop is unreachable is not a candidate. Then:
+
+1. Highest weight (Cisco-local, not advertised)
+2. Highest local preference (default 100)
+3. Locally originated (`network`, redistribution, aggregate)
+4. Shortest AS_PATH (an AS_SET counts as 1; skipped with `bgp bestpath as-path ignore`)
+5. Lowest origin: IGP < EGP < Incomplete
+6. Lowest MED, compared only between paths from the same neighbor AS unless `bgp always-compare-med` (set it AS-wide or not at all)
+7. eBGP over iBGP
+8. Lowest IGP metric to the next hop
+9. Multipath decision, if `maximum-paths` is set
+10. Oldest eBGP path (skipped with `bgp bestpath compare-routerid`)
+11. Lowest router ID (originator ID with route reflection)
+12. Shortest cluster list
+13. Lowest neighbor address
+
+Other vendors follow the same broad order without weight; Junos and FRR differ in details (for example MED handling and the oldest-path step). Check the vendor's doc for the exact release.
+
+## Well-known communities
+
+| Community | Value | Effect |
+|---|---|---|
+| NO_EXPORT | 65535:65281 | Do not advertise outside the AS (or confederation) |
+| NO_ADVERTISE | 65535:65282 | Do not advertise to any peer |
+| NO_EXPORT_SUBCONFED | 65535:65283 | Do not advertise to external peers, including other confederation member ASes |
+| GRACEFUL_SHUTDOWN | 65535:0 | RFC 8326: receiver lowers local preference before planned maintenance |
+| BLACKHOLE | 65535:666 | RFC 7999: request the neighbor to discard traffic to the prefix (only if the neighbor supports it) |
+
+Regular communities are `ASN:value` (RFC 1997). Large communities are `ASN:value1:value2` (RFC 8092) and are needed for 4-byte ASNs. Provider-specific action communities (prepend, local-pref, no-export to a region) are documented by each provider; look them up, never guess. On IOS, communities are only sent to a neighbor with `neighbor <ip> send-community` (`both` or `extended`/`large` as needed).
+
+## RPKI route origin validation (RFC 6811)
+
+Result per route: Valid (a ROA covers the prefix with the same origin AS and the prefix length is within max-length), Invalid (covered but wrong origin or too long), NotFound (no covering ROA). Many networks drop Invalid.
+
+## Command equivalents
+
+| Task | Cisco IOS/IOS-XE | Junos | Arista EOS | FRR (vtysh) |
+|---|---|---|---|---|
+| Summary | `show bgp ipv4 unicast summary` | `show bgp summary` | `show ip bgp summary` | `show bgp summary` |
+| Neighbor detail | `show bgp ipv4 unicast neighbors <ip>` | `show bgp neighbor <ip>` | `show ip bgp neighbors <ip>` | `show bgp neighbors <ip>` |
+| Prefix detail | `show bgp ipv4 unicast <prefix>` | `show route <prefix> detail` | `show ip bgp <prefix>` | `show bgp ipv4 unicast <prefix>` |
+| Sent to peer | `show bgp ipv4 unicast neighbors <ip> advertised-routes` | `show route advertising-protocol bgp <ip>` | `show ip bgp neighbors <ip> advertised-routes` | `show bgp ipv4 unicast neighbors <ip> advertised-routes` |
+| Received from peer (before policy) | `... neighbors <ip> received-routes` (needs `soft-reconfiguration inbound`) | `show route receive-protocol bgp <ip>` | `show ip bgp neighbors <ip> received-routes` | `... neighbors <ip> received-routes` (configure `soft-reconfiguration inbound` to keep the pre-policy table) |
+| Soft refresh inbound (operator runs) | `clear bgp ipv4 unicast <ip> soft in` | `clear bgp neighbor <ip> soft-inbound` | `clear ip bgp <ip> soft in` | `clear bgp ipv4 unicast <ip> soft in` |
+
+Check whether `received-routes` / `receive-protocol` output on your release is before or after inbound policy before drawing conclusions from it.
+
+## Sources
+
+- RFC 4271 (FSM, NOTIFICATION codes, OPEN subcodes, hold time): https://www.rfc-editor.org/rfc/rfc4271
+- RFC 4486 (Cease subcodes): https://www.rfc-editor.org/rfc/rfc4486
+- RFC 5492 (subcode 7, Unsupported Capability): https://www.rfc-editor.org/rfc/rfc5492
+- IANA well-known communities: https://www.iana.org/assignments/bgp-well-known-communities/
+- RFC 8092 (large communities), RFC 6811 (origin validation), RFC 8212 (eBGP default reject)
+- Cisco best-path algorithm: https://www.cisco.com/c/en/us/support/docs/ip/border-gateway-protocol-bgp/13753-25.html
+- Cisco IOS BGP timers (`neighbor timers`): https://www.cisco.com/c/en/us/td/docs/ios/iproute_bgp/command/reference/irg_book/irg_bgp4.html
+- FRR BGP (`ebgp-requires-policy`, show and clear commands): https://docs.frrouting.org/en/latest/bgp.html
+- Junos `clear bgp neighbor`: https://www.juniper.net/documentation/us/en/software/junos/bgp/topics/ref/command/clear-bgp-neighbor.html