ada-agent 0.1.0

package/skills/visual-diff-ci/SKILL.md

@@ -0,0 +1,24 @@
+---
+name: visual-diff-ci
+description: Wire visual regression into CI with stable rendering, diff artifacts, and tuned tolerance thresholds
+category: visual-test
+---
+
+# Visual Diff CI
+
+Reach for this when screenshot tests pass locally but flake or fail in CI, or when you're adding visual checks to a pipeline for the first time.
+
+1. Pin the render environment: same browser/engine version, fonts, OS image, and a fixed DPR/viewport — bake it into a container so local == CI.
+2. Generate baselines INSIDE that container (or via the test runner's Docker image), never from a developer laptop, or you'll diff against the wrong font hinting.
+3. On every run, upload the three images per failing case — baseline, actual, diff — as CI artifacts so a reviewer can see the regression without rerunning.
+4. Tune two thresholds: per-pixel color tolerance (absorbs AA) and a max changed-pixel ratio (gates real changes); start strict, loosen only on proven flake.
+5. Make baseline updates an explicit, reviewable step (a labeled job or committed `--update-snapshots` PR), never an auto-overwrite on failure.
+6. Quarantine and fix flaky cases — disable animations, mock clocks/network, hide carets/scrollbars — rather than raising the threshold to hide them.
+
+## Rules
+- Local-vs-CI font/AA mismatch is the top cause of CI-only flake; containerize rendering before touching thresholds.
+- Always publish the diff image as an artifact — a red "visual test failed" with no picture is useless to reviewers.
+- Never auto-update baselines on failure; that turns the gate into a rubber stamp.
+- Loosening tolerance to silence flake hides real regressions — fix determinism instead.
+- Shard/parallelize deterministically; non-deterministic data ordering produces phantom diffs.
+- Keep baselines in-repo (or LFS) and tied to the commit, so a checkout reproduces the exact expected state.

package/skills/visual-regression/SKILL.md

@@ -0,0 +1,23 @@
+---
+name: visual-regression
+description: Baseline and pixel-diff screenshots so a UI change can't silently regress an unrelated view
+category: visual-test
+---
+
+# Visual Regression
+
+Reach for this when a code change "shouldn't touch the UI" but you need proof, or when a regression slipped through and you want a net under it.
+
+1. Establish baselines from a known-good commit: render each target state to a deterministic PNG and commit those under `__snapshots__/` (or your tool's baseline dir).
+2. Make the change, re-render the same states with identical viewport/DPR/theme, and pixel-diff each new shot against its baseline.
+3. For every diff, open the highlighted-diff image: confirm whether the delta is the *intended* change or a *collateral* regression.
+4. If intended, update the baseline deliberately (`--update-snapshots`) and review the new PNG in the diff before committing it.
+5. If unintended, fix the code and re-run until only the expected states differ.
+6. Lock in determinism (frozen time, disabled animations, mocked data, fixed fonts) so reruns are byte-stable.
+
+## Rules
+- Treat baselines as source: review every snapshot update in the PR like code; a blind `--update-all` defeats the entire net.
+- Render in the SAME environment as CI (font rendering, GPU/SwiftShader, OS) or you get diffs from anti-aliasing, not bugs — see visual-diff-ci.
+- Mock everything non-deterministic: clocks, random, network, animations, carets, scrollbars.
+- Set a small per-pixel + total-diff tolerance to absorb sub-pixel AA, but keep it tight enough to catch a 1px shift.
+- One state per snapshot — giant full-page baselines make every diff ambiguous and every update a rubber-stamp.

package/skills/vue-composition/SKILL.md

@@ -0,0 +1,23 @@
+---
+name: vue-composition
+description: Migrate a Vue Options API component to the Composition API with script setup
+category: frameworks
+---
+
+# Vue Composition
+
+Use when converting a Vue 2/3 Options API component to `<script setup>` with the Composition API, keeping reactivity and lifecycle behavior intact.
+
+1. Replace the Options block with `<script setup>`; declare `defineProps` and `defineEmits` for the component's props and events.
+2. Convert each `data()` field to `ref()` (primitives) or `reactive()` (objects); access `.value` for refs in script.
+3. Turn `computed` options into `computed(() => ...)` and `watch`/`watchEffect` for the watchers.
+4. Move `methods` to plain functions in setup; map lifecycle hooks (`mounted` → `onMounted`, `beforeUnmount` → `onBeforeUnmount`, etc.).
+5. Extract reusable logic into composables (`useXxx()` functions returning refs) instead of mixins.
+6. Run the app; verify reactivity (template updates), emitted events, and that hooks fire in order.
+
+## Rules
+- In the template, refs auto-unwrap — don't write `.value` there; in script you must.
+- Destructuring a `reactive` object breaks reactivity; use `toRefs` if you need to spread it.
+- `defineProps`/`defineEmits` are compiler macros — don't import them; they only work in `<script setup>`.
+- Replace `this.$emit` with the function returned by `defineEmits`, and `this.$refs` with template `ref()`.
+- Prefer composables over mixins; keep each composable focused on one concern and return only what's needed.

package/skills/web-component/SKILL.md

@@ -0,0 +1,23 @@
+---
+name: web-component
+description: Build a reusable custom element with Shadow DOM, attributes/properties, slots, and events using web standards.
+category: html
+---
+
+# Web Component
+
+Use when you need a framework-agnostic, encapsulated UI element (design-system widget, embeddable badge) that works in any page or framework.
+
+1. Define a class extending `HTMLElement`, register it with `customElements.define('my-thing', MyThing)`, and use a hyphenated name (required for custom elements).
+2. Attach Shadow DOM in the constructor (`this.attachShadow({mode:'open'})`) so styles and markup are encapsulated and don't leak in or out.
+3. Render markup + scoped `<style>` into the shadow root; expose insertion points with `<slot>` (and named slots) for light-DOM content.
+4. Wire reactivity: list reflected attributes in `static observedAttributes`, react in `attributeChangedCallback`, and mirror important attrs to properties (getters/setters).
+5. Manage lifecycle in `connectedCallback`/`disconnectedCallback` — add listeners on connect, remove on disconnect to avoid leaks.
+6. Communicate outward with `dispatchEvent(new CustomEvent('change',{detail,bubbles:true,composed:true}))` so events cross the shadow boundary; expose theming via CSS custom properties and `::part()`.
+
+## Rules
+- Tag names must contain a hyphen and be unique; registering the same name twice throws.
+- Don't touch the DOM in the constructor (element may not be connected) — defer to `connectedCallback`.
+- Use `composed:true` on CustomEvents that must escape the shadow root, and `bubbles:true` to propagate.
+- Expose styling hooks via CSS custom properties / `::part()`; consumers can't reach inside closed Shadow DOM otherwise.
+- Always remove event listeners and observers in `disconnectedCallback` to prevent memory leaks.

package/skills/web-fonts/SKILL.md

@@ -0,0 +1,24 @@
+---
+name: web-fonts
+description: Load and pair web fonts performantly — subset, preload, self-host, and avoid FOUT/FOIT and layout shift
+category: ui-design
+---
+
+# Web Fonts
+
+Use this when adding or fixing custom fonts so they look right *and* load fast. Fonts are often a page's heaviest render-blocking asset and a top cause of layout shift.
+
+1. Prefer variable fonts in `woff2` only — one file covers all weights, drops requests, and `woff2` is the smallest format every modern browser supports.
+2. Self-host instead of linking Google Fonts: it removes a third-party round-trip and the privacy/consent overhead, and lets you control caching and `font-display`.
+3. Subset aggressively — strip to the scripts/glyphs you use (e.g. latin + latin-ext) with `glyphhanger`/`fonttools`; a full font can shrink 70%+, cutting first paint.
+4. `preload` the one or two critical fonts (the body and primary heading face) with `<link rel="preload" as="font" type="font/woff2" crossorigin>`; don't preload every weight.
+5. Set `font-display: swap` to render text immediately in a fallback, then tune the fallback metrics with `size-adjust`, `ascent-override`, and `descent-override` (or Next/Fontsource defaults) so the swap causes near-zero CLS.
+6. Define a real fallback stack matched in metrics to the web font (`"Inter", system-ui, sans-serif`) so the pre-swap render already looks close.
+7. Measure: confirm in DevTools that fonts are `woff2`, preloaded, swapped, and that the layout-shift score stays near zero after they load.
+
+## Rules
+- `woff2` only, variable font when available; never serve `ttf`/`otf`/multiple static weights.
+- Self-host critical fonts; reserve external CDNs for non-critical or fallback cases.
+- Preload only the 1–2 above-the-fold faces — preloading everything defeats the purpose.
+- `font-display: swap` plus metric-overridden fallbacks to keep CLS ≈ 0.
+- Subset to the glyphs you actually render; ship no unused scripts.

package/skills/web3-frontend/SKILL.md

@@ -0,0 +1,25 @@
+---
+name: web3-frontend
+description: Wire a dapp frontend to contracts with wagmi/viem (or ethers) for wallet, reads, and writes
+category: web3
+---
+
+# Web3 Frontend
+
+Use when connecting a React/Next dapp to on-chain contracts. Prefer wagmi + viem for typed, hook-based access; ethers is the fallback.
+
+1. Install and configure: `wagmi`, `viem`, and a connector kit (RainbowKit/ConnectKit); define `chains`, transports (RPC URLs from env), and wrap the app in `WagmiProvider` + a React Query client.
+2. Handle connection: render a connect button, read account/chain via `useAccount`/`useChainId`, and prompt a network switch when the wrong chain is active.
+3. Load typed ABIs: import the contract ABI `as const` so viem infers argument and return types.
+4. Read state with `useReadContract`/`useReadContracts`; batch related reads and key cache invalidation on the relevant block/account.
+5. Send transactions with `useWriteContract` + `useWaitForTransactionReceipt`; surface pending → confirmed → error states in the UI.
+6. Decode reverts and events into human-readable messages; format token amounts with `formatUnits`/`parseUnits` using the token's decimals.
+7. Test against a local fork/testnet (Anvil/Hardhat) before pointing at mainnet.
+
+## Rules
+- Never hardcode private keys or seed phrases in frontend code — the wallet signs, the app never holds keys.
+- Put RPC URLs and API keys in env vars and proxy paid RPC through a backend to avoid leaking quota.
+- Always check `chainId` and the connected account before a write; guard against wrong-network sends.
+- Use `parseUnits`/`formatUnits` with correct decimals; never do token math in floats.
+- Show explicit loading/pending/error states — transactions are async and can fail or be dropped.
+- Validate addresses (`isAddress`) and handle user rejection (code 4001) gracefully.

package/skills/webgl-debug/SKILL.md

@@ -0,0 +1,23 @@
+---
+name: webgl-debug
+description: Debug WebGL/GPU rendering: blank canvas, context loss, bad buffers/attributes, silent draw-call failures
+category: graphics
+---
+
+# WebGL Debug
+
+Reach for this when a WebGL scene renders black, flickers, or draws nothing despite "no errors" — the API fails silently, so you must instrument it.
+
+1. Check the context exists and isn't lost: confirm `gl = canvas.getContext('webgl2'||'webgl')` is non-null and listen for `webglcontextlost`. A null context usually means a prior context leak or an unsupported feature.
+2. Add `gl.getError()` after every meaningful call during bring-up (or wrap with a debug proxy). Hunt the first non-`NO_ERROR`; `INVALID_OPERATION` after a draw call almost always means an unbound buffer or mismatched attribute.
+3. Verify program linkage: check `gl.getProgramParameter(prog, gl.LINK_STATUS)` and `getShaderParameter(...COMPILE_STATUS)`, and print `getProgramInfoLog`/`getShaderInfoLog` — compile errors are otherwise swallowed.
+4. Audit the draw-call preconditions: program `useProgram`'d, VAO/attributes enabled with correct stride/offset/type, uniforms set after `useProgram`, viewport set via `gl.viewport(0,0,w,h)`, and the buffer actually has data (`bufferData` length > 0).
+5. Isolate: clear to a bright color (`clearColor(1,0,1,1); clear(...)`). If you don't even see magenta, it's context/viewport/canvas sizing — not your geometry.
+6. For black geometry that's clearly drawing, suspect depth test (everything failing depth, near/far swapped), culling (`CULL_FACE` with reversed winding), or NaN in the MVP matrix collapsing all verts to one point.
+
+## Rules
+- Set uniforms and bind textures only AFTER `gl.useProgram`; before that they target the wrong/no program.
+- `gl.viewport` does not auto-update on canvas resize — set it whenever the drawing buffer size changes.
+- Always handle `webglcontextlost`/`restored`; GPU resets (tab background, driver hiccup) invalidate all buffers and textures.
+- Attribute `stride`/`offset` are in bytes; getting the type or stride wrong reads garbage with no error.
+- Use a magenta clear as the canary — it instantly separates "nothing draws" from "geometry is wrong".

package/skills/webhook/SKILL.md

@@ -0,0 +1,23 @@
+---
+name: webhook
+description: Implement a webhook receiver with signature verification and idempotency
+category: api
+---
+
+# Webhook
+
+Use when accepting inbound webhooks from a third party (Stripe, GitHub, etc.) — you must verify authenticity and process safely.
+
+1. Capture the raw request body before any JSON parsing — signature verification needs the exact bytes, not a re-serialized object.
+2. Read the signature header and shared secret, recompute the HMAC, and compare with a constant-time check; reject with 401 on mismatch.
+3. Reject stale events using the provider's timestamp (tolerance window) to block replay attacks.
+4. Deduplicate by the provider's event id so retries don't double-process — store seen ids or use a unique constraint.
+5. Acknowledge fast: return 2xx immediately and hand slow work to a queue/background job so the provider doesn't time out and retry.
+6. Test signature pass/fail, a replayed event, and a duplicate-id delivery.
+
+## Rules
+- Never trust the payload until the signature verifies; verify against the raw body, framework body-parsers often mutate it.
+- Use a constant-time comparison for signatures to avoid timing leaks; `==` on the digest is a vulnerability.
+- Make handling idempotent — providers deliver at-least-once and will retry on any non-2xx or timeout.
+- Return 2xx for accepted-but-unprocessed events; do real work async so a slow handler doesn't trigger redelivery storms.
+- Keep the secret in env/secret storage, never in code, and scope it per-provider.

package/skills/websocket/SKILL.md

@@ -0,0 +1,23 @@
+---
+name: websocket
+description: Implement a WebSocket server or client with proper handshake, heartbeats, and reconnection
+category: networking
+---
+
+# WebSocket
+
+Use for low-latency, bidirectional, long-lived connections (live feeds, chat, collaborative cursors). If the client only ever reads, prefer SSE; if it's request/response, prefer HTTP.
+
+1. Establish the connection: server upgrades the HTTP request (`Upgrade: websocket`), validating `Origin` and authenticating during the handshake (token in query/subprotocol, not after).
+2. Define a message protocol — pick JSON or binary, give every message a `type`, and version it so you can evolve the schema.
+3. Add ping/pong heartbeats on a timer; close connections that miss N pongs so dead peers and half-open NAT connections get reaped.
+4. On the client, implement reconnect with exponential backoff + jitter and resubscribe/replay state after reconnecting.
+5. Apply backpressure: bound the send queue per connection and drop or disconnect slow consumers instead of buffering unbounded.
+6. Handle clean shutdown — send a close frame with a status code, drain in-flight messages, and remove the connection from any registries.
+
+## Rules
+- Always validate `Origin` (and auth) at handshake time; an open upgrade endpoint is a CSRF/abuse vector.
+- Never trust message size — cap frame/message length and reject oversized payloads to avoid memory blowups.
+- A WebSocket is not reliable delivery: design for dropped connections, duplicate messages on reconnect, and out-of-order resends.
+- Use `wss://` in production; plain `ws://` breaks under TLS-terminating proxies and leaks tokens.
+- Don't do heavy work in the read loop — hand messages to workers so one slow handler can't stall the socket.

package/skills/write-tests/SKILL.md

@@ -0,0 +1,19 @@
+---
+name: write-tests
+description: Write and run focused tests for a change — find the runner, add cases, run, report.
+category: testing
+---
+
+# Write tests
+
+1. **Detect the setup.** Check `package.json` `scripts.test`, or look for existing `*test*` / `*spec*` files and the framework in use (vitest, jest, mocha, pytest, `go test`, …). Match the project's existing style exactly.
+2. **Pick what to cover.** The change's happy path plus the edge cases that would actually break it: empty input, boundaries, error paths. Don't test trivial getters or framework code.
+3. **Write the tests** next to their siblings, following local conventions for naming, imports, and assertions.
+4. **Run them** with the project's command (`npm test`, `pytest -q`, `go test ./...`, …).
+5. **Report** pass/fail with the real output. If a test fails, decide whether the test or the code is wrong — never weaken a test just to make it pass.
+
+## Rules
+
+- Cover the logic that would break, not every line. Minimal and meaningful.
+- Don't add a new test framework unless the project has none and the user wants one.
+- A test that can't fail is worthless — make sure each one would catch a real regression.