infinity-harness 2.0.0

package/harness/skills/concurrency-async.md

@@ -0,0 +1,61 @@
+---
+name: concurrency-async
+description: Concurrency and async correctness — races, idempotency, queues, cancellation, locking
+tags: [concurrency, async, race, parallel, queue, lock, mutex, retry, idempotent, worker, thread, promise, deadlock, atomic]
+when: task involves parallel work, background jobs, shared state, or retried operations
+phases: [plan, build, verify]
+provenance: { origin: built-in }
+---
+
+# Concurrency & Async
+
+## Rules
+
+- **Name the shared state.** Before writing concurrent code, list what is
+  read/written by more than one flow. No list = you haven't designed yet.
+  Prefer eliminating sharing (message passing, ownership) over locking it.
+- **Check-then-act is a race.** `if (!exists) create()` fails under
+  concurrency every time. Push atomicity down: unique constraints +
+  upsert, atomic compare-and-swap, `INSERT ... ON CONFLICT` — let the
+  storage layer arbitrate.
+- **Everything retried must be idempotent.** Queues deliver at-least-once;
+  networks retry; users double-click. Design handlers so processing twice
+  = processing once (idempotency keys, natural dedup, upserts).
+- **Every await is a suspension point.** State can change across it —
+  re-validate assumptions after resuming; don't cache a check made before
+  an await and act on it after.
+- **Bound everything:** every queue has a max depth + backpressure
+  behavior; every parallel map has a concurrency limit; every wait has a
+  timeout. Unbounded = OOM or thundering herd, only later.
+- **Cancellation propagates.** Long operations accept a signal
+  (AbortSignal / context) and pass it to their children; on cancel, clean
+  up partial work.
+- **One lock order.** If you must hold two locks, EVERY path acquires them
+  in the same documented order — that single rule prevents most deadlocks.
+
+## Anti-patterns
+
+- **Fire-and-forget promises** — unawaited async work whose failures
+  vanish → await it, or hand it to a supervised job runner that logs +
+  retries.
+- **Sleep-based coordination** — "wait 500ms so X finishes first" →
+  synchronize on the event itself; timing assumptions break under load.
+- **Global mutable singletons as coordination** → explicit passing or a
+  real store with atomic ops.
+- **Distributed transactions by hope** — two systems updated without an
+  outbox/saga → write locally + outbox table, deliver async, reconcile.
+
+## Testing concurrency
+
+Force interleavings — don't hope: run the racy pair with a barrier so both
+start together; loop 100×; inject delays at suspension points. A race you
+can't provoke deliberately is a race you'll meet in production
+(`diagnosing-bugs.md` § non-deterministic bugs).
+
+## Checklist
+
+- [ ] Shared state enumerated; each entry owned, locked, or made atomic
+- [ ] All retried paths provably idempotent (test: run handler twice)
+- [ ] Queues/parallelism/waits all bounded with explicit numbers
+- [ ] Cancellation reaches children; partial work cleaned up
+- [ ] At least one test forces the race window

package/harness/skills/config-and-secrets.md

@@ -0,0 +1,52 @@
+---
+name: config-and-secrets
+description: Configuration discipline — env-driven config, validation at boot, secret hygiene, environments
+tags: [config, configuration, environment, env, secret, settings, deploy, dotenv, variable]
+when: task adds configuration, environment handling, or deployment settings
+phases: [build, ship]
+provenance: { origin: built-in }
+---
+
+# Configuration & Secrets
+
+## Rules
+
+- **Config comes from the environment; code ships identical everywhere.**
+  Anything that differs between dev/staging/prod (URLs, credentials,
+  flags, limits) is env config — never an `if (env === "prod")` branch
+  buried in logic.
+- **One config module, validated at boot.** Read `process.env`/equivalent
+  in exactly one place; parse, type-check, and apply defaults there; crash
+  at startup with a message naming every missing/invalid variable. A
+  missing variable discovered at 3am mid-request is a design failure.
+- **Everything has a sane dev default EXCEPT secrets.** A fresh clone runs
+  with `.env.example` copied to `.env`. Secrets have NO defaults —
+  absence must fail loudly, never fall back to a shared "dev secret".
+- **Secrets:** environment or secrets manager only. `.env` gitignored;
+  `.env.example` committed with dummy values documenting every variable.
+  Rotate on any suspicion of exposure; a secret that hit git history IS
+  exposed (rewriting history doesn't un-leak it — rotate).
+- **Name for grep:** consistent prefix (`APP_DB_URL`, `APP_REDIS_URL`).
+  Booleans parse explicitly ("true"/"1"); everything else arrives as a
+  string — convert deliberately.
+- **Feature flags are config too:** defined in the config module, defaulted
+  off, deleted after full rollout — a flag older than a quarter is debt.
+
+## Anti-patterns
+
+- **`process.env.X` scattered through the codebase** → impossible to know
+  what the app needs; centralize.
+- **Config objects passed 8 layers deep** → modules accept the 2 values
+  they need (see `codebase-design.md`), not the world.
+- **"Just for testing" hardcoded credentials** → tests read the same
+  config module, pointed at test resources.
+- **Committing the real .env "temporarily"** → it's in history forever;
+  rotate everything it contained.
+
+## Checklist
+
+- [ ] Fresh clone + `.env.example` → app boots (or fails naming exactly what's missing)
+- [ ] Single config module; grep finds no stray env reads
+- [ ] No secret has a default; all documented in .env.example
+- [ ] git history greps clean of credentials
+- [ ] Env-specific behavior expressed as config values, not env-name branches

package/harness/skills/context-hygiene.md

@@ -0,0 +1,51 @@
+---
+name: context-hygiene
+description: Externalize state before it decays — write discoveries down, re-read instead of remember
+tags: [meta, context, memory, handoff, session, notes, playbook]
+when: any long session, and always before ending one
+phases: []
+provenance: { origin: built-in, notes: frontier-playbook }
+---
+
+# Context Hygiene
+
+Your working memory decays and your session will end — possibly mid-task.
+Everything that matters must live in files, not in your head. The next
+session (you, another agent, a human) starts from what was WRITTEN.
+
+## Rules
+
+- **Externalize at the moment of discovery**, not "later":
+  - Surprise, gotcha, non-obvious behavior → `harness/lessons-decisions.md "..."`
+  - Design choice with a why → `infinity-harness decision "..."`
+  - Resolved terminology → `harness/docs/DOMAIN.md`
+  - Verified fact about an API/tool → `docs/research/` (with frontmatter)
+- **Re-read instead of remember.** Before acting on something you learned
+  a while ago (a file's shape, a config value), read it again — it may
+  have changed, and your memory of it degrades silently.
+- **Carry one slice.** Work on the current task only; when adjacent
+  problems surface, write them down (learn / feature-list backlog) and
+  return to the slice. Holding five threads drops four.
+- **Commit = checkpoint your understanding.** Commit after every validated
+  step with a message that says WHY, not just what. Uncommitted work +
+  ended session = archaeology for the next one.
+- **Before exiting — the clock-out ritual:**
+  1. Record any un-captured discoveries (`learn`) and choices (`decision`)
+  2. Commit (`git commit -am "session: <state + what's next>"`)
+  3. The harness writes `session-handoff.md` at boundaries — make sure
+     what YOU know that it doesn't is in progress notes or lessons
+
+## Anti-patterns
+
+- **"I'll remember"** — across an iteration boundary, you won't exist.
+  Write it down.
+- **Giant uncommitted diffs** spanning multiple concerns — impossible to
+  hand off, painful to bisect. Commit per validated slice.
+- **Notes in chat/scratch only** — anything not in the repo doesn't exist
+  for the next session.
+
+## Checklist (end of any session)
+
+- [ ] Lessons/decisions recorded for everything non-obvious found
+- [ ] Working tree committed with a why-message
+- [ ] A stranger could resume from handoff + progress + lessons alone

package/harness/skills/databases.md

@@ -0,0 +1,63 @@
+---
+name: databases
+description: Relational database craft — schema design, migrations, transactions, indexing, query safety
+tags: [database, db, sql, postgres, postgresql, mysql, sqlite, schema, migration, transaction, index, query, orm, persistence, storage]
+when: task touches persistent data, schemas, queries, or migrations
+phases: [plan, build, verify]
+provenance: { origin: built-in }
+---
+
+# Databases
+
+## Rules
+
+- **Schema first, code second.** Write the DDL (tables, types, constraints)
+  before the access code. Constraints in the database (`NOT NULL`, `UNIQUE`,
+  `FOREIGN KEY`, `CHECK`) beat validation in code — code has bugs; the
+  constraint never sleeps.
+- **Every schema change is a migration file** — forward-only, numbered,
+  committed, and runnable from scratch (`migrate` on an empty DB must
+  produce the current schema). Never edit an applied migration; add a new one.
+- **Transactions around invariants.** Any multi-statement change that must
+  hold together goes in one transaction. Name the invariant in a comment.
+- **Parameterized queries only.** String-built SQL is an injection —
+  no exceptions, including "internal" tooling.
+- **Index what you filter/join/sort on** — but only with evidence: add the
+  index when a real query needs it (EXPLAIN shows a scan), not
+  speculatively. Every index taxes writes.
+- **IDs:** prefer surrogate keys (bigint identity or UUIDv7); natural keys
+  get UNIQUE constraints instead.
+- **Timestamps:** store UTC (`timestamptz` in Postgres), convert at the edge.
+- **Money/decimals:** exact types (`NUMERIC`), never floats.
+
+## The N+1 rule
+
+If you query in a loop, you have an N+1. Fix with a join, an `IN` batch,
+or a dataloader — before it ships, not after the incident. Tell: page
+loads trigger a query count proportional to row count.
+
+## Migration safety (live systems)
+
+Expand → migrate → contract: add the new column/table (nullable or
+defaulted) → backfill + dual-write → switch reads → drop the old thing in
+a LATER migration once nothing references it. Never rename or drop in the
+same deploy that changes code.
+
+## Anti-patterns
+
+- **SELECT \*** in application code → name the columns; schema drift breaks
+  you silently otherwise.
+- **Soft-delete everywhere by default** → only where restore/audit is a real
+  requirement; otherwise it poisons every query with `WHERE deleted_at IS NULL`.
+- **Business logic in triggers** → invisible control flow; keep triggers to
+  bookkeeping (updated_at) if used at all.
+- **Testing against mocks of the DB** → test against a real (local/ephemeral)
+  database; SQLite-in-memory only when production is SQLite.
+
+## Checklist
+
+- [ ] Schema has constraints for every invariant you rely on
+- [ ] Migrations replay clean on an empty database
+- [ ] No string-concatenated SQL anywhere
+- [ ] Hot queries EXPLAINed; indexes justified by a real plan
+- [ ] Tests hit a real database engine matching production

package/harness/skills/diagnosing-bugs.md

@@ -0,0 +1,84 @@
+---
+name: diagnosing-bugs
+description: Feedback-loop-first debugging discipline for hard bugs and regressions
+tags: [debug, debugging, bug, error, failure, crash, flaky, slow, performance, regression, bisect]
+when: something is broken, throwing, failing intermittently, or slow
+phases: [verify, build]
+provenance: { origin: "mattpocock/skills", license: MIT, adapted: true }
+---
+
+# Diagnosing Bugs
+
+> Adapted from [mattpocock/skills](https://github.com/mattpocock/skills) (MIT © Matt Pocock).
+> Use during: VERIFY, or any time something is broken, throwing, failing, or slow.
+
+A discipline for hard bugs. Follow the phases in order; skip one only when
+you can explicitly justify it.
+
+## Phase 1 — Build a feedback loop
+
+**This is the skill.** Everything else is mechanical. You need a **tight**
+pass/fail signal that goes red on *this* bug. Without one, no amount of
+staring at code will save you. Spend disproportionate effort here.
+
+Ways to construct one, roughly in order:
+
+1. **Failing test** at whatever seam reaches the bug — unit, integration, e2e.
+2. **CLI/HTTP invocation** with a fixture input, diffing output against a known-good result.
+3. **Replay a captured trace** — save a real payload/event log, replay it through the code path in isolation.
+4. **Throwaway harness** — a minimal subset of the system (one module, mocked externals) that exercises the bug path with a single call.
+5. **Bisection harness** — if the bug appeared between two known states, automate "boot at state X, check" so `git bisect run` can do the work.
+6. **Differential loop** — run the same input through old vs new version and diff outputs.
+
+Once you have *a* loop, **tighten** it: faster (seconds, not minutes),
+sharper (assert the exact symptom, not "didn't crash"), deterministic (pin
+time, seed RNG, isolate filesystem). For flaky bugs, raise the reproduction
+rate — loop the trigger 100×, add stress, narrow timing — until it's
+debuggable.
+
+**Completion criterion:** you can name ONE command you have already run that
+is red-capable (asserts the user's exact symptom), deterministic, fast, and
+runnable unattended. If you catch yourself reading code to build a theory
+before this command exists — stop. That's the exact failure this skill
+prevents.
+
+## Phase 2 — Reproduce + minimise
+
+Run the loop. Watch it go red. Confirm it produces the failure mode that was
+*reported* — not a different failure nearby. Then shrink the repro to the
+smallest scenario that still goes red: cut inputs, callers, config, one at a
+time, re-running after each cut. Done when every remaining element is
+load-bearing.
+
+## Phase 3 — Hypothesise
+
+Generate **3–5 ranked hypotheses** before testing any. Each must be
+falsifiable: "If X is the cause, then changing Y will make the bug
+disappear." If you can't state the prediction, it's a vibe — discard it.
+Record the ranked list (in the task notes or `harness/lessons-decisions.md`).
+
+## Phase 4 — Instrument
+
+Each probe maps to one prediction. Change one variable at a time. Prefer a
+debugger/REPL breakpoint over logs; targeted logs over log-everything. Tag
+every debug log with a unique prefix (e.g. `[DEBUG-a4f2]`) so cleanup is a
+single grep. For performance bugs: measure a baseline first, then bisect —
+logs are usually the wrong tool.
+
+## Phase 5 — Fix + regression test
+
+Write the regression test **before the fix** — at a seam that exercises the
+real bug pattern. If no correct seam exists, that is itself a finding:
+record it as a lesson. Then: watch the test fail → apply the fix → watch it
+pass → re-run the Phase 1 loop against the original scenario.
+
+## Phase 6 — Cleanup + post-mortem
+
+- [ ] Original repro no longer reproduces
+- [ ] Regression test passes (or absence of seam documented)
+- [ ] All `[DEBUG-...]` instrumentation removed (grep the prefix)
+- [ ] Throwaway harnesses deleted
+- [ ] Record the confirmed hypothesis: `harness/lessons-decisions.md "bug X was caused by Y"`
+
+Then ask: what would have prevented this bug? If the answer is architectural
+(no test seam, tangled callers), record it: `infinity-harness decision "..."`.

package/harness/skills/domain-modeling.md

@@ -0,0 +1,65 @@
+---
+name: domain-modeling
+description: Pin down domain terminology — glossary discipline and decision records
+tags: [domain, glossary, terminology, naming, model, ubiquitous, language, adr, decision]
+when: defining specs, resolving fuzzy or conflicting terms, recording decisions
+phases: [define, plan]
+provenance: { origin: "mattpocock/skills", license: MIT, adapted: true }
+---
+
+# Domain Modeling
+
+> Adapted from [mattpocock/skills](https://github.com/mattpocock/skills) (MIT © Matt Pocock).
+> Use during: DEFINE (before writing the spec), and whenever terminology gets fuzzy.
+
+Actively build and sharpen the project's domain model as you design.
+The glossary lives in `harness/docs/DOMAIN.md`; decisions live in
+`harness/docs/DECISIONS.md`. Create `DOMAIN.md` the moment the first term
+is resolved — not before, and not "later".
+
+## The habits
+
+### Sharpen fuzzy language
+When a vague or overloaded term appears ("account", "job", "sync"), propose
+a precise canonical term. "You're saying 'account' — do you mean the
+Customer or the User? Those are different things." One concept, one name,
+everywhere: spec, code, tests, docs.
+
+### Challenge against the glossary
+When new text conflicts with an existing definition in `DOMAIN.md`, call it
+out immediately and resolve which meaning wins. Never let two meanings
+coexist silently.
+
+### Stress-test with concrete scenarios
+When domain relationships are being defined, invent specific scenarios that
+probe the edges. "A customer cancels half an order that already partially
+shipped — what happens to the invoice?" Force the boundaries between
+concepts to be precise.
+
+### Cross-reference with code
+When someone states how something works, check whether the code agrees. If
+the code cancels entire Orders but the spec says partial cancellation is
+possible — surface the contradiction now, not in BUILD.
+
+### Update DOMAIN.md inline
+When a term is resolved, write it down right there. Don't batch. Format:
+
+```markdown
+## Terms
+
+### Order
+A customer's confirmed request to purchase. Created at checkout; immutable
+once `shipped`. NOT the same as a Cart (pre-checkout, mutable).
+```
+
+`DOMAIN.md` is a glossary and nothing else — no implementation details, no
+scratch notes, no specs.
+
+### Record decisions sparingly
+Record a decision (`infinity-harness decision "..."`) only when all three hold:
+
+1. **Hard to reverse** — changing your mind later costs something real
+2. **Surprising without context** — a future reader would ask "why?"
+3. **A real trade-off** — genuine alternatives existed and you picked one
+
+If any is missing, skip it. Noise buries signal.

package/harness/skills/error-handling-logging.md

@@ -0,0 +1,56 @@
+---
+name: error-handling-logging
+description: Error taxonomy, fail-loud handling, structured logging that debugs itself
+tags: [error, exception, logging, log, observability, retry, crash, handling, monitoring, trace]
+when: task defines error paths, adds logging, or hardens failure behavior
+phases: [build, verify]
+provenance: { origin: built-in }
+---
+
+# Error Handling & Logging
+
+## Rules
+
+- **Two kinds of errors, two behaviors.** *Expected/operational* (bad
+  input, not-found, downstream timeout): handle at the boundary, map to
+  the API error shape, keep serving. *Unexpected/programmer* (undefined is
+  not a function, invariant broken): crash loud — log, alert, restart.
+  Catching-and-continuing a programmer error corrupts state downstream.
+- **Catch where you can act.** A catch block must do one of: recover
+  meaningfully, translate to the caller's vocabulary (wrapping the cause),
+  or add context and rethrow. `catch (e) {}` and log-and-swallow are how
+  systems lie about being healthy.
+- **Preserve the chain.** When wrapping, keep the original (`cause`), the
+  stack, and add what you know: which operation, which IDs, which inputs.
+  "Database error" tells nothing; "saving order 123: unique violation on
+  idempotency_key" tells everything.
+- **Structured logs (JSON), one event per line:** timestamp, level, event
+  name, and the IDs someone will grep for at 3am (request_id, user_id,
+  order_id). A log line you can't query is decoration.
+- **Correlate:** generate/propagate a request_id at the edge; include it
+  in every log line and error response. One incident = one grep.
+- **Levels mean things:** ERROR = a human should look (alertable);
+  WARN = degraded but coping; INFO = state changes worth an audit trail;
+  DEBUG = off in production. If ERROR fires routinely, it's WARN or a bug.
+- **Never log secrets** — tokens, passwords, full card/PII. Scrub
+  centrally at the logger, not at each call site.
+
+## Anti-patterns
+
+- **Stringly errors** (`throw "failed"`) → typed/coded errors the caller
+  can switch on; strings can't be handled, only displayed.
+- **Retry without classification** — retrying a 400 forever, or not
+  retrying a timeout → retry only transient errors, bounded + backoff
+  (see `concurrency-async.md` for idempotency).
+- **The 500-catch-all that hides the cause** → boundary handler logs the
+  full chained error with request_id, returns the safe shape.
+- **printf debugging left behind** → tagged temp logs (`[DEBUG-x]`) and a
+  cleanup grep before validate (the anti-placeholder gate will catch you).
+
+## Checklist
+
+- [ ] Every catch: recovers, translates, or rethrows with context — no swallows
+- [ ] Error responses use the API error shape; internals never leak
+- [ ] Logs structured; request_id flows edge→depths
+- [ ] ERROR level = actionable only; alert noise is a bug
+- [ ] Grep confirms: no secrets in logs, no leftover debug prints

package/harness/skills/frontend-ui.md

@@ -0,0 +1,56 @@
+---
+name: frontend-ui
+description: Frontend craft — state discipline, componentization, accessibility, loading/error states
+tags: [frontend, ui, component, react, vue, svelte, state, form, accessibility, a11y, css, browser, render]
+when: task builds or changes user interface
+phases: [plan, build]
+provenance: { origin: built-in }
+---
+
+# Frontend / UI
+
+## Rules
+
+- **State has one owner.** Every piece of state lives in exactly one place;
+  everything else derives from it. Duplicated state = guaranteed
+  desync bug. Derive, don't copy.
+- **Server state ≠ UI state.** Data fetched from an API (cacheable,
+  refetchable, shared) is a different animal from local UI state (open
+  modal, input draft). Use the ecosystem's query layer for server state;
+  keep UI state local to the component that owns it.
+- **Every async view renders three states:** loading, error (with a retry
+  affordance), and empty ("no results" is not a blank screen). Design them
+  first — they're most of what users see on bad networks.
+- **Forms:** controlled state or a form library — not DOM scraping.
+  Validate on submit + inline after first blur; disable the submit button
+  while in flight (double-submit is a data bug, not a UX nit).
+- **Accessibility is baseline, not polish:** semantic elements first
+  (`button`, `label`+input, `nav`); every interactive element keyboard
+  reachable with visible focus; images get alt; color is never the only
+  signal. If a div has onClick, it's a button — make it one.
+- **Componentize by responsibility, not by size.** A component that takes
+  12 props wants to be two. Container (data) vs presentational (markup)
+  split keeps both testable.
+- **Test behavior through the user's eyes:** render, interact (click/type),
+  assert visible outcome. Don't assert internal state or mock child
+  components — that's the implementation-coupled trap (`tdd.md`).
+
+## Anti-patterns
+
+- **useEffect as event handler** — effects synchronize with external
+  systems; user actions belong in handlers. Effect-chains that set state
+  which triggers effects = rewrite the data flow.
+- **Prop drilling 4+ levels** → lift to context/store — but only genuinely
+  shared state; context is not a junk drawer.
+- **Pixel-perfect absolute positioning** → flexbox/grid; the content WILL
+  change length and language.
+- **Swallowed promise rejections in handlers** → every await in a handler
+  has a catch that surfaces to the user.
+
+## Checklist
+
+- [ ] Loading / error / empty rendered for every async view
+- [ ] Keyboard-only walkthrough works; focus visible
+- [ ] No state duplicated across components (grep for copied fetch results)
+- [ ] Forms: double-submit blocked, validation inline, errors named
+- [ ] Interaction tests assert what the USER sees

package/harness/skills/grilling.md

@@ -0,0 +1,48 @@
+---
+name: grilling
+description: Stress-test a spec or plan with relentless one-at-a-time questions before committing
+tags: [grill, spec, requirements, questions, stress, interview, scope, clarify]
+when: before proposing the sprint contract, or when a plan feels underspecified
+phases: [define]
+provenance: { origin: "mattpocock/skills", license: MIT, adapted: true }
+---
+
+# Grilling — Stress-Test the Spec
+
+> Adapted from [mattpocock/skills](https://github.com/mattpocock/skills) (MIT © Matt Pocock).
+> Use during: DEFINE (before the sprint contract is agreed).
+
+A spec that hasn't been grilled is a guess. Before proposing the sprint
+contract, interrogate the plan until it stops changing.
+
+## With a human available (copilot mode)
+
+Interview the human relentlessly about every aspect of the spec until you
+reach shared understanding. Walk down each branch of the decision tree,
+resolving dependencies between decisions one by one.
+
+- Ask questions **one at a time** — wait for each answer before continuing.
+  Multiple questions at once are bewildering.
+- For each question, provide your **recommended answer**.
+- If a *fact* can be found by exploring the environment (filesystem, code,
+  docs), look it up rather than asking. The *decisions* are the human's —
+  put each one to them.
+- Do not propose the contract until the human confirms shared understanding.
+
+## Without a human (autopilot mode) — self-grill
+
+Ask the questions anyway, and answer each with your best recommendation.
+Write the question + answer pairs into `specs/prd.md` under
+"## Resolved Questions" so a human can audit them later. Standard probes:
+
+- Who uses this, and what do they do the moment it works?
+- What is explicitly OUT of scope this sprint?
+- What's the smallest end-to-end slice that proves the concept?
+- What breaks first under bad input / no network / concurrent use?
+- How will we KNOW it works — what command or check proves it?
+- What existing code/library already does part of this?
+- What's the most likely way this plan fails, and what's the fallback?
+
+Any question you cannot answer confidently becomes an exclusion in the
+sprint contract or a research task (`harness/skills/research.md`) — never
+a silent assumption.

package/harness/skills/http-apis.md

@@ -0,0 +1,60 @@
+---
+name: http-apis
+description: HTTP/REST API design — resources, status codes, errors, versioning, pagination, idempotency
+tags: [api, http, rest, endpoint, route, json, status, error, versioning, pagination, webhook, request, response]
+when: task designs or implements HTTP endpoints or consumes external APIs
+phases: [plan, build]
+provenance: { origin: built-in }
+---
+
+# HTTP APIs
+
+## Rules
+
+- **Resources, not verbs.** `POST /orders`, `GET /orders/:id` — the verb is
+  the method. RPC-ish actions get a sub-resource: `POST /orders/:id/cancel`.
+- **Status codes carry meaning:** 200 ok · 201 created (+ `Location`) ·
+  204 no body · 400 client sent garbage · 401 unauthenticated ·
+  403 unauthorized · 404 absent (also for "exists but not yours") ·
+  409 conflict · 422 validation · 429 throttled · 5xx = OUR bug, never the
+  client's. Don't return 200 with `{"error": ...}`.
+- **One error shape everywhere:**
+
+  ```json
+  { "error": { "code": "ORDER_NOT_CANCELLABLE", "message": "Order already shipped", "details": [] } }
+  ```
+
+  `code` is machine-stable (clients switch on it); `message` is for humans
+  and may change.
+- **Validate at the edge.** Reject unknown fields, wrong types, and
+  out-of-range values with 400/422 naming the field. Never let bad input
+  deep into the system.
+- **Mutations are idempotent or idempotency-keyed.** PUT/DELETE naturally;
+  POST that charges/creates accepts an `Idempotency-Key` header and
+  dedupes retries — networks WILL retry.
+- **Paginate every list** from day one (cursor > offset for anything that
+  grows). Return `next_cursor`; cap page size.
+- **Version in the path** (`/v1/`) and only break within a version never.
+  Additive changes (new optional fields) don't need a bump.
+- **Timeouts + retries on everything you CALL:** explicit connect/read
+  timeouts, retry only idempotent calls, exponential backoff + jitter,
+  honor `Retry-After`.
+
+## Anti-patterns
+
+- **Chatty endpoints** — client needs 5 calls to render one screen → add a
+  composed read endpoint; don't make the client an orchestrator.
+- **Tunneling through POST /doThing** with a type field → separate routes;
+  observability and auth depend on it.
+- **Leaking internals** — DB column names, stack traces, ORM errors in
+  responses → map to the error shape at the boundary.
+- **Webhooks without verification** — sign payloads (HMAC), verify
+  signature + timestamp, respond 2xx fast and process async.
+
+## Checklist
+
+- [ ] Every endpoint: documented method+path, request/response example, error codes
+- [ ] Error shape uniform; codes machine-stable
+- [ ] Lists paginated; mutations idempotent or keyed
+- [ ] Outbound calls have timeouts, bounded retries, backoff
+- [ ] Contract exercised by an integration test hitting real routes

package/harness/skills/performance.md

@@ -0,0 +1,53 @@
+---
+name: performance
+description: Performance work — measure first, fix the biggest cost, cache with invalidation, verify
+tags: [performance, slow, latency, profiling, optimize, cache, memory, benchmark, throughput, speed]
+when: something is slow, memory-hungry, or a task sets performance targets
+phases: [verify, build]
+provenance: { origin: built-in }
+---
+
+# Performance
+
+## Rules
+
+- **Measure before touching anything.** Reproduce the slowness with a
+  number (timing harness, profiler, EXPLAIN, flamegraph) and save the
+  baseline. Optimizing without a measurement is guessing — most guesses
+  about "the slow part" are wrong.
+- **Fix costs in order of size.** The profile ranks them. The top item is
+  usually I/O shaped: N+1 queries, missing index, sync call in a loop,
+  chatty API — algorithmic elegance rarely matters before those are gone.
+- **Set a target before optimizing** ("p95 < 300ms", "fits in 512MB").
+  Without a target, optimization never ends; with one, you stop on hit.
+- **Do less work first:** don't compute what nobody reads, paginate,
+  filter at the source (DB, not app), batch round-trips, stream instead of
+  buffering whole payloads.
+- **Cache only with an invalidation story.** Every cache states: key,
+  TTL/eviction, and what makes it stale. A cache without invalidation is a
+  correctness bug on a delay. Prefer short TTLs you can reason about.
+- **Verify with the same harness** that produced the baseline; keep the
+  before/after numbers in the commit message. No number = no optimization
+  happened.
+- **Concurrency ≠ speed.** Parallelizing CPU-bound work on one core, or
+  hammering a saturated DB harder, makes it slower. Know which resource is
+  the bottleneck first.
+
+## Anti-patterns
+
+- **Micro-optimizing the cold path** — shaving the loop while every call
+  does a network round-trip → profile decides, not intuition.
+- **Speculative caching layers** — Redis before there's a measured need →
+  measure, then cache the specific hot read.
+- **Load testing at 1×** — perf verified only at dev-scale → test at
+  expected load ± spike; N+1s hide at N=3.
+- **"It's the language/framework"** — usually it's your query pattern.
+  Prove the platform is the ceiling before replatforming.
+
+## Checklist
+
+- [ ] Baseline measured and saved before any change
+- [ ] Target stated; work stops when hit
+- [ ] Top profile item addressed first (linked evidence)
+- [ ] Every cache has key/TTL/invalidation written down
+- [ ] After-numbers from the same harness, in the commit