ada-agent 0.1.0

package/skills/dpi-scaling/SKILL.md

@@ -0,0 +1,23 @@
+---
+name: dpi-scaling
+description: Fix retina/HiDPI blur and layout — devicePixelRatio mismatch between canvas backing store and CSS size
+category: graphics
+---
+
+# DPI Scaling
+
+Reach for this when a canvas, chart, or rendered surface looks blurry or soft on retina/HiDPI displays but sharp on standard ones.
+
+1. Confirm the symptom is DPR-related: read `window.devicePixelRatio`. If it's >1 and the canvas looks fuzzy, the backing store is smaller than the displayed pixels and the browser is upscaling.
+2. Inspect the two sizes that must differ: CSS size (`canvas.style.width`/`getBoundingClientRect().width`, in CSS px) and backing-store size (`canvas.width`, in device px). The blur appears when `canvas.width === cssWidth` on a DPR-2 screen.
+3. Fix the pattern: set `canvas.width = Math.round(cssWidth * dpr)` and `canvas.height = Math.round(cssHeight * dpr)`, keep `canvas.style.width/height` in CSS px, then `ctx.scale(dpr, dpr)` (2D) or `gl.viewport(0,0, canvas.width, canvas.height)` (WebGL) so your draw code stays in CSS units.
+4. Re-run on a DPR change: listen for `matchMedia('(resolution: ...)')` or just recompute on `resize`; dragging a window between monitors changes DPR live.
+5. Verify text/lines are crisp: a 1px line should hit a single device row — half-pixel offsets cause residual softness, so align strokes to `0.5` in 2D contexts after scaling.
+6. Avoid double-scaling: don't both `ctx.scale(dpr)` and multiply coordinates by dpr — pick one (scale the context, draw in CSS px).
+
+## Rules
+- Backing store (`canvas.width`) must be CSS size times `devicePixelRatio`; the style width stays in CSS px.
+- `ctx.scale(dpr,dpr)` once after sizing lets all draw code stay in logical units — don't also scale coordinates.
+- Recompute on resize and on monitor change; `devicePixelRatio` is not constant.
+- For WebGL, scale via `gl.viewport` and the drawing-buffer size, not by `ctx.scale`.
+- Cap DPR (e.g. min(dpr,2)) for fill-rate-heavy scenes to avoid rendering 9x pixels on a 3x phone.

package/skills/e2e-test/SKILL.md

@@ -0,0 +1,23 @@
+---
+name: e2e-test
+description: Write an end-to-end test that drives the real app through a user flow with Playwright or Cypress
+category: testing
+---
+
+# E2E Test
+
+Use when you need to verify a complete user journey through the running app, not isolated units.
+
+1. Identify the user-facing flow and its success criteria (what the user does, what they should see/get at the end).
+2. Set up the test against a real or test-seeded environment; ensure known starting state (logged-out, empty cart, etc.).
+3. Drive the flow by user-visible interactions — click buttons, fill fields, follow links — as a real user would.
+4. Locate elements by accessible role, label, or test id rather than brittle CSS/XPath tied to styling.
+5. Assert on observable outcomes (visible text, URL, network result), using the framework's auto-waiting instead of fixed sleeps.
+6. Run it headless and headed, confirm it passes repeatably, and wire it into CI.
+
+## Rules
+- Test critical paths end-to-end (signup, checkout, core action); keep E2E count small since they are slow and costly.
+- Select elements by role/label/`data-testid`, never by auto-generated class names or deep DOM position.
+- Rely on built-in waiting for conditions; never paper over timing with `sleep`/fixed `waitForTimeout`.
+- Seed and reset state per test so runs are independent and repeatable; don't depend on leftover data.
+- Keep secrets and base URLs in env/config, not hardcoded, so the test runs across local/CI/staging.

package/skills/embeddings/SKILL.md

@@ -0,0 +1,23 @@
+---
+name: embeddings
+description: Set up embeddings and a vector store for semantic search or retrieval
+category: data-ml
+---
+
+# Embeddings
+
+Use when you need semantic search, clustering, dedup, or retrieval and must turn text (or other data) into vectors stored in an index.
+
+1. Pick an embedding model matched to the domain and language; note its dimensionality, max input length, and cost.
+2. Preprocess and chunk inputs to fit the model's token limit, keeping a stable id and metadata for each item.
+3. Batch the embedding calls, handle rate limits/retries, and normalize vectors if your similarity metric expects it (cosine).
+4. Store vectors in a vector store (FAISS, pgvector, or a managed index) with the chosen distance metric and an ANN index sized to your recall/latency target.
+5. Query by embedding the query the same way, retrieving top-k, and verifying results make semantic sense on real queries.
+6. Persist the model name and version with the index so you can detect and handle re-embedding needs.
+
+## Rules
+- Embed queries and documents with the exact same model and preprocessing — mismatches silently wreck recall.
+- Match the index's distance metric to the model (most use cosine/dot on normalized vectors); don't mix metrics.
+- Re-embedding is required when you change the model, dimension, or chunking — version the index accordingly.
+- Store source ids and metadata alongside vectors so retrieved hits can be traced back and filtered.
+- Benchmark recall and latency at your real data size; small-sample behavior doesn't predict ANN tradeoffs.

package/skills/empty-states/SKILL.md

@@ -0,0 +1,23 @@
+---
+name: empty-states
+description: Design empty, loading, and error states that orient the user and offer a clear next action.
+category: ui-design
+---
+
+# Empty States
+
+Reach for this whenever a view can have no data, be loading, or fail — these states are most of the real experience and deserve the same care as the happy path.
+
+1. Distinguish the three cases and design each: first-run empty (no data yet), cleared empty (filters/search returned nothing), and error (something broke) — they need different copy and actions.
+2. For first-run, make it a launchpad: a short encouraging line, a focused illustration or icon, and one primary CTA that creates the first item — turn the void into onboarding.
+3. For "no results", explain why and give an out: echo the active query/filters and offer "clear filters" or a broader suggestion, not a generic shrug.
+4. For errors, be specific and recoverable: plain-language cause, a "Try again" action, and a path to support — never expose a raw stack trace or a bare "Something went wrong".
+5. Match the layout to the eventual content so the page doesn't jump when data arrives, and keep tone consistent with the product's voice (helpful, not cute-at-the-user's-expense).
+6. Respect hierarchy and restraint: one illustration, one heading, one action; muted supporting text; accessible contrast and a real `role`/announcement for error states.
+
+## Rules
+- Every empty/error state offers at least one obvious next step — a dead end with no action is a bug.
+- Error copy names what happened and what to do; "Oops!" with no recovery path is failure theater.
+- Don't reuse the first-run empty state for "no search results" — they imply different user situations.
+- Keep illustrations subtle and on-brand; they support the message, they aren't the message.
+- Announce errors to assistive tech (`aria-live="assertive"` / `role="alert"`) and keep focus recoverable.

package/skills/env-setup/SKILL.md

@@ -0,0 +1,23 @@
+---
+name: env-setup
+description: Add a .env.example and validate required config at startup so missing vars fail fast
+category: ci-cd
+---
+
+# Env Setup
+
+Use when config is read from environment variables and you want a discoverable template plus a hard fail on missing/invalid values.
+
+1. Grep the codebase for every environment variable read (`process.env.X`, `os.environ[...]`, `getenv`) to build the full list.
+2. Create `.env.example` listing each var with a safe placeholder or sane default and a one-line comment on its purpose.
+3. Centralize config loading in one module that reads, type-coerces, and validates all vars at startup.
+4. Validate on boot with a schema (zod, pydantic, envalid, or a manual check) and exit non-zero with a clear message naming any missing/invalid var.
+5. Ensure real `.env` is gitignored and document the `cp .env.example .env` bootstrap step.
+6. Run the app with a deliberately missing var to confirm it fails fast with an actionable error rather than crashing later.
+
+## Rules
+- Keep `.env.example` in sync with the code — a var read but undocumented is a setup trap.
+- Never commit a real `.env` or real secret values; placeholders only in the example.
+- Validate at startup, not lazily at first use, so misconfig surfaces immediately.
+- Fail with a message that names the offending variable and what it expects.
+- Read each var through the central config module, not scattered `process.env` access.

package/skills/erc20/SKILL.md

@@ -0,0 +1,24 @@
+---
+name: erc20
+description: Implement a standards-compliant ERC-20 token using OpenZeppelin with tests
+category: web3
+---
+
+# ERC-20 Token
+
+Reach for this to ship a fungible token. Extend OpenZeppelin's audited base rather than implementing the standard by hand.
+
+1. Inherit `ERC20` from OpenZeppelin and set name/symbol in the constructor; decimals default to 18 unless you override for a reason.
+2. Decide supply policy: fixed (mint all in constructor) or mintable (`ERC20` + `Ownable`/`AccessControl` gating `mint`); add `ERC20Burnable` only if burning is intended.
+3. Add only the extensions you need — `ERC20Permit` (EIP-2612 gasless approvals), `ERC20Pausable`, `ERC20Capped` — and avoid feature creep.
+4. Wire access control: restrict `mint`/`pause` to roles, never leave them public.
+5. Write tests covering transfer, `approve`/`transferFrom`, allowance edge cases, zero-address reverts, and supply invariants.
+6. Deploy with a script that records the token address, then verify the source on the block explorer (Etherscan/Sourcify).
+
+## Rules
+- Do not reimplement transfer/allowance logic — inherit it; custom logic reintroduces known bugs.
+- Be aware of the `approve` race; prefer `ERC20Permit` or increase/decrease-allowance patterns.
+- Never override `decimals()` casually — wallets and integrators assume the value you publish.
+- Gate `mint` and `pause`; an open mint function is an instant exploit.
+- Don't add transfer fees/rebasing without warning — they break DEXes and many integrators.
+- Account for decimals in every amount; mixing raw and human units is a common bug.

package/skills/error-tracking/SKILL.md

@@ -0,0 +1,23 @@
+---
+name: error-tracking
+description: Wire up Sentry/error reporting with context, releases, and source maps
+category: observability
+---
+
+# Error Tracking
+
+Use this when uncaught exceptions and crashes need to be captured, grouped, and triaged with enough context to fix them.
+
+1. Add the SDK (Sentry or equivalent) and initialize it as early as possible in startup with the DSN from an env var and the `environment` set.
+2. Set `release` to the build SHA/version and upload source maps (or debug symbols) in CI so stack traces de-minify to real source lines.
+3. Let the SDK install global handlers for uncaught exceptions and unhandled rejections; add framework middleware so request errors are captured automatically.
+4. Enrich events with context — user (non-PII id), tags (`route`, `tenant`), and breadcrumbs — and scrub sensitive fields with `beforeSend`.
+5. Tune sampling: capture 100% of errors but sample performance/traces; set rate limits so a storm doesn't blow your quota.
+6. Trigger a test error post-deploy, confirm it lands grouped with a readable stack trace and correct release, then wire alerts/ownership for new issues.
+
+## Rules
+- Scrub PII and secrets in `beforeSend` — request bodies, headers, tokens, emails.
+- Always set `release` + upload source maps, or stack traces are useless.
+- Don't capture expected/handled control-flow errors (validation, 404s) — filter them to cut noise.
+- Link error events to `trace_id` so you can pivot to traces and logs.
+- Fail open: SDK init or transport errors must never crash the app.

package/skills/estimate/SKILL.md

@@ -0,0 +1,23 @@
+---
+name: estimate
+description: Break a task into estimated subtasks with assumptions, dependencies, and a total range
+category: productivity
+---
+
+# Estimate
+
+Reach for this when someone asks "how long will this take?" — turn a vague task into a decomposed, defensible estimate with the uncertainty made explicit instead of a single hopeful number.
+
+1. Clarify the scope and the definition of done; note anything ambiguous as an explicit assumption you are estimating against.
+2. Decompose the task into subtasks small enough that each is obvious in size (roughly a half-day or less); split anything you can't size.
+3. For each subtask give a three-point estimate — optimistic / likely / pessimistic — and a one-line reason for the spread.
+4. Mark dependencies and ordering between subtasks, plus any external blockers (reviews, access, third-party APIs).
+5. Add explicit line items for testing, code review, and integration — the work that estimates usually forget.
+6. Total the likely column for a point estimate and the optimistic-to-pessimistic span for a range; flag the riskiest 1-2 subtasks driving the spread.
+
+## Rules
+- Never give a single bare number — always a range, and always with the assumptions it rests on.
+- Estimate effort, not calendar time; do not bake in meetings, context-switching, or someone's availability.
+- If a subtask's pessimistic case is more than ~3x its optimistic, it's underspecified — split it or spike it first.
+- Don't pad silently; if you add buffer, label it as buffer so it can be challenged.
+- Re-estimate when scope or assumptions change rather than defending a stale number.

package/skills/etl-pipeline/SKILL.md

@@ -0,0 +1,24 @@
+---
+name: etl-pipeline
+description: Build an ETL/data pipeline that extracts, transforms, and loads data idempotently
+category: data-ml
+---
+
+# ETL Pipeline
+
+Reach for this when moving data between systems (files, APIs, databases, warehouses) on a schedule or one-shot, and you need it to be re-runnable without duplicating or corrupting data.
+
+1. Pin down source and sink contracts: schema, primary keys, volume, update frequency, and whether the source is append-only or mutable.
+2. Split the job into explicit extract, transform, and load stages so each can be tested and re-run in isolation.
+3. Make loads idempotent: upsert on a natural/surrogate key, or stage-then-swap, so a re-run never double-writes.
+4. Process incrementally using a watermark (updated_at, sequence id, or partition) and persist the high-water mark after a successful load.
+5. Validate row counts and key invariants between stages; fail loud and stop before loading bad data downstream.
+6. Add structured logging and a dead-letter path for bad records, then wire retries with backoff on transient failures.
+7. Make the run parameterized (date range, env) and schedulable via cron/Airflow/Prefect rather than hardcoded.
+
+## Rules
+- Never mutate the source; treat raw extracts as immutable and transform into a separate layer.
+- Idempotency is non-negotiable — assume every run can be retried or run twice.
+- Keep transforms pure and deterministic; isolate I/O so logic is unit-testable without the network.
+- Checkpoint the watermark only after the load commits, never before.
+- Surface partial failures explicitly; a green exit code must mean the data is actually correct.

package/skills/eval-harness/SKILL.md

@@ -0,0 +1,23 @@
+---
+name: eval-harness
+description: Build a reproducible evaluation harness for a model or agent
+category: data-ml
+---
+
+# Eval Harness
+
+Use when you need to measure how well a model, prompt, or agent performs against a fixed dataset, and compare versions over time without moving goalposts.
+
+1. Define the task as inputs plus a scoring function; pick metrics that actually reflect the goal (accuracy, F1, pass@k, exact match, rubric score).
+2. Build a versioned dataset of cases with expected outputs or grading criteria; keep a small dev set and a frozen test set.
+3. Make each case independent and the runner deterministic where possible — fix seeds and temperature, record model/version.
+4. Run cases in parallel with isolation, capturing the raw output, score, latency, and cost per case.
+5. Aggregate into a scorecard (overall and per-category) and persist results keyed by model/prompt version for diffing.
+6. Inspect failures by reading actual transcripts, not just the aggregate; add hard cases back into the dataset.
+
+## Rules
+- Freeze the eval set; changing cases and the system in the same run makes results uncomparable.
+- Save raw outputs alongside scores so any regression can be inspected after the fact.
+- For LLM-as-judge graders, validate the judge against human labels and pin the judge model/prompt.
+- Report cost and latency next to quality — a better score that's 10x slower is a real tradeoff.
+- Always look at concrete failing cases; aggregate metrics hide systematic errors.

package/skills/exif-orientation/SKILL.md

@@ -0,0 +1,23 @@
+---
+name: exif-orientation
+description: Fix images that appear rotated or flipped because EXIF orientation metadata was ignored or double-applied
+category: image
+---
+
+# EXIF Orientation
+
+Reach for this when photos (often phone camera uploads) show up sideways or upside-down in your app but look correct in the OS file viewer — or vice versa.
+
+1. Reproduce with the actual offending file (orientation bugs are per-file); confirm it looks correct in a viewer that honors EXIF and wrong in your pipeline, or the reverse.
+2. Read the EXIF Orientation tag (values 1–8). Values other than 1 mean the stored pixels are rotated/mirrored and metadata says how to display them. `exiftool`, `identify -verbose`, or `PIL.Image.getexif()` will show it.
+3. Decide the symptom class: if your app ignores the tag, the image stays in stored (sideways) orientation. If two layers BOTH apply it (e.g. browser auto-rotates AND your code rotates), it gets double-rotated.
+4. Normalize once, early: bake the orientation into the pixels (e.g. `ImageOps.exif_transpose`) immediately after decode, then STRIP the orientation tag so nothing downstream re-applies it.
+5. Verify across the consumers: thumbnail generator, the viewer/browser, and any re-encode step must all agree — test a sideways and a mirrored sample (orientation 6 and 2 are good probes).
+6. Check the encode path too: when you write the corrected image, ensure you don't copy the old orientation tag back into the output.
+
+## Rules
+- Apply EXIF orientation exactly once, then remove the tag — double-application is the most common regression.
+- Browsers and image CDNs may auto-rotate; account for whether the consumer already honors EXIF before you also rotate.
+- Cropping/face-detection/coordinate work must happen AFTER orientation is baked in, or boxes land on the wrong region.
+- Test orientation 6 (rotate 90 CW) and 2/4 (mirrored) specifically — plain 180 hides flip vs rotate confusion.
+- Don't trust width/height from headers before normalization; a sideways image reports swapped dimensions.

package/skills/explain-code/SKILL.md

@@ -0,0 +1,23 @@
+---
+name: explain-code
+description: Explain an unfamiliar region of the codebase by reading it in context and summarizing intent and risks
+category: code-understanding
+---
+
+# Explain Code
+
+Reach for this when asked "what does this do?" about a file, function, or block you have not read yet. The goal is an accurate plain-language account, not a line-by-line restatement.
+
+1. Read the whole unit (function/class/file), not just the lines pointed at — context above and below changes meaning.
+2. Identify inputs, outputs, and side effects: what comes in, what goes out, what state or I/O it touches.
+3. Resolve unfamiliar symbols by grepping their definition rather than guessing from the name.
+4. Note the control flow: branches, loops, early returns, error/exception paths, and what triggers each.
+5. State the purpose in one or two sentences, then explain the non-obvious parts (edge cases, why it exists, surprising behavior).
+6. Flag anything risky or unclear: dead code, TODOs, implicit assumptions, or behavior that contradicts the names.
+
+## Rules
+- Explain intent and behavior, not syntax — assume the reader knows the language.
+- Quote exact identifiers and file paths so the reader can navigate; never paraphrase a function name.
+- If behavior depends on a caller or config you have not seen, say so instead of inventing it.
+- Distinguish what the code does from what it appears intended to do when they diverge.
+- Keep it proportional: a short helper gets a sentence, not a page.

package/skills/express-middleware/SKILL.md

@@ -0,0 +1,23 @@
+---
+name: express-middleware
+description: Add Express middleware for auth, logging, or error handling in the right order
+category: frameworks
+---
+
+# Express Middleware
+
+Use to add cross-cutting behavior (authentication, request logging, error handling) to an Express app via middleware, registered in the correct order.
+
+1. Decide the type: request middleware `(req, res, next)` for logging/auth, or error middleware `(err, req, res, next)` (four args) for errors.
+2. Write it in its own module; do work, attach to `req` (e.g. `req.user`), then call `next()` — or `next(err)` to fail.
+3. Register globally with `app.use(fn)` or per-route with `router.get(path, mw, handler)`; order matters — earlier `use` runs first.
+4. For auth, validate the token/session, reject with `401`/`403` (don't call `next()`), or set `req.user` and continue.
+5. Mount error-handling middleware last, after all routes, so thrown/`next(err)` errors funnel into one place.
+6. Run the server and verify: logs appear, protected routes reject without creds, and errors return clean JSON not stack traces.
+
+## Rules
+- Always call `next()` (or send a response) — forgetting it hangs the request.
+- Error middleware MUST have four parameters or Express treats it as normal middleware.
+- Register body parsers and loggers before routes; register the error handler after them.
+- In async middleware, wrap or `try/catch` and pass errors to `next(err)` — thrown async errors aren't auto-caught (pre-Express 5).
+- Don't leak internals: log the full error server-side, return a sanitized message/status to the client.

package/skills/extract-function/SKILL.md

@@ -0,0 +1,23 @@
+---
+name: extract-function
+description: Pull a cohesive block of code into a well-named function or method
+category: refactoring
+---
+
+# Extract Function
+
+Use when a function is too long, a block needs a comment to explain it, or the same logic is about to be reused. A good extraction names the "what" so the caller reads like prose.
+
+1. Identify the exact block to extract and confirm it is cohesive (one job, clear boundary).
+2. Determine inputs (variables read) and outputs (variables written/returned after the block).
+3. Create the new function with those inputs as parameters and the outputs as return value(s).
+4. Replace the original block with a call; pass arguments and assign results back.
+5. Name the function for its intent, not its mechanics (`computeTax`, not `doStep2`).
+6. Run tests; the behavior and outputs must be identical.
+
+## Rules
+- If the block writes more than one or two outer variables, return a small object/tuple instead of using side effects.
+- Keep the new function pure when feasible — pass dependencies in rather than reaching for globals.
+- Don't over-parameterize; if a value is constant at the call site, inline it.
+- Place the new function at a sensible scope (same module/class) before reaching for shared utils.
+- Preserve early returns and error paths exactly; extracting can silently swallow a `return`.

package/skills/faq/SKILL.md

@@ -0,0 +1,24 @@
+---
+name: faq
+description: Build and maintain an FAQ from real, recurring questions — answer-first, searchable, and kept current.
+category: docs
+---
+
+# FAQ
+
+Use when the same questions keep landing in support, issues, or chat — an FAQ deflects them, but only if it's sourced from real questions, not invented ones.
+
+1. Mine sources: support tickets, issue tracker, chat threads, PR comments. Collect the actual wording people use.
+2. Cluster duplicates and rank by frequency × pain; write the top items first, drop the long tail.
+3. Phrase each question the way a user would search it ("Why is my build slow?"), not in internal jargon.
+4. Answer-first: lead with the direct answer in 1-2 sentences, then optional detail and a link to the full doc.
+5. Group into sections (Setup, Billing, Errors…) and add anchor links so answers are shareable.
+6. Add a "last reviewed" date and a feedback path ("still stuck? open an issue").
+7. Revisit quarterly: promote new recurring questions, delete ones that no longer apply, fix answers that drifted.
+
+## Rules
+- Source from real questions only — a guessed FAQ answers nothing anyone asked.
+- One question per entry, in the user's words, not the team's.
+- Lead with the answer; don't make readers scroll through context to find it.
+- Link to canonical docs instead of duplicating them — duplicated answers rot out of sync.
+- Prune ruthlessly; a bloated FAQ is as useless as none.

package/skills/fastapi-endpoint/SKILL.md

@@ -0,0 +1,23 @@
+---
+name: fastapi-endpoint
+description: Add a FastAPI endpoint with Pydantic request/response models and DI
+category: frameworks
+---
+
+# FastAPI Endpoint
+
+Use to add a typed FastAPI route with Pydantic schemas for validation and serialization, plus dependency injection where needed.
+
+1. Define Pydantic models for the request body and response (`response_model=`); use separate input/output schemas to avoid leaking fields.
+2. Add the path operation on a `router`/`app` with the right verb decorator (`@router.post("/items")`) and type-annotated params.
+3. Declare params by source: path (`item_id: int`), query (defaults), body (Pydantic model) — FastAPI infers from the annotation.
+4. Inject shared resources (DB session, current user) via `Depends(...)`; raise `HTTPException` for error cases.
+5. Set `status_code=` and `response_model=` explicitly; keep the handler thin and delegate logic to functions/services.
+6. Run `uvicorn app:app --reload`, check `/docs`, and exercise the endpoint to confirm validation and shape.
+
+## Rules
+- Use distinct input vs output Pydantic models; never return ORM objects without a `response_model` to filter fields.
+- Type every parameter — FastAPI's validation and docs derive entirely from annotations.
+- Use `Depends` for DB sessions/auth instead of globals; it makes endpoints testable.
+- Raise `HTTPException(status_code, detail)` for expected errors; don't return ad-hoc error dicts.
+- For DB or external I/O, prefer `async def` with async clients, or keep blocking calls in `def` handlers (FastAPI offloads them).

package/skills/favicon/SKILL.md

@@ -0,0 +1,23 @@
+---
+name: favicon
+description: Generate a full favicon and app-icon set (SVG, PNG, Apple touch, manifest) with the correct head markup.
+category: html
+---
+
+# Favicon
+
+Use when a site needs proper tab icons, iOS home-screen icons, and PWA install icons across browsers and platforms.
+
+1. Start from a square master (SVG or 512x512+ PNG) with a simple, high-contrast mark that stays legible at 16x16.
+2. Generate the set: `favicon.svg` (scalable, preferred), `favicon.ico` (multi-size 16/32/48 for legacy), `apple-touch-icon.png` (180x180), and 192/512 PNGs for the manifest.
+3. Provide a maskable icon variant (safe-zone padded) so Android adaptive icons don't crop the mark; mark it `purpose: "maskable"` in the manifest.
+4. Add a `site.webmanifest` listing icons, `name`, `short_name`, `theme_color`, and `background_color` for PWA installs.
+5. Wire the `<head>`: `<link rel="icon" type="image/svg+xml" href="/favicon.svg">`, `<link rel="icon" href="/favicon.ico" sizes="any">`, `<link rel="apple-touch-icon" href="/apple-touch-icon.png">`, `<link rel="manifest" href="/site.webmanifest">`.
+6. Add a `<link rel="icon">` dark variant via media query if the mark needs it, then verify in a real browser tab, an iOS Add-to-Home-Screen, and an Android install prompt.
+
+## Rules
+- Provide an SVG favicon plus a fallback `.ico`; don't rely on the legacy root `/favicon.ico` auto-discovery alone.
+- Apple touch icons need an opaque background and no transparency — iOS adds its own rounded corners.
+- Maskable icons must keep the logo inside the ~80% safe zone or Android will crop it.
+- Use absolute or root-relative icon paths so they resolve on every route.
+- Bust the cache (filename hash or query) when updating an icon; browsers cache favicons aggressively.

package/skills/feature-engineering/SKILL.md

@@ -0,0 +1,23 @@
+---
+name: feature-engineering
+description: Engineer features for a model without leakage and reproducibly
+category: data-ml
+---
+
+# Feature Engineering
+
+Use when deriving model inputs from raw data — encodings, aggregates, time-window features — and you need them correct, leakage-free, and consistent between training and serving.
+
+1. Start from the prediction point: for each row, only use information available before the label is known (the "as-of" time).
+2. Derive features explicitly — encodings, ratios, datetime parts, rolling/window aggregates, and target-relative stats — one transform at a time.
+3. Fit any feature that learns from data (scalers, target/mean encoders, imputers) on the training split only, then apply to val/test.
+4. For time-windowed and aggregate features, compute them strictly from past rows to avoid look-ahead leakage.
+5. Encapsulate the transformations so the exact same code runs at training and at serving (avoid train/serve skew).
+6. Check feature distributions, null rates, and correlation with the target; drop constant, duplicate, or leaky features.
+
+## Rules
+- Leakage is the cardinal sin: never use future information or the target (directly or via fitted stats) for a row's features.
+- Fit data-dependent transforms on train only; refit per fold under cross-validation.
+- Use the same transformation code path in training and production to prevent train/serve skew.
+- Respect the as-of time for every time-based feature — joins and rolling windows must not peek ahead.
+- A feature that's suspiciously predictive is usually leakage; investigate before trusting it.

package/skills/few-shot/SKILL.md

@@ -0,0 +1,23 @@
+---
+name: few-shot
+description: Build few-shot examples that steer an LLM toward the format and behavior you want
+category: agent-llm
+---
+
+# Few-Shot Examples
+
+Use this when zero-shot prompting gives inconsistent format or quality and you want to demonstrate the target behavior by example.
+
+1. Pin down the exact target: the input shape, the output format, and the edge cases the model keeps getting wrong.
+2. Write 3-5 examples as input/output pairs that match production data — same fields, same tone, same length you actually expect.
+3. Cover variety deliberately: include a hard case, an edge case, and a "what not to do is implied" case, not five near-identical easy ones.
+4. Make every example's output perfect and consistent in format — the model copies form as much as content, including mistakes.
+5. Structure the prompt clearly: delimit examples (XML tags or labels) and separate them from the live input the model must answer.
+6. Evaluate on a held-out set; add an example only when it fixes a real failure, and remove ones that don't move accuracy.
+
+## Rules
+- Consistency beats quantity — 3 flawless, format-aligned examples outperform 10 sloppy ones.
+- Order can matter; put the most representative example last since recency biases the model.
+- Don't let examples leak the test answer or encode spurious patterns (e.g. all positive labels first).
+- More examples cost tokens on every call — prune to the minimum set that holds quality, then consider caching them.
+- If the task is purely structural, prefer a schema/structured-output constraint over spending tokens on examples.

package/skills/find-owner/SKILL.md

@@ -0,0 +1,23 @@
+---
+name: find-owner
+description: Locate where a feature or behavior lives in the codebase starting from a symptom or user-facing string
+category: code-understanding
+---
+
+# Find Owner
+
+Use when you know what the software does but not where the code is — "where is the discount applied?" or "what renders this error?" Start from observable anchors and work inward.
+
+1. Extract searchable anchors: user-facing strings, error messages, log lines, route paths, config keys, or feature-flag names.
+2. Grep for the most literal anchor first; exact strings beat guessed identifiers.
+3. From a hit, walk outward to the owning function/module and confirm it matches the behavior, not just the wording.
+4. If the string is composed or templated, search for its stable fragments or the format template instead of the full text.
+5. Cross-check with git history (`git log -S` / blame) to find when and where the behavior was introduced.
+6. Report the owning file(s) and entry function, plus adjacent code (tests, config) that confirms it is the right place.
+
+## Rules
+- Strings shown to users are the strongest anchors — prefer them over guessing function names.
+- Watch for interpolation, i18n keys, and concatenation that prevent a full-string match; fall back to fragments.
+- Confirm the candidate actually produces the behavior; a matching string can live in dead code or a comment.
+- Use `git log -S"<snippet>"` to pinpoint the introducing commit when grep alone is ambiguous.
+- If the behavior comes from a dependency or generated code, say so rather than forcing a match in app source.

package/skills/firmware-driver/SKILL.md

@@ -0,0 +1,23 @@
+---
+name: firmware-driver
+description: Write a bare-metal peripheral driver against a memory-mapped register interface
+category: gamedev
+---
+
+# Firmware Driver
+
+Reach for this when bringing up an MCU peripheral or external chip from the datasheet with no HAL to lean on.
+
+1. Read the datasheet/reference manual: find the register map, base address, bit fields, and the reset/init sequence.
+2. Define registers as `volatile` typed pointers or a packed struct at the base address; mirror field names from the manual.
+3. Write a blocking init: enable the peripheral clock, configure mode/pins, set dividers, then enable the peripheral.
+4. Implement read/write as small functions that poll status flags or use interrupts; never busy-spin without a timeout.
+5. Add a timeout and error return to every wait loop so a missing/hung device cannot lock the firmware.
+6. Bring up incrementally: verify clock and a known read-only ID register before attempting full transfers.
+
+## Rules
+- Mark every register access `volatile`; the compiler will otherwise cache or reorder hardware reads/writes.
+- Use read-modify-write for shared registers; blind writes clobber neighboring control bits.
+- Respect required ordering and delays in the init sequence — some bits must settle before the next write.
+- Guard every hardware wait loop with a timeout and surface failures; silent infinite loops are unrecoverable in the field.
+- Watch volatile aliasing and memory barriers around DMA buffers shared with the peripheral.

package/skills/fix-flaky-tests/SKILL.md

@@ -0,0 +1,23 @@
+---
+name: fix-flaky-tests
+description: Diagnose an intermittently failing test and stabilize it by removing the source of nondeterminism
+category: testing
+---
+
+# Fix Flaky Tests
+
+Use when a test passes and fails without code changes, eroding trust in the suite.
+
+1. Reproduce the flake: run the test in a loop (e.g. 50-100x) and run it both isolated and within the full suite.
+2. Capture failing output and compare it to passing runs to pinpoint what varies between them.
+3. Classify the cause: timing/async races, test-order or shared-state leakage, unmocked clock/random/network, or resource contention.
+4. Fix the root cause — await real conditions instead of sleeping, isolate or reset shared state, inject the clock/seed, stub the network.
+5. Re-run the loop (100x+) to confirm the flake is gone, not just hidden behind a longer timeout.
+6. If you cannot fix it now, quarantine it explicitly with a tracked issue rather than leaving it to randomly red the CI.
+
+## Rules
+- Never "fix" a flake by bumping a sleep or adding a blind retry — that masks the race, not removes it.
+- Replace fixed delays with polling on the actual condition (element present, value settled, job done).
+- Suspect order-dependence: run the suite shuffled and in reverse to surface state leakage between tests.
+- Pin nondeterministic inputs — freeze time, seed RNG, fix timezone/locale — rather than asserting loosely.
+- A test you quarantine must have an owner and a tracking issue; quarantine is a pause, not a fix.

package/skills/flutter-widget/SKILL.md

@@ -0,0 +1,23 @@
+---
+name: flutter-widget
+description: Build a Flutter widget that owns and updates local state
+category: mobile
+---
+
+# Flutter Widget
+
+Reach for this when you need a reusable Flutter widget that holds and mutates its own state (toggles, counters, form fields, animations) rather than a pure stateless layout.
+
+1. Decide stateless vs stateful: if nothing changes after build, use `StatelessWidget`; if the widget mutates over its lifetime, use `StatefulWidget` with a paired `State` class.
+2. Declare constructor params as `final` fields and pass a `Key? key` through to `super`; mark required params `required`.
+3. Put mutable values as fields on the `State` class and wrap every mutation in `setState(() { ... })` so the framework reschedules `build`.
+4. Implement `build(BuildContext context)` returning the widget tree; pull colors and text styles from `Theme.of(context)` instead of hardcoding.
+5. Override `initState` for one-time setup (controllers, listeners) and `dispose` to tear them down; never start work in the constructor.
+6. Run `flutter analyze` and exercise the widget with a `WidgetTester` (`pumpWidget`, `tap`, `pump`) to confirm state transitions.
+
+## Rules
+- Never call `setState` in `build`, after `dispose`, or inside `initState` — it triggers loops or "called after disposed" errors.
+- Always `dispose` of `AnimationController`, `TextEditingController`, `FocusNode`, and stream subscriptions.
+- Keep `build` pure and cheap: no I/O, no allocations you can hoist, no side effects.
+- Prefer `const` constructors and `const` child widgets to cut rebuild cost.
+- For state shared across the tree, lift it up or use a state-management package instead of widget-local `setState`.

package/skills/font-rendering/SKILL.md

@@ -0,0 +1,23 @@
+---
+name: font-rendering
+description: Debug text rendering — missing glyphs/tofu, wrong fallback font, bad kerning, blurry or clipped subpixel text
+category: graphics
+---
+
+# Font Rendering
+
+Reach for this when text shows boxes/question marks, jumps to the wrong typeface, looks blurry, or clips at the edges.
+
+1. Identify the failure mode first: "tofu" boxes (□) mean the glyph is missing from the loaded font; a different-looking-but-readable face means fallback kicked in; blur/clipping is a rasterization or metrics issue.
+2. For missing glyphs, confirm the font actually loaded and covers the codepoints: use `document.fonts.check('16px MyFont')` / `document.fonts.ready`, and verify the character's Unicode range is in the font (CJK, emoji, and rare symbols are often absent).
+3. For wrong-font fallback, check the `@font-face` URL loads (network tab, no 404/CORS), `font-family` name matches exactly, and the `font-weight`/`font-style` you request exists — requesting bold from a regular-only file triggers synthetic or fallback rendering.
+4. For FOUT/FOIT flashes, set `font-display` deliberately and preload the font; layout shift on swap is a metrics mismatch between fallback and real font — tune with `size-adjust`/`ascent-override` or a closer fallback.
+5. For canvas text, remember the font must be loaded before `fillText`; call `await document.fonts.load('16px MyFont')` first or you'll silently rasterize in the fallback face.
+6. For blur/clipping, check subpixel positioning and DPI scaling (see dpi-scaling), ensure the baseline/`textBaseline` and line-height give enough box, and that no `transform` is fractional-translating the text off the pixel grid.
+
+## Rules
+- Tofu = glyph absent from the font; pick a font with the needed Unicode coverage, don't fight the renderer.
+- Always await font load before drawing canvas text — `fillText` won't wait and falls back silently.
+- The CSS `font-family` name must match the `@font-face` `font-family` exactly, including case and spaces.
+- Requesting a weight/style the file lacks yields synthetic faux-bold/italic or fallback — ship the real weights.
+- Blurry text is usually DPI/subpixel, not the font; rule out devicePixelRatio before blaming the typeface.

package/skills/form-validation/SKILL.md

@@ -0,0 +1,23 @@
+---
+name: form-validation
+description: Add client-side and server-side form validation with a shared schema and clear error UX
+category: frontend
+---
+
+# Form Validation
+
+Use when a form accepts user input that must be validated — required fields, formats, ranges — on both the client and the server.
+
+1. Define one validation schema (e.g. Zod/Yup/Valibot) as the source of truth for field rules, and share it between client and server so they can't drift.
+2. Validate on the client for fast feedback: validate a field on blur/change and the whole form on submit; disable submit while invalid or in-flight.
+3. Show errors inline next to each field, tie them to the input via `aria-describedby`/`aria-invalid`, and move focus to the first error on failed submit.
+4. Re-validate on the server with the same schema — treat client validation as UX only and never trust the incoming payload.
+5. Return structured field-level errors from the server and map them back onto the matching inputs, plus a form-level message for non-field failures.
+6. Cover edge cases: trimming/normalizing input, duplicate submits, async checks (e.g. unique email), and preserving entered values after a failed submit.
+
+## Rules
+- Server validation is mandatory; client validation can be bypassed and is for UX only.
+- Keep one schema as the single source of truth — don't duplicate rules in two places.
+- Associate every error message with its input via ARIA so it's announced and reachable.
+- Validate format AND business rules (uniqueness, allowed values), not just "non-empty".
+- Don't block typing or wipe the user's input on error; show the problem and let them fix it.