rsc-universal 0.1.1

package/skills/api-connector-builder/references/pagination.md

@@ -0,0 +1,144 @@
+# Pagination — full code per style
+
+The universal rule: **loop until the API signals no next page.** Never a fixed
+page count. Expose results as a generator / async-iterator so callers stream
+instead of buffering the whole set in memory.
+
+(graphql.org/learn/pagination + REST pagination pattern guides, accessed
+2026-06-02.)
+
+## Offset / page number
+
+Simple, but it **drifts** when rows are inserted or deleted mid-walk (you skip or
+double-read) and gets **slow at large offsets** (the server scans and discards).
+Prefer cursor/keyset when the API offers it.
+
+```python
+def iter_offset(client, path, page_size=100):
+    offset = 0
+    while True:
+        body = client.get(path, params={"offset": offset, "limit": page_size}).json()
+        rows = body["data"]
+        if not rows:                  # empty page = exhausted
+            return
+        yield from rows
+        offset += len(rows)
+```
+
+```typescript
+export async function* iterOffset(get: (q: Record<string, number>) => Promise<any>, pageSize = 100) {
+  let offset = 0;
+  for (;;) {
+    const body = await get({ offset, limit: pageSize });
+    const rows = body.data as unknown[];
+    if (rows.length === 0) return;     // exhausted
+    yield* rows;
+    offset += rows.length;
+  }
+}
+```
+
+## Cursor / keyset
+
+The server returns an opaque cursor for the next page; you pass it back. **Stable
+under concurrent writes and fixed cost regardless of depth** — the strategy to
+prefer.
+
+```python
+def iter_cursor(client, path, page_size=100):
+    cursor = None
+    while True:
+        body = client.get(path, params={"cursor": cursor, "limit": page_size}).json()
+        yield from body["data"]
+        cursor = body.get("next_cursor")
+        if not cursor:                # cursor exhausted
+            return
+```
+
+## Link header (REST)
+
+The next page lives in the `Link` response header with `rel="next"`. Follow it
+until the header has no `next`.
+
+```python
+import re
+
+def iter_link(client, url):
+    while url:
+        resp = client.get(url)
+        yield from resp.json()
+        link = resp.headers.get("Link", "")
+        m = re.search(r'<([^>]+)>;\s*rel="next"', link)
+        url = m.group(1) if m else None   # no rel="next" = exhausted
+```
+
+```typescript
+function nextLink(header: string | null): string | null {
+  if (!header) return null;
+  const m = header.match(/<([^>]+)>;\s*rel="next"/);
+  return m ? m[1] : null;
+}
+
+export async function* iterLink(start: string, get: (u: string) => Promise<Response>) {
+  let url: string | null = start;
+  while (url) {
+    const res = await get(url);
+    yield* (await res.json()) as unknown[];
+    url = nextLink(res.headers.get("Link"));
+  }
+}
+```
+
+## GraphQL — Relay Cursor Connections
+
+The Relay spec returns `edges` (each with a `node` and `cursor`) and a `pageInfo`
+with `endCursor` and `hasNextPage`. Pass `endCursor` as the `after` argument of
+the next query and stop when `hasNextPage` is false.
+
+```python
+QUERY = """
+query($after: String) {
+  issues(first: 100, after: $after) {
+    edges { node { id title } }
+    pageInfo { endCursor hasNextPage }
+  }
+}
+"""
+
+def iter_relay(client, url):
+    after = None
+    while True:
+        body = client.post(url, json={"query": QUERY, "variables": {"after": after}}).json()
+        conn = body["data"]["issues"]
+        for edge in conn["edges"]:
+            yield edge["node"]
+        info = conn["pageInfo"]
+        if not info["hasNextPage"]:   # exhausted
+            return
+        after = info["endCursor"]
+```
+
+## Dedup on overlap
+
+With offset pagination under concurrent inserts, the same row can appear on two
+pages. If exactness matters, track seen ids and skip duplicates:
+
+```python
+def dedup(records, key="id"):
+    seen = set()
+    for r in records:
+        k = r[key]
+        if k in seen:
+            continue
+        seen.add(k)
+        yield r
+```
+
+Cursor/keyset pagination does not have this problem for stable sort keys — another
+reason to prefer it.
+
+## Combine with retries + rate limits
+
+Each `client.get(...)` above should go through the retry + rate-limit wrapper from
+`SKILL.md` (transient-only retry with jittered backoff, `Retry-After` honored).
+Pagination is the loop; the per-request call inside it is where resilience lives.

package/skills/api-connector-builder/scripts/verify.sh

@@ -0,0 +1,172 @@
+#!/usr/bin/env bash
+#
+# verify.sh — connector-module structure/banlist linter for `api-connector-builder`.
+#
+# WHAT IT DOES (read-only; never edits a file)
+#   Lints the connector source the skill produces against the four-pillar shape:
+#   secrets, retries, pagination, timeouts. It checks the artifact's STRUCTURE,
+#   not its runtime behavior — appropriate for a connector emitted into an
+#   arbitrary target repo. It never false-fails: a repo with no connector-like
+#   source is simply skipped.
+#
+#   A connector file = a .py / .ts / .js / .mjs / .tsx file that looks like an
+#   HTTP client (mentions a base URL, fetch/httpx/requests/undici/axios, or an
+#   Authorization/Bearer header). Other files are ignored.
+#
+#   Checks per connector file:
+#     1. FAIL  hardcoded secret  — an inline API key / bearer literal / long
+#              token-looking string assigned in source (not read from env).
+#     2. FAIL  no retry wired    — no tenacity import, no backoff loop, and no
+#              undici/axios retry interceptor anywhere in the file.
+#     3. FAIL  no pagination loop — uses pagination-style params (cursor/offset/
+#              page/after/Link) but has no loop (while/for/async generator) to
+#              walk them: a lone "get first page" that ignores the next cursor.
+#     4. FAIL  no request timeout — issues HTTP calls but sets no timeout /
+#              AbortSignal.timeout on them.
+#     5. FAIL  token in localStorage  — long-lived token stored in localStorage.
+#     6. WARN  token logging      — a log/console call that emits the token,
+#              Authorization header, or Bearer value.
+#
+# HOW TO RUN (inside YOUR project, not the skills repo)
+#   ./verify.sh                 # scan ./ for connector source
+#   ./verify.sh --path src      # scan a subdirectory
+#   ./verify.sh --strict        # treat any warning as a failure (exit 1)
+#
+# EXIT CODES
+#   0  clean, or warnings only without --strict (also: nothing to check)
+#   1  a structural failure, or --strict with a warning
+#   2  bad usage
+#
+# Runs on stock macOS bash 3.2 — no mapfile, no associative arrays.
+
+set -euo pipefail
+
+if [ -t 1 ]; then
+  RED=$'\033[31m'; GREEN=$'\033[32m'; YELLOW=$'\033[33m'; NC=$'\033[0m'
+else
+  RED=''; GREEN=''; YELLOW=''; NC=''
+fi
+
+ok_count=0; skip_count=0; warn_count=0; fail_count=0
+ok()   { printf '%s[ ok ]%s %s\n' "$GREEN"  "$NC" "$*"; ok_count=$((ok_count + 1)); }
+skip() { printf '%s[skip]%s %s\n' "$YELLOW" "$NC" "$*"; skip_count=$((skip_count + 1)); }
+warn() { printf '%s[warn]%s %s\n' "$YELLOW" "$NC" "$*"; warn_count=$((warn_count + 1)); }
+fail() { printf '%s[fail]%s %s\n' "$RED"    "$NC" "$*"; fail_count=$((fail_count + 1)); }
+
+usage() { sed -n '2,40p' "$0" | sed 's/^# \{0,1\}//'; }
+
+SCAN_PATH="."
+STRICT=0
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --path)    SCAN_PATH="${2:?--path needs a value}"; shift 2 ;;
+    --strict)  STRICT=1; shift ;;
+    -h|--help) usage; exit 0 ;;
+    *) printf '%sUnknown argument: %s%s\n\n' "$RED" "$1" "$NC"; usage; exit 2 ;;
+  esac
+done
+
+if [ ! -e "$SCAN_PATH" ]; then
+  printf '%sPath not found: %s%s\n' "$RED" "$SCAN_PATH" "$NC"; exit 2
+fi
+
+TMPDIR_V="$(mktemp -d 2>/dev/null || printf '/tmp/apiconn-verify.%s' "$$")"
+mkdir -p "$TMPDIR_V" 2>/dev/null || true
+cleanup() { rm -rf "$TMPDIR_V" 2>/dev/null || true; }
+trap cleanup EXIT
+
+ALL="$TMPDIR_V/all"
+FILES="$TMPDIR_V/files"
+
+# Candidate source files (skip node_modules / vendored / build dirs).
+find "$SCAN_PATH" -type f \
+  \( -name '*.py' -o -name '*.ts' -o -name '*.tsx' -o -name '*.js' -o -name '*.mjs' \) \
+  2>/dev/null \
+  | grep -Ev '/(node_modules|\.git|dist|build|\.venv|venv|__pycache__)/' \
+  > "$ALL" || true
+
+# Keep only files that look like an HTTP client (a connector).
+: > "$FILES"
+while IFS= read -r f; do
+  [ -z "$f" ] && continue
+  if grep -Eiq 'https?://|\bfetch\(|\bhttpx\b|\brequests\.|\bundici\b|\baxios\b|Authorization|Bearer ' "$f" 2>/dev/null; then
+    printf '%s\n' "$f" >> "$FILES"
+  fi
+done < "$ALL"
+
+if [ ! -s "$FILES" ]; then
+  skip "no connector-like source (.py/.ts/.js with an HTTP client) under: $SCAN_PATH"
+  printf '\nok=%d skip=%d warn=%d fail=%d\n' "$ok_count" "$skip_count" "$warn_count" "$fail_count"
+  exit 0
+fi
+
+# --- per-file checks ---------------------------------------------------------
+while IFS= read -r f; do
+  [ -z "$f" ] && continue
+  file_ok=1
+
+  # 1. Hardcoded secret: an inline literal assigned to a key/token/secret-looking
+  #    name, OR a Bearer/sk- literal embedded in source. Reading from env is fine.
+  if grep -Eni \
+      '(api[_-]?key|secret|token|bearer|password|client[_-]?secret)[[:space:]]*[:=][[:space:]]*["'\''][A-Za-z0-9_\-]{16,}["'\'']' \
+      "$f" 2>/dev/null | grep -Eiv 'process\.env|os\.environ|getenv|import\.meta\.env|<[^>]*>|YOUR_|EXAMPLE|xxxx|\.\.\.' >/dev/null; then
+    fail "hardcoded secret literal: $f"
+    file_ok=0
+  fi
+  if grep -Eni '["'\''](sk_live_|sk_test_|ghp_|xox[baprs]-|AKIA)[A-Za-z0-9_\-]{8,}' "$f" 2>/dev/null >/dev/null; then
+    fail "hardcoded provider token literal: $f"
+    file_ok=0
+  fi
+
+  # 2. Retry mechanism wired somewhere in the file.
+  if grep -Eiq 'tenacity|@retry|wait_exponential|backoff|retry_if|maxRetries|max_retries|interceptors\.|retry[_-]?interceptor|exponential' "$f" 2>/dev/null; then
+    : # has a retry primitive
+  elif grep -Eiq 'for[[:space:]].*attempt|while[[:space:]].*attempt|range\([[:space:]]*[0-9]|attempt[[:space:]]*[+<]' "$f" 2>/dev/null \
+       && grep -Eiq 'sleep|setTimeout|delay|backoff' "$f" 2>/dev/null; then
+    : # has a hand-rolled retry loop with a delay
+  else
+    fail "no retry mechanism wired (no tenacity/backoff/interceptor or retry loop): $f"
+    file_ok=0
+  fi
+
+  # 3. Pagination loop, only required when the file uses pagination params.
+  if grep -Eiq 'cursor|next[_-]?cursor|endCursor|hasNextPage|pageInfo|offset|\bpage\b|\bafter\b|rel="next"|Link' "$f" 2>/dev/null; then
+    if grep -Eiq 'while[[:space:]]|for[[:space:]]|yield|async[[:space:]]*function\*|def[[:space:]]+iter|->[[:space:]]*Generator|AsyncIterator' "$f" 2>/dev/null; then
+      : # walks the pages
+    else
+      fail "pagination params used but no loop to walk them (first-page-only): $f"
+      file_ok=0
+    fi
+  fi
+
+  # 4. Request timeout set on the HTTP calls.
+  if grep -Eiq 'timeout|AbortSignal\.timeout|AbortController|signal[[:space:]]*[:=]|connect_timeout|read_timeout' "$f" 2>/dev/null; then
+    : # a timeout is configured
+  else
+    fail "no request timeout set (a hung socket will stall the run): $f"
+    file_ok=0
+  fi
+
+  # 5. Token in localStorage (long-lived secret in an XSS-readable store).
+  if grep -Eiq 'localStorage\.(setItem|getItem)?[[:space:]]*\(?[^)]*\b(token|bearer|access[_-]?token|refresh[_-]?token|api[_-]?key)\b' "$f" 2>/dev/null \
+     || grep -Eiq 'localStorage[^;]*\b(token|access_token|refresh_token|apiKey)\b' "$f" 2>/dev/null; then
+    fail "token stored in localStorage (XSS-readable): $f"
+    file_ok=0
+  fi
+
+  # 6. WARN: logging the token / Authorization header.
+  if grep -Eni '(console\.(log|info|debug|warn|error)|logg?(er)?\.|print|logging\.)[^;\n]*\b(token|bearer|authorization)\b' "$f" 2>/dev/null \
+     | grep -Eiv 'x-request-id|status|attempt|request[_-]?id|//|#' >/dev/null; then
+    warn "possible token/Authorization logging: $f"
+  fi
+
+  if [ "$file_ok" -eq 1 ]; then
+    ok "connector shape ok: $f"
+  fi
+done < "$FILES"
+
+printf '\nok=%d skip=%d warn=%d fail=%d\n' "$ok_count" "$skip_count" "$warn_count" "$fail_count"
+
+if [ "$fail_count" -gt 0 ]; then exit 1; fi
+if [ "$STRICT" -eq 1 ] && [ "$warn_count" -gt 0 ]; then exit 1; fi
+exit 0

package/skills/api-design/SKILL.md

@@ -0,0 +1,189 @@
+---
+name: api-design
+description: "Use when designing the contract of a network API before/independent of implementation — modeling resources and URLs, choosing REST vs GraphQL, picking a versioning strategy, defining one consistent error envelope, and settling pagination/filtering/idempotency conventions. Triggers: 'design the REST API for X', 'what should the endpoints be', 'how do I version this without breaking clients', 'should this be REST or GraphQL', 'cursor vs offset pagination', 'standard error format for my API', 'RFC 9457 problem details', 'idempotency key on POST', '200 with error body', 'diseña la API REST de esto', 'cómo verziono la API sin romper clientes'. NOT implementing endpoints in a framework (that is fastapi/nestjs/go/nodejs), NOT security/auth hardening (that is secure-coding), NOT receiving inbound webhooks (that is webhooks), NOT building an outbound client to a third-party API (that is api-connector-builder)."
+tags: [api-design, rest, graphql, openapi, versioning, pagination, http, rfc9457, contract-design]
+recommends: [fastapi, nestjs, go, nodejs, secure-coding, webhooks, api-connector-builder, code-review]
+origin: risco
+---
+
+# API design
+
+## Your one job
+
+You design the **contract** an API exposes. You do not write the handler. The deliverable is a set of decisions a backend skill can implement directly: resource shapes, URLs, methods, the status-code map, one error envelope, pagination params, versioning rules — ideally captured as an **OpenAPI 3.1** document.
+
+When the user names a framework (FastAPI, NestJS, Go, Node), they own the build; you are pulled in for contract questions. Settle the contract first, then hand off (see [Handoff](#handoff)). Keep every decision framework-neutral: nothing here should mention an ORM, a router, or a DI container.
+
+## REST vs GraphQL vs hybrid
+
+Pick on traffic shape, not fashion. Decide once, write it down.
+
+| Situation | Choose | Why |
+|---|---|---|
+| CRUD-ish resources, public API, HTTP caching matters | **REST** | URLs map to resources; CDN/proxy caching works on GET + ETag out of the box |
+| Many client shapes, deep nested graphs, mobile over-fetch is real | **GraphQL** | one round-trip, client picks fields; no N endpoints per screen |
+| Stable resource API + one rich read surface for a client app | **Hybrid** | REST for the system of record, a GraphQL read layer on top |
+
+Operational gotcha that decides monitoring: **GraphQL returns HTTP 200 even when a field errored** — failures live in an `errors[]` array next to partial `data`. Your dashboards cannot alert on 5xx; you must alert on the `errors[]` payload. REST signals failure with the HTTP status itself. If your ops team lives on status-code SLOs, that is a point for REST. Details in `references/graphql-design.md`.
+
+## Resource & URL modeling
+
+Resources are **nouns**; HTTP methods are the verbs. Never put a verb in a path.
+
+Rules, each with its reason:
+- **Plural collections, consistent everywhere** — `/projects`, `/projects/{id}`. Pick plural and never mix singular in; inconsistent naming is the most-cited design smell.
+- **Nest sub-resources one level** — `/projects/{id}/tasks`. Deeper than one level (`/projects/{p}/tasks/{t}/comments/{c}`) gets unreadable; link to the flat resource instead (`/comments/{c}`).
+- **Methods carry intent** — `GET` read, `POST` create, `PUT` full replace, `PATCH` partial update, `DELETE` remove. A path never says what it does.
+- **Filter/sort/select via query string, not new paths** — `?status=open&sort=-created_at&fields=id,title`. One `GET /projects` handles all of it; don't mint `/projects/open` and `/projects/byDate`.
+
+| Bad | Good | Why |
+|---|---|---|
+| `POST /createProject` | `POST /projects` | the method is the verb |
+| `GET /getUserOrders/{id}` | `GET /users/{id}/orders` | noun hierarchy, no verb |
+| `GET /project` and `GET /tasks` | `GET /projects` and `GET /tasks` | one plural convention |
+| `GET /projects/active` | `GET /projects?status=active` | filter is a query param |
+| `POST /projects/{id}/delete` | `DELETE /projects/{id}` | method, not path segment |
+
+Full query grammar (filter operators, sparse fieldsets, sort syntax) is in `references/rest-conventions.md`.
+
+## Status codes that matter
+
+You need a small map, used consistently. Don't overload 200.
+
+```http
+200 OK            # read / update succeeded, body returned
+201 Created       # resource created — include Location: /projects/{id}
+202 Accepted      # async accepted, not done — return a status URL
+204 No Content    # success, nothing to return (e.g. DELETE)
+400 Bad Request   # malformed syntax / unparseable
+401 Unauthorized  # not authenticated — who are you?
+403 Forbidden     # authenticated but not allowed — I know you, no
+404 Not Found     # resource absent (or hidden from this caller)
+409 Conflict      # state collision — duplicate, version mismatch
+422 Unprocessable # syntactically fine, semantically invalid (validation)
+429 Too Many Req  # rate limited — include Retry-After
+5xx               # your fault, never the client's; never leak the stack
+```
+
+Two distinctions agents get wrong:
+- **401 vs 403** — 401 means *unauthenticated* (no/invalid credentials); 403 means *authenticated but unauthorized*. Returning 401 on a permission failure leaks that re-auth might help when it won't.
+- **409 vs 422** — 409 is a *state* conflict (the request fights the current server state: dup key, stale version). 422 is a *content* problem (the body parses but fails business rules). Full table with when-each in `references/rest-conventions.md`.
+
+## Error envelope: RFC 9457
+
+One error shape across **every** endpoint. Adopt **RFC 9457 Problem Details** (the current standard; it obsoletes RFC 7807). Media type `application/problem+json`. Standard members: `type`, `title`, `status`, `detail`, `instance`, plus your own extension members.
+
+```json
+{
+  "type": "https://api.acme.com/problems/validation-error",
+  "title": "Your request parameters didn't validate.",
+  "status": 422,
+  "detail": "due_date must be in the future.",
+  "instance": "/projects/8a3/tasks",
+  "errors": [
+    { "field": "due_date", "message": "must be in the future" }
+  ],
+  "correlation_id": "req_01H..."
+}
+```
+
+Rules:
+- **`type` is a stable, machine-readable URI** — clients branch on it, not on `detail`. Never change a `type` string once published.
+- **`title` is human, generic per type; `detail` is human, specific to this occurrence.** `detail` is for people, not parsers.
+- **Always carry a correlation/request id** (extension member) so a support ticket maps to a log line.
+- **Never leak internals** — no stack traces, SQL, internal hostnames, or raw DB ids in `detail`. That is both an information leak and a coupling leak.
+
+## Pagination
+
+Default to **cursor (keyset)** pagination. Use offset only for small, bounded sets.
+
+| Approach | Use when | Why |
+|---|---|---|
+| **Cursor / keyset** | large or changing datasets, feeds, anything hot | opaque token over an indexed ordered column → constant-time, stable across inserts |
+| **Offset / limit** | small bounded admin lists, fixed reference tables | simple, but the DB scans-and-discards skipped rows (degrades with depth) and **skips or duplicates rows** when data shifts between page loads |
+
+Decision line: if the list can grow unbounded or rows can be inserted between page fetches, use cursor.
+
+REST cursor envelope — same keys on every list endpoint:
+
+```json
+{
+  "data": [ { "id": "...", "title": "..." } ],
+  "next_cursor": "eyJpZCI6MTI4N30",
+  "has_more": true
+}
+```
+
+The next page is `GET /projects?cursor=eyJpZCI6MTI4N30&limit=50`. The cursor is opaque — clients must not parse or construct it.
+
+GraphQL has its own de-facto standard: **Relay Connections** — `edges { node, cursor }`, `pageInfo { hasNextPage, endCursor }`, args `first` / `after`. Use it; don't invent a bespoke GraphQL pagination shape. See `references/graphql-design.md`.
+
+## Versioning & evolution
+
+**Prefer additive, non-breaking evolution over a new version.** A new version forks your client base and your maintenance. Most changes don't need one.
+
+- **Non-breaking (no version bump):** adding an optional field, adding a new endpoint, adding a new optional query param, adding a new enum value clients are told to tolerate.
+- **Breaking (needs a version):** removing/renaming a field, changing a type, making an optional field required, changing status-code semantics, changing the error `type` for a case.
+
+When you must version, **use a URL path version (`/v1/...`) for public APIs** — it is visible, cacheable, trivially testable in a browser, and the most common convention clients expect. Header/media-type versioning (`Accept: application/vnd.acme.v2+json`) keeps URLs clean but is harder to test and cache; query-param versioning (`?version=2`) pollutes every URL. Default to path.
+
+Deprecate gracefully with the `Deprecation` and `Sunset` response headers so clients get programmatic warning before removal:
+
+```http
+Deprecation: true
+Sunset: Sat, 31 Oct 2026 23:59:59 GMT
+Link: <https://api.acme.com/v2/projects>; rel="successor-version"
+```
+
+Full breaking-vs-non-breaking matrix and the deprecation workflow live in `references/versioning-and-evolution.md`.
+
+## Idempotency & concurrency
+
+- **Make POST/PATCH retry-safe with an `Idempotency-Key` header.** The client sends a unique key; the server replays the original response on a retry instead of double-creating. This is an IETF httpapi draft (not yet an RFC) but is the proven pattern across Stripe, PayPal, and others — adopt it for any create/charge/payment-like operation where a network retry could duplicate work.
+
+```http
+POST /payments
+Idempotency-Key: 9b1f7c2e-... 
+```
+
+- **Use `ETag` + `If-Match` for optimistic concurrency** on PUT/PATCH. The server returns an `ETag` (a version fingerprint) on read; the client sends it back in `If-Match` on write. If it no longer matches, the server returns **412 Precondition Failed** — no lost update. Use `If-None-Match` for conditional GET caching.
+
+## Anti-patterns
+
+| Anti-pattern | Why it bites | Do instead |
+|---|---|---|
+| Verbs in paths (`/getUsers`, `/createProject`) | duplicates HTTP semantics, breaks caching/tooling | noun + HTTP method |
+| Mixed plural/singular collections | clients can't predict URLs | one plural convention everywhere |
+| 200 on error (REST) | breaks status-code monitoring and client error handling | real 4xx/5xx + RFC 9457 body |
+| Different error shape per endpoint | every client writes per-endpoint parsing | one `application/problem+json` shape |
+| Leaking stack traces / SQL / DB ids in errors | info leak + couples clients to internals | generic `title`, safe `detail`, correlation id |
+| Offset pagination on a hot/large feed | slow at depth; skips/dups rows on insert | cursor/keyset pagination |
+| Unbounded list endpoint (no limit) | one client can pull the whole table | enforce a default + max `limit` |
+| New version for every change | forks clients, multiplies maintenance | additive non-breaking evolution |
+| Breaking a field in place on a live version | silently breaks existing clients | new field/version + deprecation headers |
+| 401 for a permission failure | misleads client into re-authing | 403 when authenticated-but-forbidden |
+| 200 for a created resource | hides the create, no `Location` | 201 + `Location` header |
+| Ignoring GraphQL partial `errors[]` | failures invisible to monitoring | alert on `errors[]`, not just HTTP 5xx |
+
+## Handoff
+
+The contract is the artifact. Emit it as an **OpenAPI 3.1** document (see `references/openapi-contract.md`) — that is the checkable deliverable a framework skill generates code from.
+
+Hand off to the builder:
+- Python/async → [`../fastapi/SKILL.md`](../fastapi/SKILL.md)
+- NestJS / Node DI → [`../nestjs/SKILL.md`](../nestjs/SKILL.md)
+- Go `net/http` → [`../go/SKILL.md`](../go/SKILL.md)
+- Node generally → [`../nodejs/SKILL.md`](../nodejs/SKILL.md)
+
+Adjacent concerns you do **not** own:
+- Auth hardening, OWASP, CORS/CSP threat-modeling → [`../secure-coding/SKILL.md`](../secure-coding/SKILL.md) (you only place 401/403/scopes in the contract)
+- Receiving inbound webhooks (HMAC verify, replay, dedupe) → [`../webhooks/SKILL.md`](../webhooks/SKILL.md)
+- Building an outbound client to a third-party API → [`../api-connector-builder/SKILL.md`](../api-connector-builder/SKILL.md)
+- Reviewing handler code (not the design) → [`../code-review/SKILL.md`](../code-review/SKILL.md)
+
+## References
+
+- `references/rest-conventions.md` — full status-code table, filter/sort/sparse-fieldset grammar, content negotiation, rate-limit headers, HATEOAS note.
+- `references/versioning-and-evolution.md` — breaking-vs-non-breaking matrix, three versioning mechanisms, deprecation/sunset workflow.
+- `references/graphql-design.md` — schema/nullability design, Relay Connections, mutation + error-union conventions, the HTTP-200 error model and its monitoring impact.
+- `references/openapi-contract.md` — capture the contract as OpenAPI 3.1 so frameworks generate from it; what `scripts/verify.sh` checks.

package/skills/api-design/evals/README.md

@@ -0,0 +1,3 @@
+# Evals: api-design
+
+These cases are run by the repository's eval harness against the skill router. `should_trigger` asserts that for each prompt the router selects `api-design`; `should_not_trigger` asserts the named sibling wins instead (each `route_to` is a real catalog id); `capability` is a rubric-graded generation check — the model is asked the scenario and its output is scored against the `must_include` list. Run them with the repo's eval runner pointed at `cases.yaml`; no network or live API is needed.

package/skills/api-design/evals/cases.yaml

@@ -0,0 +1,45 @@
+skill: api-design
+
+should_trigger:
+  - prompt: "Design the REST API for a multi-tenant invoicing service"
+    why: core greenfield contract-design request; resource modeling + URLs.
+  - prompt: "How do I add a field and a new status value to this endpoint without breaking existing clients?"
+    why: evolution/versioning; non-obvious — no words 'API' or 'design', it's the additive-non-breaking rule.
+  - prompt: "Should this be REST or GraphQL, and how should pagination work?"
+    why: paradigm choice plus pagination convention — both are design-time decisions.
+  - prompt: "What's the standard error format? I keep returning a different shape per endpoint"
+    why: symptom-led; routes to the single RFC 9457 problem-details envelope.
+  - prompt: "Our list endpoint times out at page 5000 with offset pagination"
+    why: non-obvious symptom — the fix is a cursor/keyset pagination design, not a query tweak.
+  - prompt: "diseña los endpoints y el versionado de nuestra API pública"
+    why: Spanish trigger for endpoint design + versioning strategy.
+  - prompt: "We need an Idempotency-Key on POST so retries don't double-charge — how should the contract handle it?"
+    why: non-obvious header-level contract decision (idempotency), design-time not implementation.
+
+should_not_trigger:
+  - prompt: "Implement these endpoints in FastAPI with Pydantic models and async routes"
+    route_to: fastapi
+    why: build-time framework implementation, not contract design.
+  - prompt: "Threat-model this endpoint and check the CORS and CSP config for OWASP issues"
+    route_to: secure-coding
+    why: security/hardening lens, not the API shape.
+  - prompt: "Verify the incoming Stripe webhook signature and dedupe replayed events"
+    route_to: webhooks
+    why: receiving inbound events with HMAC verification, not designing an exposed API.
+  - prompt: "Write a client that calls the OpenWeather API and handles its rate limits and retries"
+    route_to: api-connector-builder
+    why: building an outbound client to a third-party API, not designing one.
+  - prompt: "Wire a custom provider with useFactory in my NestJS module"
+    route_to: nestjs
+    why: framework dependency-injection wiring, not contract design.
+
+capability:
+  - scenario: "Design the public REST API contract for a 'projects' resource with nested tasks, supporting pagination, consistent errors, and a versioning plan."
+    must_include:
+      - plural noun collections and nested path `/projects/{id}/tasks` with no verbs in paths
+      - correct methods + status codes, including 201 + Location on create and the 409-vs-422 distinction
+      - one RFC 9457 `application/problem+json` error envelope used across all endpoints, with a stable machine `type` and a correlation id, no leaked internals
+      - cursor (keyset) pagination with a consistent response envelope (data + next_cursor/has_more)
+      - URL-path versioning for the public API plus the additive-non-breaking evolution rule (and Deprecation/Sunset on removal)
+      - a handoff note pointing to a framework skill (fastapi/nestjs/go/nodejs) to implement it
+      - bonus: an OpenAPI 3.1 sketch of the contract

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

@@ -0,0 +1,70 @@
+# GraphQL design
+
+When you chose GraphQL (many client shapes, deep graphs, over-fetch is real), design the schema as the contract. Framework-neutral.
+
+## Schema & nullability
+
+- **Model the domain graph, not your tables.** Types are nouns with relationships; let clients traverse instead of you minting endpoints.
+- **Nullability is a contract.** A non-null field (`String!`) means the resolver must always produce it — and if it errors, GraphQL nulls the *nearest nullable parent*, which can blank a whole subtree. Make a field non-null only when it truly cannot be absent; default to nullable for anything fetched from a flaky downstream.
+- **Use enums for closed sets** and add values additively (clients should tolerate unknown enum values).
+- **Evolve additively; deprecate with `@deprecated(reason: ...)`** instead of removing — GraphQL has no URL version to fall back on.
+
+## Pagination: Relay Connections
+
+Use the de-facto standard rather than a bespoke shape, so client tooling (Apollo/Relay) works out of the box.
+
+```graphql
+type ProjectConnection {
+  edges: [ProjectEdge!]!
+  pageInfo: PageInfo!
+}
+
+type ProjectEdge {
+  node: Project!
+  cursor: String!
+}
+
+type PageInfo {
+  hasNextPage: Boolean!
+  endCursor: String
+}
+
+type Query {
+  projects(first: Int!, after: String): ProjectConnection!
+}
+```
+
+- `first` + `after` paginate forward; `last` + `before` backward.
+- `cursor` is opaque — clients pass `endCursor` back as `after`; they never construct it.
+
+## Mutations & error model
+
+- **One input object per mutation, one payload type out** — keeps mutations evolvable: `createProject(input: CreateProjectInput!): CreateProjectPayload!`.
+- **Model expected, business-level failures as data, not as protocol errors.** A union or a payload with `userErrors { field, message }` lets clients handle validation without parsing the transport `errors[]`.
+
+```graphql
+type CreateProjectPayload {
+  project: Project
+  userErrors: [UserError!]!
+}
+```
+
+## The HTTP-200 error model (the big operational difference)
+
+GraphQL returns **HTTP 200 even when a field errored.** Failures appear in a top-level `errors[]` array alongside partial `data`:
+
+```json
+{
+  "data": { "project": null },
+  "errors": [
+    { "message": "Project not found", "path": ["project"], "extensions": { "code": "NOT_FOUND" } }
+  ]
+}
+```
+
+Consequences you must design for:
+- **Monitoring cannot rely on HTTP 5xx.** Alerting must inspect the `errors[]` payload and `extensions.code`, not the status line. Wire this before launch or outages go invisible.
+- **Clients must check `errors[]` on every response**, even a 200. Treating 200 as success silently swallows failures.
+- **Standardize `extensions.code`** (e.g. `NOT_FOUND`, `FORBIDDEN`, `VALIDATION`) so clients and dashboards branch on a stable machine value — the GraphQL analogue of an RFC 9457 `type`.
+
+This single difference, not the query syntax, is what makes GraphQL operationally distinct from REST. Decide it explicitly.