@ketecode/loom 0.0.0-stage → 0.1.0

package/skills/ai-media-generation/SKILL.md

@@ -0,0 +1,89 @@
+---
+name: ai-media-generation
+description: Product features built on hosted generative image, video, speech and music models, including prompt templates with fixed parameters and seeds, long-running jobs submitted then polled or confirmed by signed webhooks, per-user quotas and cost estimates before submission, input and output moderation, C2PA content credentials and AI-generated labels, and copying results to your own storage before provider URLs expire. Use when adding text-to-image, image editing, text-to-video or text-to-speech generation to an app, wiring up a generation provider's async job API, or controlling the cost, safety and storage of generated media.
+license: MIT
+compatibility: Any Agent Skills host. Live calls need network access and an API key for the chosen provider. Examples are provider-neutral; check the provider's current API reference for model names and parameters.
+metadata:
+  kete-loom/version: "0.1.0"
+  kete-loom/category: ai
+  kete-loom/risk: network
+  kete-loom/owner: "Kete-org"
+---
+
+# AI media generation
+
+Generation APIs are slow, priced per output, change model names often, and can produce content you are responsible for. Build the feature as a job pipeline with limits, moderation and your own storage, not as a single request in a page handler.
+
+## 0. Before you start
+
+1. Ask the user, or find in the repo: which provider and model, which media (image, edit, video, speech, music), expected volume, and who the end users are (internal staff, logged-in customers, anonymous public).
+2. Read the provider's current API reference and pricing page for that model. Model IDs, sizes, durations and prices change; never copy them from memory or old code. Note: max resolution/duration, whether the call is synchronous or a job, output format (base64 in the response vs a URL), how long output URLs live, rate limits, and whether the provider adds C2PA or a watermark.
+3. **Stop and ask** before building a public, anonymous generation endpoint, any feature that edits images of real people, voice cloning, or anything aimed at children. These need explicit policy decisions.
+
+## 1. Prompt and parameter design
+
+- Keep a server-side **prompt template** per feature: fixed style instructions plus the user's text in a clearly delimited slot. Users choose from options (style, aspect ratio, length) that map to allowed parameter values; never pass raw user JSON as provider parameters.
+- Pin the **model ID and version** in config, not scattered in code, so an upgrade is a reviewed change. Record it with every output.
+- Store the **full request** (template version, final prompt, parameters, seed if supported) with each job, so results can be reproduced and audited.
+- Validate inputs at the boundary: prompt length, uploaded image type/size/dimensions, audio length. Strip metadata (EXIF GPS) from user uploads before sending them.
+- For edits with masks or reference images, check the provider's format rules (same size, alpha channel, size limit) before submitting, not after a failed job.
+
+## 2. Job flow
+
+Treat every generation as a job, even if the provider responds synchronously today.
+
+1. `POST /generations` in your API: authenticate, check quota (section 3), moderate the input (section 4), insert a `generation_jobs` row (`id`, `user_id`, `status=queued`, `provider`, `model`, `request`, `estimated_cost`), and return `202` with the job ID.
+2. A worker submits to the provider with an idempotency key if the API supports one (otherwise store the provider job ID immediately so a retry doesn't submit twice). Save `provider_job_id`, set `status=running`.
+3. Learn the result by **webhook** when offered: verify the signature on the raw body with the provider's secret and timestamp tolerance, look up the job by provider ID, and treat duplicate or out-of-order deliveries as normal. Back it with a **poll** fallback: exponential backoff (for example 2 s doubling to 30 s), a hard deadline per media type, then mark `timed_out` and cancel at the provider if it supports cancel.
+4. On success: download the output, check type and size, run output moderation, add provenance (section 5), store it (section 6), set `status=succeeded`, record actual cost.
+5. On failure: map provider errors to `failed_safety` (prompt or output refused), `failed_invalid` (bad parameters), `failed_provider` (5xx, timeouts). Retry only `failed_provider`, a bounded number of times. Never retry a safety refusal by rewording the prompt automatically.
+6. The client polls `GET /generations/:id` or subscribes to updates; it never talks to the provider or sees the provider key.
+
+See `references/job-pipeline.md` for a table schema, a poll loop and a webhook handler outline.
+
+## 3. Cost and latency
+
+- Estimate cost **before** submitting (resolution x count, seconds of video, characters of speech, using the provider's price table) and check it against a per-user and a global daily budget. Reject or queue when over.
+- Cap `n` (outputs per request), resolution and duration server-side. Default to the cheapest setting that meets the feature's need; offer "high quality" as an explicit, metered choice.
+- Rate-limit per user and per IP; generation endpoints attract abuse.
+- Cache identical requests (same template, prompt, parameters and seed) when outputs are deterministic enough for the feature.
+- Show realistic progress: images take seconds, video can take minutes. Never hold an HTTP request open for a video job.
+- Log latency and cost per job and alert on spend spikes.
+
+## 4. Content safety
+
+- Moderate the **input** (prompt text, uploaded images) before paying for a generation, and the **output** before showing it, with the provider's moderation API or your own classifier. Provider-side filters are a floor, not your whole policy.
+- Write down the policy with the user: disallowed content, real-person likeness, logos and trademarks, minors. Block and log; let users report outputs.
+- Keep a reviewable record (prompt, output reference, moderation result, user) for abuse investigations, with a retention period the user agrees to.
+- Don't present generated people, voices or events as real. For voice, require consent records for any cloned voice.
+
+## 5. Provenance and labelling
+
+- Keep any **C2PA content credentials** or watermark the provider embeds; re-encoding, resizing or stripping metadata can remove the C2PA manifest. If you transform outputs, re-sign with your own C2PA manifest (for example with the open-source `c2patool` or a C2PA SDK) or keep the original alongside.
+- Label generated media as AI-generated in the UI and in alt text or metadata where the media is published.
+- Transparency rules such as Article 50 of the EU AI Act, and platform rules, can require machine-readable marking and visible disclosure. **Ask the user's legal or compliance owner** which apply; this skill does not give legal advice.
+
+## 6. Storing outputs
+
+- Provider output URLs are often temporary (some expire within an hour). Copy every output to your own object storage as soon as the job succeeds; never store the provider URL as the permanent link.
+- Write with a generated key (`generations/<job_id>/<n>.<ext>`), the right `Content-Type`, private by default, served through signed URLs or a CDN with access checks.
+- Keep metadata in your database: job ID, user, model and version, prompt, parameters, seed, cost, moderation result, checksum, dimensions/duration.
+- Set lifecycle rules for drafts and failed jobs, and delete outputs when the user deletes their account.
+- Post-process with the right tool: resize/convert images with the project's image library; trim, transcode or package video and audio with the ffmpeg-media-processing skill.
+
+## Never
+
+- Never call a generation API from the browser or mobile app with your provider key.
+- Never submit without a quota and cost check, or let a client choose unbounded `n`, resolution or duration.
+- Never show an output that skipped output moderation, or auto-retry a safety refusal.
+- Never rely on provider URLs for storage.
+
+## Stop and ask the user
+
+- Provider and model choice when not given, and the monthly budget.
+- Content policy, likeness and voice-cloning rules, and labelling obligations.
+- Data handling: whether prompts and uploads may be used by the provider for training (check the provider's data terms), and retention periods.
+
+## Report back
+
+Provider and pinned model, the job states and where each transition happens, cost limits set, moderation points, provenance handling, storage location and retention, and anything taken from docs you could not confirm.

package/skills/ai-media-generation/evals/triggers.json

@@ -0,0 +1,16 @@
+{
+  "should_trigger": [
+    "Add a feature where users type a prompt and get four product mockup images from an image generation API",
+    "Our text-to-video jobs take minutes, how should we poll the provider and notify the user when it's done?",
+    "Generated images disappear after an hour because we saved the Replicate output URL",
+    "Put per-user limits on AI image generation so one customer can't run up a huge bill",
+    "Label AI-generated images and keep their C2PA content credentials when we resize them"
+  ],
+  "should_not_trigger": [
+    "Add structured JSON output and retries to our chatbot's LLM calls",
+    "Rewrite this system prompt so the support bot stops making up refund policies",
+    "Compress our product videos to H.264 and make thumbnails every ten seconds",
+    "Build a RAG pipeline over our help-centre articles with hybrid search",
+    "Make a launch video in React with animated captions"
+  ]
+}

package/skills/ai-media-generation/references/job-pipeline.md

@@ -0,0 +1,76 @@
+# Generation job pipeline
+
+Provider-neutral shapes. Map field names to your provider's API reference.
+
+## Table
+
+```sql
+CREATE TABLE generation_jobs (
+  id               uuid PRIMARY KEY,
+  user_id          uuid NOT NULL,
+  status           text NOT NULL CHECK (status IN
+                     ('queued','running','succeeded','failed_safety','failed_invalid','failed_provider','timed_out','canceled')),
+  provider         text NOT NULL,
+  model            text NOT NULL,          -- pinned model ID and version
+  template_version text NOT NULL,
+  request          jsonb NOT NULL,         -- final prompt, parameters, seed
+  provider_job_id  text UNIQUE,
+  estimated_cost   numeric(12,6) NOT NULL,
+  actual_cost      numeric(12,6),
+  attempts         int NOT NULL DEFAULT 0,
+  error            text,
+  outputs          jsonb,                  -- [{ key, content_type, bytes, sha256, width, height, duration_s }]
+  moderation       jsonb,
+  created_at       timestamptz NOT NULL DEFAULT now(),
+  deadline_at      timestamptz NOT NULL,
+  finished_at      timestamptz
+);
+```
+
+Guard state changes so a webhook and a poller can't both finish a job:
+
+```sql
+UPDATE generation_jobs SET status = 'succeeded', finished_at = now()
+WHERE id = $1 AND status = 'running';   -- 0 rows updated means someone else finished it
+```
+
+## Poll loop (worker)
+
+```ts
+async function pollUntilDone(job: Job) {
+  let delay = 2_000;
+  while (Date.now() < job.deadlineAt.getTime()) {
+    const p = await provider.getJob(job.providerJobId);           // GET the provider's job/prediction
+    if (p.status === 'succeeded') return finish(job, p.output);
+    if (['failed', 'canceled', 'aborted'].includes(p.status)) return fail(job, classify(p.error));
+    await sleep(delay + Math.random() * 500);                     // jitter
+    delay = Math.min(delay * 2, 30_000);
+  }
+  await provider.cancel?.(job.providerJobId);
+  return markTimedOut(job);
+}
+```
+
+Run polling in a queue worker, not in the request handler. On worker restart, resume every job in `running` from its `provider_job_id`.
+
+## Webhook handler
+
+1. Read the raw body (before any JSON parser).
+2. Verify the provider's signature headers with its signing secret using a constant-time compare, and reject timestamps outside a few minutes.
+3. Parse, find the job by `provider_job_id`; unknown ID -> `200` and log (don't make the provider retry forever).
+4. Enqueue `finish` / `fail` and return `2xx` quickly; downloading and moderation happen in the worker.
+
+Example of one provider's scheme (Replicate, checked against its docs): headers `webhook-id`, `webhook-timestamp`, `webhook-signature`; signed content `${id}.${timestamp}.${rawBody}`; HMAC-SHA256 keyed with the base64-decoded bytes of the part after the `whsec_` prefix (the official JS client's `validateWebhook` helper does this), signature compared as base64, secret fetched from `GET /v1/webhooks/default/secret`; the header can carry several space-separated `v1,<sig>` values. Its prediction statuses are `starting`, `processing`, `succeeded`, `failed`, `canceled` and `aborted`, and API prediction outputs are deleted after one hour by default, so copy them at once.
+
+## finish(job, output)
+
+1. Download each output with a size limit and timeout; check the content type by magic bytes, not the extension.
+2. Output moderation; on block set `failed_safety`, keep the evidence privately, don't show it.
+3. Keep or add provenance (C2PA manifest, label metadata).
+4. Upload to `generations/<job_id>/<n>.<ext>`, private, with `Content-Type` and checksum.
+5. Guarded `UPDATE` to `succeeded`, record `actual_cost`, notify the client.
+
+## Testing
+
+- Stub the provider client with recorded responses for success, safety refusal, invalid parameters, 5xx and a job that never finishes.
+- Test duplicate webhooks, a webhook arriving before the submit call returns, a bad signature (rejected), quota exceeded (rejected before any provider call), and a timed-out job (canceled at the provider).

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-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"] }
+```