@ketecode/loom 0.0.0-stage → 0.2.0

package/skills/angular-patterns/SKILL.md

@@ -0,0 +1,122 @@
+---
+name: angular-patterns
+description: Modern Angular guidance for standalone components, signal state with input(), output(), model(), computed and effect, RxJS subscriptions that cannot leak, OnPush and zoneless change detection, inject()-based dependency injection, typed reactive or signal forms, and TestBed component tests. Use when writing, migrating or debugging an Angular application, such as moving NgModules to standalone, replacing decorators with signals, fixing a view that does not refresh, or stopping a subscription leak.
+license: MIT
+compatibility: Any Agent Skills host. Targets Angular 17+ and notes where v20, v21 and v22 changed defaults. Needs the Angular CLI (ng) to build and test.
+metadata:
+  kete-loom/version: "0.1.0"
+  kete-loom/category: coding
+  kete-loom/risk: runs-commands
+  kete-loom/requires: "ng"
+  kete-loom/owner: "Kete-org"
+---
+
+# Angular patterns
+
+Write Angular that uses signals for state, RxJS for streams, and lets change detection do as little as possible. Match the version the project is on; do not introduce APIs it does not have.
+
+## 0. Orient first
+
+1. Read `package.json` for the `@angular/core` major. Read `angular.json` for the builder and test runner (Vitest, Karma or Jest).
+2. Check `main.ts` / `app.config.ts`: `bootstrapApplication` means standalone; `provideZonelessChangeDetection()` or no `zone.js` in `polyfills` means zoneless.
+3. Know the default shifts:
+   - Standalone is the default for components, directives and pipes since v19.
+   - New apps are zoneless by default since v21, and new projects use Vitest.
+   - From v22, components without a `changeDetection` setting are OnPush; the old default is named `ChangeDetectionStrategy.Eager`.
+4. Run the CLI migrations instead of rewriting by hand when moving a codebase: `ng generate @angular/core:standalone`, `@angular/core:control-flow`, `@angular/core:signal-input-migration`, `@angular/core:inject`. Review their diff.
+
+## 1. Components
+
+```ts
+@Component({
+  selector: 'app-user-card',
+  imports: [DatePipe],
+  changeDetection: ChangeDetectionStrategy.OnPush,
+  template: `
+    @if (user(); as u) { <h2>{{ u.name }}</h2> } @else { <p>Loading</p> }
+    @for (tag of tags(); track tag.id) { <span>{{ tag.label }}</span> } @empty { <p>No tags</p> }
+  `,
+})
+export class UserCard {
+  user = input.required<User>();
+  tags = input<Tag[]>([]);
+  selected = output<string>();
+  expanded = model(false);
+  initials = computed(() => this.user().name.slice(0, 2).toUpperCase());
+}
+```
+
+- Use built-in control flow (`@if`, `@for`, `@switch`) over `*ngIf`/`*ngFor` in new code. `@for` requires `track`: use a stable id, `$index` only for static lists.
+- Set `OnPush` explicitly on versions before v22 so behaviour is the same after upgrade.
+- Keep templates free of method calls that compute; use `computed` or a pure pipe.
+- Use `@defer` for heavy below-the-fold components.
+
+## 2. Signals
+
+- `signal()` for local state, `computed()` for anything derived, `input()`/`model()` for component inputs.
+- Update with `.set()` or `.update(v => ...)`. Never mutate an object inside a signal in place; produce a new object or the change is not seen.
+- `effect()` is for syncing to the outside world (localStorage, logging, a non-Angular widget). Do not use it to copy one signal into another; use `computed`, or `linkedSignal` when the derived value must also be writable.
+- For async data, prefer `resource()` / `httpResource()` (stable in v22; check status on older versions) or `toSignal(observable$)` over manual subscribe-and-set.
+- Bridge with `toSignal` and `toObservable` from `@angular/core/rxjs-interop`. `toSignal` needs an injection context and an `initialValue` unless you handle `undefined`.
+
+## 3. RxJS without leaks
+
+Every `subscribe()` needs a teardown. In order of preference:
+
+1. Do not subscribe: use the `async` pipe or `toSignal`.
+2. `takeUntilDestroyed()` in a constructor or field initialiser, or `takeUntilDestroyed(this.destroyRef)` elsewhere.
+3. Explicit `Subscription` cleaned in `DestroyRef.onDestroy`.
+
+Rules:
+
+- No nested `subscribe` inside `subscribe`. Use `switchMap` (cancel previous, for search and route params), `concatMap` (keep order, for writes), `exhaustMap` (ignore while busy, for submit buttons) or `mergeMap` (parallel).
+- `HttpClient` calls complete on their own, but long-lived sources (`valueChanges`, router events, `interval`, websockets, store selects) never do.
+- Handle errors with `catchError` inside the inner observable so one failure does not kill the outer stream.
+- Use `shareReplay({ bufferSize: 1, refCount: true })` for shared HTTP results, not bare `shareReplay(1)` on infinite sources.
+
+## 4. Change detection
+
+- With OnPush or zoneless, a view refreshes when a signal it reads changes, an input reference changes, a template event fires, or the `async` pipe emits. Setting a plain field from a `setTimeout` or a third-party callback does not refresh the view: make that field a signal.
+- Never fix a stale view with `ChangeDetectorRef.detectChanges()` sprinkled in callbacks, or `setTimeout(() => ...)`. Convert the state to a signal.
+- `ExpressionChangedAfterItHasBeenCheckedError` means a value changes during the check; move the write into a `computed`, an event handler, or `afterNextRender`.
+- Run DOM-measuring or browser-only code in `afterNextRender` / `afterEveryRender`, which do not run on the server.
+
+## 5. Dependency injection
+
+- Use `inject(Service)` in field initialisers; constructor injection is still valid in codebases that use it.
+- `@Injectable({ providedIn: 'root' })` for app-wide singletons. Provide per-feature services in route `providers` or a component's `providers` when each instance needs its own state.
+- Use `InjectionToken<T>` for config values, provided in `app.config.ts`.
+- `inject()` only works in an injection context; outside one, pass an `Injector` and use `runInInjectionContext`.
+- Use functional guards, resolvers and interceptors (`CanActivateFn`, `HttpInterceptorFn` with `provideHttpClient(withInterceptors([...]))`).
+
+## 6. Forms
+
+- Use typed reactive forms (`FormBuilder.nonNullable.group`, `FormControl<string>`) for new forms on versions before v22. Avoid `UntypedFormGroup` in new code.
+- On v22+, signal forms (`form()` with the `[formField]` directive) are stable; use them for new forms if the codebase has adopted them, and do not mix both styles inside one form.
+- Put validation in validators, not in submit handlers. Show errors from the control's state (`invalid && touched`).
+- Disable the submit button while pending and use `exhaustMap` (or a pending signal) to stop double submits.
+
+## 7. Tests
+
+1. Run the project's test command (`ng test`, which uses Vitest in new v21+ projects or Karma in older ones). Do not switch runners as a side effect.
+2. Standalone components: `TestBed.configureTestingModule({ imports: [UserCard] })`, then `const fixture = TestBed.createComponent(UserCard)`.
+3. Set signal inputs with `fixture.componentRef.setInput('user', user)`, then `await fixture.whenStable()` (or `fixture.detectChanges()` in zone-based tests).
+4. Use `provideHttpClient()` plus `provideHttpClientTesting()` and `HttpTestingController` to assert requests; call `httpMock.verify()` after each test.
+5. Query by role, text or `data-testid`, and assert what the user sees.
+
+## Stop and ask the user
+
+- Moving the app from zone.js to zoneless, or from Karma to Vitest.
+- A migration schematic touches more than the files you were asked to change.
+- Upgrading the Angular major is the simplest fix.
+
+## Never
+
+- Never leave a `subscribe()` on a long-lived observable without teardown.
+- Never mutate inputs or objects held in signals in place.
+- Never call `detectChanges()` or `setTimeout` to paper over a state that is not reactive.
+- Never bypass sanitisation with `bypassSecurityTrustHtml` on user content.
+
+## Report back
+
+List the files changed, the Angular version assumptions you relied on, the build and test commands you ran with their results, and any migration left for later.

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

@@ -0,0 +1,16 @@
+{
+  "should_trigger": [
+    "Convert this Angular NgModule feature to standalone components",
+    "My Angular component subscribes to valueChanges and never unsubscribes, fix the leak",
+    "Replace the @Input decorators in this Angular component with signal inputs",
+    "The Angular view doesn't refresh after the websocket callback sets a field, using OnPush",
+    "Write a TestBed test for the Angular user card component that sets a signal input"
+  ],
+  "should_not_trigger": [
+    "Fix the TypeScript strict null errors in our Express server",
+    "Write a Vue 3 composable that wraps a websocket connection",
+    "My Svelte 5 $effect runs in an infinite loop",
+    "Set up Playwright end-to-end tests for the checkout flow",
+    "Review this Nuxt change for hydration mismatches"
+  ]
+}

package/skills/api-client-integration/SKILL.md

@@ -0,0 +1,86 @@
+---
+name: api-client-integration
+description: Builds a dependable client or connector for any third-party HTTP API that has no dedicated Kete Loom skill, covering API-key and OAuth 2.0 auth with single-flight token refresh, connect and read timeouts, retries with exponential backoff and jitter limited to idempotent calls or calls carrying an idempotency key, Retry-After and rate-limit headers, cursor, offset and Link-header pagination, HMAC webhook signature checks on the raw body, and recorded-response contract tests, all shaped to the integration patterns the repo already uses. Use when wiring up a new vendor or partner REST API, writing a sync job or connector against an external service, or hardening a flaky integration that times out, hits 429s or double-submits.
+license: MIT
+compatibility: Any Agent Skills host. Live calls need network access to the vendor; tests use the project's HTTP mocking or record/replay library.
+metadata:
+  kete-loom/version: "0.1.0"
+  kete-loom/category: integrations
+  kete-loom/risk: network
+  kete-loom/owner: "Kete-org"
+---
+
+# API client integration
+
+Build a client for an external API that fails predictably: bounded time per call, safe retries, honest errors, no secrets in logs, and tests that run without the network.
+
+If a provider-specific Kete Loom skill exists (for example `stripe-integration`, `paystack-integration`, `github-api-automation`, `slack-app-integration`, `jira-integration`, `accounting-api-integration`), use it for that provider; this skill is the general method. For deciding error and retry policy in your own code generally, see `error-handling-patterns`.
+
+## 0. Read before writing
+
+1. **Find the house pattern.** Search the codebase for existing integrations: a shared HTTP client, base class, retry helper, secrets loader, logging redaction, test fixtures or cassettes. Copy its structure, naming, config style and error types. A new integration that looks unlike the others is a defect.
+2. **Read the vendor docs** for: base URLs per environment, auth method and token lifetime, rate limits and their headers, pagination style, which endpoints accept an idempotency key, error format, webhook signing, API versioning header, sandbox availability. Note the doc URL and date in a comment or the integration's README. Never invent an endpoint, header or limit; if the docs don't say, ask the user or treat it as unknown.
+3. **Prefer the official SDK** if it is maintained, typed and already allowed in the project; wrap it the same way. Hand-roll only when there isn't one or it's unsuitable, and say why.
+4. **Stop and ask** before adding a new dependency, before any call that creates, charges, sends or deletes in a live account, and if credentials would need to be stored somewhere new.
+
+## 1. Shape of the client
+
+- One module per vendor with a small interface the app calls (`getCustomer`, `listInvoices`), hiding transport details. Callers never build URLs.
+- Config from the environment or the secrets manager: base URL, credentials, timeouts. Sandbox and production differ only by config.
+- Map vendor responses to your own types at the boundary; validate the fields you rely on and fail loudly on schema surprises.
+- Typed errors: distinguish auth (401/403), not found, validation (400/422), rate limited (429), retryable server/network (5xx, timeouts, resets) and unknown. Keep the vendor's request ID in the error.
+
+## 2. Auth
+
+- API keys: send in the header the vendor specifies, not in query strings (they end up in logs); if the vendor only accepts a query parameter, redact URLs before logging them.
+- OAuth 2.0 client credentials or refresh tokens: cache the access token with its expiry, refresh a little before expiry, and make refresh **single-flight** so concurrent requests share one refresh. On a 401, refresh once and retry once; a second 401 is a real auth error.
+- Rotating refresh tokens: persist the new refresh token atomically before using the new access token, or you lock yourself out.
+- Redact `Authorization`, cookies, tokens and secrets from logs, errors and recorded fixtures.
+
+## 3. Timeouts, retries, idempotency
+
+Details and pseudocode: `references/resilience.md`.
+
+- Set a connect timeout and a total/read timeout on every call (no library defaults of "forever").
+- Retry only: network errors, timeouts, 429, 502, 503, 504 (and 500 if the vendor documents it as transient). Never retry 4xx validation or auth errors.
+- Retry a non-idempotent call (`POST` that creates, charges or sends) **only** if it carries an idempotency key the vendor honours, reused unchanged across attempts. Otherwise surface the error and reconcile.
+- Exponential backoff with full jitter, a max attempt count (3 to 5) and an overall deadline. Honour `Retry-After` (seconds or HTTP date) over your own delay.
+- Respect published rate limits proactively with a client-side limiter where the vendor publishes them; read remaining-quota headers if provided.
+- Add a circuit breaker or bulkhead only if the repo already has one or the user asks.
+
+## 4. Pagination
+
+Use the vendor's style; never assume page numbers. Cursor or `next` token: loop until it's absent. `Link: <...>; rel="next"`: follow the URL as given. Offset/limit: stop on a short page, and be aware rows can shift between pages. Expose an iterator or async generator; cap total pages for safety and log when the cap is hit.
+
+## 5. Webhooks from the vendor
+
+- Verify the signature on the **raw request body bytes** with the vendor's algorithm (commonly HMAC-SHA256) and a constant-time compare; reject if the header is missing.
+- Check the timestamp tolerance where the vendor signs one (Standard Webhooks uses `webhook-id`, `webhook-timestamp`, `webhook-signature`).
+- Deduplicate by event ID, return 2xx fast, process asynchronously, and handle out-of-order delivery by re-fetching the resource when order matters.
+
+## 6. Tests
+
+- Unit-test the client against recorded or hand-built responses, with the project's mock or record/replay tool (for example nock, msw, responses, respx, VCR.py, WireMock). Scrub secrets from recordings.
+- Cover: success, each error class, 429 with `Retry-After`, timeout, token expiry then refresh, multi-page listing, empty page, malformed body, bad webhook signature.
+- One opt-in smoke test against the sandbox, skipped unless credentials are present; never against production.
+
+## Never
+
+- Never log full request or response bodies containing personal data or secrets.
+- Never retry in two layers (SDK and your wrapper) without knowing the combined count.
+- Never swallow an error and return an empty list; that looks like "no data".
+- Never hard-code a production URL or credential.
+
+## Report
+
+```
+## Integration: <vendor> (<SDK or hand-rolled>)
+Follows house pattern: <module it mirrors>
+Auth: <method>, refresh: <single-flight yes/no>
+Timeouts: connect <s>, total <s> | Retries: <codes>, max <n>, idempotency: <how>
+Rate limits: <documented limit and handling>
+Pagination: <style>
+Webhooks: <verification method, dedupe> | n/a
+Tests: <command> -> <result>; sandbox smoke: <ran/skipped>
+Unknown from docs: <items to confirm with the vendor>
+```

package/skills/api-client-integration/evals/triggers.json

@@ -0,0 +1,16 @@
+{
+  "should_trigger": [
+    "Write a connector for the Acme Logistics REST API: OAuth client credentials, cursor pagination and rate limits",
+    "Our sync job against the vendor's API keeps getting 429s and sometimes creates duplicate records on retry. Make the client robust.",
+    "Add a client for the partner's shipment-tracking API that matches how our other integrations in src/integrations are built",
+    "The CRM vendor's access token expires mid-sync and several workers all refresh at once. Fix the token handling in our client.",
+    "Build a typed wrapper around this third-party weather API with timeouts, retries and recorded tests"
+  ],
+  "should_not_trigger": [
+    "Add Stripe Checkout and the customer portal to our billing page",
+    "Design the endpoints and error format for our own public REST API",
+    "Set up an OpenAPI spec and mock server so the frontend and backend teams can work in parallel",
+    "Write a GitHub App that labels new issues using the REST API",
+    "Explain in general when a function should throw versus return an error value"
+  ]
+}

package/skills/api-client-integration/references/resilience.md

@@ -0,0 +1,57 @@
+# Resilience details for API clients
+
+## Retry decision
+
+```
+retryable(response or error, request):
+  if error is connect error, DNS failure, connection reset, timeout: transient = true
+  elif status in (429, 502, 503, 504): transient = true
+  elif status == 500 and vendor documents 500 as transient: transient = true
+  else: return false
+  if request.method in (GET, HEAD, OPTIONS, PUT, DELETE): return transient
+  return transient and request.has_idempotency_key   # POST/PATCH only with a key
+```
+
+`PUT` and `DELETE` are idempotent by HTTP semantics (RFC 9110), but check the vendor actually implements them that way.
+
+## Backoff with full jitter
+
+```
+delay(attempt) = random(0, min(cap, base * 2^attempt))   # base ~0.5s, cap ~30s
+if Retry-After present:
+  delay = seconds value, or (HTTP-date - now)             # never shorter than the server asked
+stop when attempt == max_attempts or now + delay > deadline
+```
+
+Log each retry at debug/info with attempt number, status and vendor request ID; log the final failure once at warn/error.
+
+## Idempotency keys
+
+- Generate one key per logical operation (UUID v4), store it with the local record (order, payout, message) before the first attempt, and reuse it on every retry and on a later replay.
+- Header name is vendor-specific (`Idempotency-Key` is common; some use a body field or a client reference ID). Check the docs.
+- Note the vendor's key expiry window; replays after it can create duplicates.
+- If the vendor has no idempotency support, don't retry creates; instead look the object up by your own reference before trying again.
+
+## Rate limits
+
+- Common headers: `Retry-After`; vendor-specific `X-RateLimit-Limit` / `-Remaining` / `-Reset`; the IETF `RateLimit` / `RateLimit-Policy` fields are still a draft, so treat them as vendor-specific too.
+- Use a token bucket sized below the documented limit, shared across workers if the limit is per account (for example in Redis), not per process.
+- Bulk or batch endpoints are often cheaper against the limit than many single calls.
+
+## Token refresh, single-flight
+
+```
+get_token():
+  if cached and cached.expires_at - now > skew (60s): return cached
+  if refresh_in_progress: await it; return cached
+  start refresh; on success persist (new refresh token first), cache, resolve waiters
+  on failure: reject waiters, clear in-progress flag
+```
+
+In multi-process deployments, store the token in a shared cache with a lock, or accept one refresh per process if the vendor allows parallel tokens.
+
+## Timeouts
+
+- Connect timeout small (2 to 5 s); read or total timeout based on the endpoint's documented or observed p99 plus margin.
+- The overall deadline (all retries) must be less than the caller's own timeout, such as an HTTP handler or queue visibility timeout.
+- Streaming or file downloads: use an idle/read timeout rather than a total timeout.

package/skills/api-design/SKILL.md

@@ -0,0 +1,96 @@
+---
+name: api-design
+description: HTTP API contract design covering resource modelling, REST versus RPC-style endpoints, status codes and RFC 9457 problem details, cursor pagination, filtering, versioning and deprecation headers, Idempotency-Key retries, OpenAPI-first contracts, and when GraphQL is worth it. Use when designing a new HTTP or GraphQL API, adding endpoints to an existing one, reviewing an API contract or OpenAPI file before it ships, or planning a breaking change.
+license: MIT
+compatibility: Any Agent Skills host. Language and framework neutral; examples are HTTP and OpenAPI YAML.
+metadata:
+  kete-loom/version: "0.1.0"
+  kete-loom/category: coding
+  kete-loom/risk: writes-files
+  kete-loom/owner: "Kete-org"
+---
+
+# API design
+
+Design the contract first, then the code. A published API is a promise: every field, status code and default you ship is something a client will depend on.
+
+## Before you design
+
+1. Find what already exists: search the codebase for an OpenAPI/Swagger file, GraphQL schema, route definitions and an existing error format. **Match the house conventions** (casing, error shape, pagination style) even where this skill would choose differently; consistency beats local perfection.
+2. Name the consumers: browser app, mobile app (slow to update, so breaking changes hurt for months), partners, internal services.
+3. **Stop and ask the user** when you don't know: who the clients are, whether the API is public or internal, the auth model, or whether a breaking change is acceptable.
+
+## Choose the style
+
+| Situation | Choose |
+|---|---|
+| CRUD-ish domain, many clients, caching matters | REST (resources + HTTP methods) |
+| Actions that don't map to a resource (`send`, `recalculate`) | REST with a sub-resource or action resource (`POST /invoices/{id}/send`), not a verb in every path |
+| Internal service-to-service, strict schemas, streaming | gRPC or another RPC framework |
+| Many client shapes over a graph of data, one team owns the schema | GraphQL, if you accept the costs below |
+
+GraphQL costs: HTTP caching mostly lost, query cost limits and depth limits needed, N+1 resolvers (needs batching such as DataLoader), errors returned with `200`, and authorization per field. Don't choose it only to avoid writing endpoints.
+
+## Resource modelling (REST)
+
+1. Nouns, plural, lowercase, hyphenated: `/orders`, `/orders/{orderId}/line-items`. Nest at most one level; beyond that, link by id.
+2. Methods mean what HTTP says: `GET` safe, `PUT` and `DELETE` idempotent, `PATCH` partial update, `POST` create or action.
+3. IDs are opaque strings to clients. Never expose auto-increment IDs on public APIs if enumeration matters.
+4. One casing for JSON fields across the whole API (pick `camelCase` or `snake_case`, match what exists).
+5. Timestamps in RFC 3339 / ISO 8601 UTC (`2026-03-01T12:00:00Z`). Money as integer minor units plus a currency code, or a decimal string; never a float.
+6. Return the created resource and `Location` header on `201`. Return `204` only when there is truly nothing to say.
+7. Design for additive change: clients must ignore unknown fields, and enums must tolerate new values.
+
+## Errors
+
+- Use the status code that matches the failure (table in `references/conventions.md`). `400` malformed, `401` unauthenticated, `403` not allowed, `404` not found (also for "exists but you can't see it"), `409` conflict, `422` validation, `429` rate limited, `5xx` server fault.
+- Body uses **Problem Details (RFC 9457)** with `Content-Type: application/problem+json`: `type`, `title`, `status`, `detail`, `instance`, plus extension members such as `errors` for field-level validation.
+- Never leak stack traces, SQL or internal hostnames in `detail`.
+- Error `type` URIs and machine-readable codes are part of the contract. Clients branch on them, not on `detail` text.
+
+## Pagination, filtering, sorting
+
+1. Default to **cursor pagination** for anything that grows: `?limit=50&cursor=<opaque>`, respond with `next_cursor` (null at the end). Offset pagination is fine for small, stable admin lists.
+2. Always enforce a maximum `limit`, and a default when it is absent.
+3. Cursors are opaque (encode the sort key and id); never let clients build them.
+4. Filtering via plain query params (`?status=paid&created_after=...`). Sorting via `?sort=-created_at,id`, always with a unique tiebreaker so pages are stable.
+5. Only add filters someone needs. Each one is an index and a promise.
+
+## Idempotency and concurrency
+
+- Make retryable `POST`s safe with an `Idempotency-Key` request header: store key + request fingerprint + response for a retention window; replay the stored response on a repeat; return `422` or `409` if the same key arrives with a different body. Required for payments and anything that sends messages or moves money.
+- Prevent lost updates with `ETag` + `If-Match` on `PUT`/`PATCH`; return `412 Precondition Failed` on mismatch.
+- Rate limit with `429` and a `Retry-After` header.
+
+## Versioning and deprecation
+
+1. Prefer evolving one version additively. A breaking change is: removing or renaming a field, changing a type or meaning, adding a required input, tightening validation, changing a default or status code.
+2. When you must break, pick one scheme and keep it: URL major version (`/v2/...`, simplest for public APIs) or a header/media-type version. Don't mix.
+3. Deprecate before removing: announce, send the `Deprecation` header (RFC 9745) and a `Sunset` header (RFC 8594) with the removal date, and a `Link` with `rel="deprecation"` to the migration guide. Measure usage before switching off.
+4. **Stop and ask** before shipping any breaking change to a public or mobile-facing API.
+
+## OpenAPI contract
+
+1. Write or update the OpenAPI document (3.1 or later; 3.2 was published in September 2025, so check what your generators and linters support before adopting it) **before** the handler code, and review it as the source of truth.
+2. Every operation has an `operationId`, request/response schemas under `components/schemas`, and documented error responses using a shared problem-details schema.
+3. Lint it (for example Spectral or Redocly CLI, whichever the repo already uses) and validate requests/responses against it in tests where possible.
+4. See `references/conventions.md` for a skeleton.
+
+## Never
+
+- Verbs in resource paths (`/getUser`), or `200` with `{"error": ...}` on REST endpoints.
+- Unbounded list endpoints.
+- Accepting a price, role or owner id from the client when the server can derive it.
+- Silent breaking changes in a "minor" release.
+
+## Report back
+
+When you design or review an API, return:
+
+```
+Style: REST | RPC | GraphQL, and why (one line)
+Endpoints: METHOD path → status codes (one line each)
+Contract file: path to OpenAPI/schema written or changed
+Breaking changes: none | list
+Open questions: what the user must decide
+```

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

@@ -0,0 +1,18 @@
+{
+  "should_trigger": [
+    "Design the REST endpoints for a bookings service: create, list, cancel, reschedule",
+    "What should our error response body look like? Right now every endpoint returns something different",
+    "Our /transactions list endpoint times out with big accounts, how should we paginate it?",
+    "We need to rename the customer_name field in the public API without breaking the mobile app",
+    "Review this openapi.yaml before we publish it to partners",
+    "Should we build the partner API in GraphQL or REST?"
+  ],
+  "should_not_trigger": [
+    "Integrate Stripe checkout into our Node backend",
+    "Restructure the service so the domain logic doesn't import Express or the ORM",
+    "Write an ADR recording why we picked gRPC for internal services",
+    "Write the SQL migration that adds an index on orders.created_at",
+    "Add JWT authentication with refresh tokens to the login endpoint",
+    "Break the reporting feature into an ordered implementation plan"
+  ]
+}

package/skills/api-design/references/conventions.md

@@ -0,0 +1,133 @@
+# API conventions reference
+
+Read this when choosing a status code, writing an error body, or starting an OpenAPI file.
+
+## Status codes
+
+| Code | Use for |
+|---|---|
+| 200 OK | Successful read, or update that returns the resource |
+| 201 Created | Resource created; include `Location` and the body |
+| 202 Accepted | Work queued; return a status resource to poll |
+| 204 No Content | Success with no body (for example `DELETE`) |
+| 304 Not Modified | Conditional `GET` with matching `If-None-Match` |
+| 400 Bad Request | Malformed syntax, unparsable JSON, wrong types |
+| 401 Unauthorized | Missing or invalid credentials; send `WWW-Authenticate` |
+| 403 Forbidden | Authenticated but not allowed |
+| 404 Not Found | No such resource, or caller may not know it exists |
+| 405 Method Not Allowed | Method not supported on this path; send `Allow` |
+| 409 Conflict | State conflict (duplicate, wrong state transition) |
+| 412 Precondition Failed | `If-Match` ETag mismatch |
+| 415 Unsupported Media Type | Wrong `Content-Type` |
+| 422 Unprocessable Content | Well-formed but fails validation |
+| 429 Too Many Requests | Rate limited; send `Retry-After` |
+| 500 Internal Server Error | Unexpected server fault |
+| 503 Service Unavailable | Overloaded or down for maintenance; send `Retry-After` |
+
+## Problem details (RFC 9457)
+
+```http
+HTTP/1.1 422 Unprocessable Content
+Content-Type: application/problem+json
+
+{
+  "type": "https://api.example.com/problems/validation-error",
+  "title": "Request validation failed",
+  "status": 422,
+  "detail": "2 fields are invalid.",
+  "instance": "/orders/req_7f3a",
+  "errors": [
+    { "pointer": "#/email", "detail": "must be a valid email address" },
+    { "pointer": "#/quantity", "detail": "must be at least 1" }
+  ]
+}
+```
+
+`type` defaults to `about:blank` when no specific type exists. `errors` is an extension member (RFC 9457 shows this shape, with `pointer` as a JSON Pointer into the request body); keep its shape identical everywhere.
+
+## Cursor pagination
+
+```http
+GET /orders?limit=2&cursor=eyJjIjoiMjAyNi0wMy0wMVQxMjowMDowMFoiLCJpZCI6Im9yZF85In0
+```
+
+```json
+{
+  "data": [ { "id": "ord_8" }, { "id": "ord_7" } ],
+  "next_cursor": "eyJjIjoiMjAyNi0wMi0yOFQwOTowMDowMFoiLCJpZCI6Im9yZF83In0"
+}
+```
+
+Server side: decode the cursor to `(created_at, id)` and query `WHERE (created_at, id) < (:c, :id) ORDER BY created_at DESC, id DESC LIMIT :limit + 1`. Fetching one extra row tells you whether `next_cursor` is null. Back it with an index on the sort columns.
+
+## Idempotency-Key flow
+
+1. Client sends `Idempotency-Key: <uuid>` on `POST`.
+2. Server looks up the key scoped to the caller.
+   - Not found: insert a row (key, fingerprint of method+path+body, status `processing`), run the operation, store the response.
+   - Found, same fingerprint, finished: return the stored response unchanged.
+   - Found, same fingerprint, still processing: return `409`.
+   - Found, different fingerprint: return `422`.
+3. Expire keys after a documented window (24 hours is common).
+
+The `Idempotency-Key` header is specified in an IETF HTTPAPI working-group Internet-Draft; Stripe and other payment APIs use the same pattern.
+
+## Deprecation headers
+
+```http
+Deprecation: @1767225599
+Sunset: Thu, 31 Dec 2026 23:59:59 GMT
+Link: <https://api.example.com/docs/migrate-v2>; rel="deprecation"
+```
+
+`Deprecation` (RFC 9745) carries a structured-field date (`@` + Unix seconds). `Sunset` (RFC 8594) carries an HTTP-date.
+
+## OpenAPI skeleton
+
+```yaml
+openapi: 3.1.0
+info: { title: Orders API, version: 1.0.0 }
+paths:
+  /orders:
+    get:
+      operationId: listOrders
+      parameters:
+        - { name: limit, in: query, schema: { type: integer, minimum: 1, maximum: 100, default: 50 } }
+        - { name: cursor, in: query, schema: { type: string } }
+      responses:
+        "200":
+          description: A page of orders
+          content:
+            application/json:
+              schema: { $ref: "#/components/schemas/OrderPage" }
+        default:
+          description: Error
+          content:
+            application/problem+json:
+              schema: { $ref: "#/components/schemas/Problem" }
+components:
+  schemas:
+    Problem:
+      type: object
+      properties:
+        type: { type: string, format: uri-reference }
+        title: { type: string }
+        status: { type: integer }
+        detail: { type: string }
+        instance: { type: string, format: uri-reference }
+    Order:
+      type: object
+      required: [id, status, total_minor, currency, created_at]
+      properties:
+        id: { type: string }
+        status: { type: string, enum: [pending, paid, cancelled] }
+        total_minor: { type: integer }
+        currency: { type: string, minLength: 3, maxLength: 3 }
+        created_at: { type: string, format: date-time }
+    OrderPage:
+      type: object
+      required: [data, next_cursor]
+      properties:
+        data: { type: array, items: { $ref: "#/components/schemas/Order" } }
+        next_cursor: { type: [string, "null"] }
+```

package/skills/architecture-decision-records/SKILL.md

@@ -0,0 +1,98 @@
+---
+name: architecture-decision-records
+description: Writes and maintains Architecture Decision Records (ADRs), deciding whether a choice deserves one, filling a short template (Nygard sections plus options considered) with context, the options weighed, the decision and its consequences, numbering and storing it next to the code, and superseding old records instead of rewriting them. Use when the user wants to record or document a technical decision, start an ADR log in a repo, or update the status of an earlier decision.
+license: MIT
+compatibility: Any Agent Skills host. Writes Markdown files; git is optional.
+metadata:
+  kete-loom/version: "0.1.0"
+  kete-loom/category: docs
+  kete-loom/risk: writes-files
+  kete-loom/owner: "Kete-org"
+---
+
+# Architecture decision records
+
+An ADR captures one decision, the reason for it, and what it costs, so a future reader can tell whether the reason still holds. It is short, dated and never silently edited.
+
+## Does this need an ADR?
+
+Write one when the decision is **hard to reverse, affects more than one module or team, or someone will later ask "why did we do it this way?"** Examples: choosing a database, message broker, auth provider, framework, API style, deployment model; adopting or dropping an architectural pattern; a deliberate trade-off against a stated quality (accepting eventual consistency, skipping multi-region).
+
+Don't write one for: library patch upgrades, naming, formatting, decisions fully captured by a ticket, or anything trivially reversible. Say so and stop.
+
+## Steps
+
+1. **Find the log.** Search the repo for an existing ADR directory: `docs/adr/`, `doc/adr/` (the adr-tools default), `docs/decisions/`, `doc/architecture/decisions/`, `adr/`, or an `.adr-dir` file (adr-tools stores the chosen directory there). Use it and its template and numbering exactly. If none exists, propose `docs/adr/` and create `0001-record-architecture-decisions.md` first, then the user's ADR.
+2. **Gather the facts.** You need: the problem and forces (constraints, requirements, deadlines), at least two real options (including "do nothing" when plausible), the chosen option, and who decided. **Stop and ask the user** for anything missing. Never invent the reasons, the alternatives considered or the people involved.
+3. **Number and name.** Next free four-digit number, kebab-case title stating the decision: `0007-use-postgres-for-event-store.md`. Numbers are never reused.
+4. **Write it** with the template below. Keep it to one or two screens. Link to longer analysis rather than pasting it.
+5. **Set the status** (see lifecycle). New records start as `Proposed` unless the user says the decision is made.
+6. **Supersede, don't rewrite.** When a decision changes, write a new ADR, set the old one's status to `Superseded by ADR-00NN` and add `Supersedes ADR-00MM` to the new one. Only typo fixes and status lines change in accepted ADRs.
+7. **Index.** If the log has a README or index listing ADRs, add the new line.
+
+## Template
+
+```markdown
+# ADR-0007: Use Postgres for the event store
+
+- Status: Proposed | Accepted | Rejected | Deprecated | Superseded by ADR-00NN
+- Date: 2026-03-01
+- Deciders: names or roles
+- Supersedes: ADR-00MM (if any)
+
+## Context
+
+What problem forces a decision now. Constraints, requirements, quality
+attributes that matter (cost, latency, team skills, compliance). Facts, not
+the conclusion.
+
+## Options considered
+
+1. **Postgres with an append-only events table**: pros, cons.
+2. **EventStoreDB**: pros, cons.
+3. **Kafka as the system of record**: pros, cons.
+
+## Decision
+
+We will use option 1 because <the deciding reasons, tied to the context>.
+
+## Consequences
+
+- Positive: what gets easier.
+- Negative: what gets harder or what we accept (the trade-off, stated plainly).
+- Follow-ups: work this creates, and the signal that would make us revisit it.
+```
+
+## Status lifecycle
+
+```
+Proposed ──▶ Accepted ──▶ Deprecated
+    │            └──────▶ Superseded by ADR-NNNN
+    └──▶ Rejected
+```
+
+- `Proposed`: under discussion, usually in a pull request.
+- `Accepted`: merged and in force.
+- `Rejected`: kept on purpose, so the option isn't re-litigated without new facts.
+- `Deprecated`: no longer relevant (the system it governed is gone).
+- `Superseded`: replaced by a newer ADR, linked both ways.
+
+## Where to store them
+
+- In the repo of the code they govern, as Markdown, reviewed in pull requests like code. Cross-cutting decisions go in a shared architecture repo, linked from each affected repo.
+- If the team uses a tool (adr-tools, Log4brains), follow its file layout and commands instead of hand-numbering.
+
+## Writing rules
+
+- One decision per ADR. If you need "and" in the title, split it.
+- The Consequences section must include at least one negative. A decision with no cost wasn't a decision.
+- Write the context so a new hire understands it without the meeting.
+- Dates are absolute (`2026-03-01`), never "last sprint".
+
+## Report back
+
+```
+ADR: path/to/NNNN-title.md (status)
+Updated: older ADRs whose status changed, index file
+Missing facts: anything you left as a question for the user
+```