ada-agent 0.1.0

package/skills/tailwind-theme/SKILL.md

@@ -0,0 +1,24 @@
+---
+name: tailwind-theme
+description: Set up Tailwind with a custom token-driven theme so utilities map to your design system, not defaults
+category: ui-design
+---
+
+# Tailwind Theme
+
+Use this when a Tailwind project still looks like stock Tailwind — default grays, `blue-500`, `shadow-md` everywhere. The fix is wiring Tailwind to your tokens so utility classes carry your brand.
+
+1. Define your palette/space/type/radius as CSS custom properties on `:root` (and a dark override), then point Tailwind at them. In v4, do this in CSS via `@theme { --color-accent: …; --radius-lg: …; }`.
+2. Map semantic names into the theme: `bg-surface`, `text-muted`, `border-subtle`, `bg-accent` — so markup reads by role and a re-theme is a token edit, not a find-replace across components.
+3. Replace, don't extend-and-ignore, the defaults you won't use: prune the stock gray ramp and arbitrary blues so nobody reaches for `text-gray-500` and bypasses your system.
+4. Set a real type scale and `fontFamily` from your fonts; configure `--leading-*` and `--tracking-*` so `text-2xl` etc. carry intentional line-height, not Tailwind's generic defaults.
+5. Build repeated patterns as components (React/Astro/Svelte) or `@apply` recipes for true primitives (`.btn`), not by copy-pasting 14 utility classes per button.
+6. Lean on Tailwind's modern features intentionally: container queries (`@container`), `data-*`/`aria-*` variants for state, and the `dark:` variant driven by your `[data-theme]` strategy.
+7. Add `prettier-plugin-tailwindcss` for canonical class order and an ESLint rule to flag arbitrary values (`w-[13px]`) that signal an off-system value.
+
+## Rules
+- Utilities must resolve to your tokens; if `bg-accent` doesn't exist, the theme isn't wired up.
+- Prune unused default colors so the stock palette can't be used by accident.
+- Extract a component or `@apply` recipe once a class string repeats; don't shotgun utilities.
+- Arbitrary values (`p-[13px]`, `text-[#3a3a3a]`) are escape hatches — flag and minimize them.
+- Drive `dark:` from the same token strategy as the rest of the system, not a separate color set.

package/skills/tcp-server/SKILL.md

@@ -0,0 +1,23 @@
+---
+name: tcp-server
+description: Write a TCP or UDP server with correct framing, concurrency, timeouts, and graceful shutdown
+category: networking
+---
+
+# TCP / UDP Server
+
+Reach for this when implementing a custom wire protocol or a low-level network service below HTTP. Choose TCP for ordered, reliable streams; UDP for low-latency, loss-tolerant datagrams.
+
+1. Bind and listen, then accept connections in a loop, handing each to its own handler (goroutine/thread/async task) so one slow client can't block others.
+2. Define framing for TCP — length-prefix or a delimiter — because TCP is a byte stream with no message boundaries; never assume one read equals one message.
+3. Read in a loop into a buffer until you have a full frame; handle partial reads, coalesced messages, and split messages across reads.
+4. Set read/write/idle deadlines per connection so dead or stalled peers get closed instead of leaking.
+5. For UDP, handle each datagram independently — no connection state, expect loss/reordering/duplication, and validate every packet's size and contents.
+6. Implement graceful shutdown: stop accepting, signal handlers to drain, close listeners, and wait (with a timeout) for in-flight connections.
+
+## Rules
+- TCP has no message boundaries — always frame explicitly; relying on read sizes is the classic bug.
+- Cap per-message and total per-connection buffer sizes; an attacker sending a huge length prefix can OOM you.
+- Always set socket deadlines; without them a half-open connection (peer vanished) hangs a handler forever.
+- Limit concurrent connections (a semaphore/accept limiter) so the server degrades instead of falling over under load.
+- For UDP, never trust the source address blindly — it's trivially spoofed; don't use it alone for auth or amplification-prone replies.

package/skills/tdd/SKILL.md

@@ -0,0 +1,23 @@
+---
+name: tdd
+description: Drive a feature with a red-green-refactor loop, writing the failing test before any implementation
+category: testing
+---
+
+# TDD
+
+Reach for this when building a new feature or behavior and you want tests to define the contract before code exists.
+
+1. Pick the smallest next behavior and write one test that asserts it; do not write implementation yet.
+2. Run the test and confirm it fails for the expected reason (assertion, not a typo or import error) — this is RED.
+3. Write the minimum code to make that test pass; resist adding anything the test doesn't demand.
+4. Run the full test file and confirm GREEN; if other tests broke, fix them before moving on.
+5. Refactor names, duplication, and structure with tests green as a safety net; re-run after each change.
+6. Commit the green increment, then loop back to the next behavior.
+
+## Rules
+- One behavior per cycle; never write a second test while the first is red.
+- A test that passes on its first run is suspect — make it fail first to prove it tests something.
+- Keep implementation minimal; "fake it till you make it" (hardcode, then generalize) is valid early.
+- Refactor only on green, never while red, and never mix a refactor with new behavior in one commit.
+- If a test is hard to write, treat it as a design smell and reconsider the interface before forcing it.

package/skills/terraform-module/SKILL.md

@@ -0,0 +1,24 @@
+---
+name: terraform-module
+description: Write a reusable Terraform module with clean inputs, outputs, and pinned providers
+category: cloud
+---
+
+# Terraform Module
+
+Reach for this when you need to package infrastructure (a VPC, a bucket, an ECS service) so it can be called repeatedly with different inputs instead of copy-pasted HCL.
+
+1. Lay out the standard files: `main.tf`, `variables.tf`, `outputs.tf`, `versions.tf`, and `README.md` in the module directory.
+2. Pin Terraform and provider versions in `versions.tf` with `required_version` and `required_providers` (use `~>` constraints, not floating).
+3. Declare every input in `variables.tf` with `type`, `description`, and a sensible `default` only where optional; add `validation` blocks for constrained values.
+4. Build resources in `main.tf` using only variables and locals — never hardcode account IDs, regions, names, or CIDRs.
+5. Expose the IDs/ARNs/endpoints callers will need in `outputs.tf`, each with a `description`.
+6. Run `terraform fmt -recursive`, `terraform validate`, and `terraform-docs markdown table . > README.md` before committing.
+7. Add an `examples/` subdir with a minimal working invocation that `init`/`plan` cleanly.
+
+## Rules
+- A module must not configure `provider` blocks or backends — that belongs to the root caller.
+- Name resources `this` (or by role) and rely on the module name for namespacing; avoid baking the module name into every resource.
+- Mark secrets `sensitive = true` and never write them to `outputs` in plaintext.
+- Don't use `count`/`for_each` on whole modules to fake conditional creation if a `create` bool + per-resource `count` is clearer.
+- Keep provider and state concerns out; a module should be importable into any backend.

package/skills/test-coverage/SKILL.md

@@ -0,0 +1,23 @@
+---
+name: test-coverage
+description: Find untested code paths in a module and add focused tests that exercise the real risk
+category: testing
+---
+
+# Test Coverage
+
+Use when a module is under-tested and you need to raise meaningful coverage, not just the percentage.
+
+1. Run the suite with coverage reporting enabled and read the per-file line/branch numbers for the target module.
+2. Open the coverage report and locate uncovered lines, especially error handling, early returns, and conditional branches.
+3. Rank gaps by risk: prioritize logic that can fail in production over trivial getters or generated code.
+4. Write a test for each high-risk path, naming it after the behavior it pins (not "test_function_2").
+5. Cover the negative and edge cases — empty inputs, nulls, boundary values, thrown exceptions — not just the happy path.
+6. Re-run coverage to confirm the lines are hit, then sanity-check that each new test actually asserts something.
+
+## Rules
+- Chase uncovered branches and behaviors, not a coverage number; 100% line coverage with weak asserts is worthless.
+- Do not add tests that only call code without asserting on results or side effects.
+- Skip testing third-party libraries and trivial pass-throughs; focus on your own logic.
+- A surprising uncovered path often signals dead code — confirm it is reachable before testing it.
+- Keep each test isolated; do not rely on order or shared mutable state to hit a path.

package/skills/texture-debug/SKILL.md

@@ -0,0 +1,23 @@
+---
+name: texture-debug
+description: Debug texture loading, UV mapping, mipmaps, wrapping and seams — black, blurry, repeated, or flipped textures
+category: graphics
+---
+
+# Texture Debug
+
+Reach for this when a textured surface shows black, solid color, blur, visible seams, repeats, or upside-down/mirrored image.
+
+1. Confirm the image actually loaded before upload: textures uploaded from an unloaded `<img>`/fetch are blank. Log dimensions and bind from the `onload`/awaited decode, not synchronously.
+2. Swap in a known-good debug texture (a 2x2 checker or magenta/green stripes generated in code). If the checker maps correctly, the bug is your asset or its load; if it's also wrong, the bug is UVs/sampling.
+3. For black or solid-color textures in WebGL/GL, check the NPOT (non-power-of-two) rule: NPOT textures require `CLAMP_TO_EDGE` wrapping and `LINEAR`/`NEAREST` (no mipmap) min filter, or they sample black. Either pad to POT or set those params.
+4. For blur/shimmer at distance or on minification, you likely have no mipmaps: call `generateMipmap` after upload and use a `*_MIPMAP_*` min filter. For oversharp/aliased edges at angles, enable anisotropic filtering if available.
+5. For repeating or stretched-edge artifacts, audit wrap mode: `REPEAT` tiles, `CLAMP_TO_EDGE` smears the border, `MIRRORED_REPEAT` flips. Pick to match intent and check UVs aren't outside [0,1] unintentionally.
+6. For flipped/mirrored images, check the Y convention (`UNPACK_FLIP_Y_WEBGL` or a flipped UV.y) and that your atlas/UV offsets use top-left vs bottom-left origin consistently.
+
+## Rules
+- Never bind a texture before its source image has finished decoding — upload in the load callback.
+- NPOT textures + `REPEAT` or mipmap filtering = black sample; clamp + non-mip filter, or resize to POT.
+- `generateMipmap` must run after the base level is uploaded and again on any base-level change.
+- Set min and mag filters explicitly; defaults vary and the mipmap default needs mipmaps to exist.
+- Seams between tiles usually mean `REPEAT` where you wanted `CLAMP_TO_EDGE`, or half-texel UV bleed — inset UVs by half a texel.

package/skills/threat-model/SKILL.md

@@ -0,0 +1,23 @@
+---
+name: threat-model
+description: Produce a quick STRIDE-based threat model for a feature with ranked threats and mitigations
+category: security
+---
+
+# Threat Model
+
+Use this when designing or reviewing a feature to surface what can go wrong before it ships — a lightweight, decision-ready threat model.
+
+1. Scope it: state the feature, its assets (data, money, capabilities), the actors (users, admins, external services, attackers), and the trust boundaries.
+2. Sketch the data flow: entry points, components, data stores, and where data crosses a trust boundary (these are the interesting spots).
+3. Enumerate threats per boundary using STRIDE (Spoofing, Tampering, Repudiation, Info disclosure, Denial of service, Elevation of privilege).
+4. Rank each threat by likelihood x impact; drop the implausible ones to keep the model actionable.
+5. Assign each top threat a mitigation (control, design change, or accepted-risk) and who/what enforces it.
+6. List residual risks and any assumptions the design depends on (e.g. "TLS terminates upstream", "tenant id is trusted from gateway").
+
+## Rules
+- Keep it lean and decision-oriented — a one-page model that ships beats an exhaustive one that does not.
+- Anchor on trust boundaries; most real threats live where data or control crosses one.
+- Every retained threat needs an owner-able mitigation or an explicit accepted-risk note.
+- State assumptions plainly — an unvalidated assumption is a future vulnerability.
+- Revisit the model when the feature's data flow or trust boundaries change.

package/skills/thumbnail/SKILL.md

@@ -0,0 +1,24 @@
+---
+name: thumbnail
+description: Generate and debug thumbnails and responsive srcset — aspect ratio, sharpness, format, and the picked source
+category: visual-test
+---
+
+# Thumbnail
+
+Reach for this when thumbnails come out stretched, blurry, wrong-format, or the browser picks the wrong `srcset` candidate.
+
+1. Reproduce against the actual source asset: pull the original, note its real dimensions and aspect ratio, and run the resize step in isolation.
+2. Diagnose distortion: stretched output means the resize ignored aspect ratio — decide fit (`cover` crop vs `contain` letterbox) explicitly and apply it.
+3. Diagnose blur: re-encoding at low quality, upscaling a small source, or a bad downscale filter — downscale with a quality filter (Lanczos/area) and never upscale past the source.
+4. Pick the format deliberately: serve AVIF/WebP with a JPEG/PNG fallback; debug `<picture>`/`type` negotiation by checking which candidate the browser actually requested.
+5. Build the `srcset` with real intrinsic widths and a correct `sizes` attribute, then verify in devtools (Network → the chosen file, `currentSrc`) that the expected candidate loads at each DPR/viewport.
+6. Confirm visually: render each generated size at its display box and diff against the source crop to catch off-by-one cropping or wrong gravity.
+
+## Rules
+- Decide and document fit mode (cover vs contain) per use case — silent stretching is the most common thumbnail bug.
+- Never upscale beyond the source resolution; generate only sizes ≤ original and let CSS handle the rest.
+- `sizes` is required for `srcset` width descriptors to work — a missing/wrong `sizes` makes the browser fetch the largest candidate every time.
+- Use a proper downscaling filter and a sane quality setting; default/fast filters produce mushy thumbnails.
+- Verify the *picked* source via `img.currentSrc` and the Network tab, not by guessing from the markup.
+- Generate at device pixel ratios (1x/2x/3x) and cache by content hash so a re-upload busts stale thumbnails.

package/skills/todo-scan/SKILL.md

@@ -0,0 +1,23 @@
+---
+name: todo-scan
+description: Collect TODO/FIXME/HACK comments across the codebase into a triaged, actionable backlog
+category: productivity
+---
+
+# Todo Scan
+
+Reach for this when you want a single inventory of the inline debt scattered through code comments, turned into a backlog you can prioritize instead of a pile of grep hits.
+
+1. Grep the tree for the marker set: `TODO`, `FIXME`, `HACK`, `XXX`, `BUG`, `OPTIMIZE` (case-insensitive), excluding `node_modules`, `vendor`, build, and lockfiles.
+2. For each hit capture file path, line number, the marker type, and the full comment text plus a line or two of surrounding context.
+3. Normalize duplicates and multi-line comments into one entry each; drop commented-out code and false positives (e.g. the word "todo" in a string or doc).
+4. Tag every entry with a rough severity (blocker / should-fix / nice-to-have) and a guessed area (auth, db, ui, build, tests) from the path.
+5. Sort by severity then area, and emit a Markdown table: marker, severity, location (`path:line`), summary.
+6. Surface any entry that names a person, ticket id, or a date that has already passed — those are the highest-signal items.
+
+## Rules
+- Report `path:line` for every item so it is click-to-open; never paraphrase a location.
+- Do not edit, resolve, or delete the comments — this skill only inventories them.
+- Skip generated/vendored directories and minified files or the list drowns in noise.
+- Distinguish marker types in output; a `FIXME` is not the same priority as an aspirational `TODO`.
+- If the scan returns more than ~50 items, summarize counts per area first, then list the top items rather than dumping everything.

package/skills/tool-definition/SKILL.md

@@ -0,0 +1,23 @@
+---
+name: tool-definition
+description: Define a new agent tool/function schema the LLM can call reliably
+category: agent-llm
+---
+
+# Tool Definition
+
+Use this when adding a callable tool/function to an agent so the model invokes it with correct arguments and at the right time.
+
+1. Name the tool as a clear verb_noun (e.g. `search_orders`, `create_invoice`); the name is the model's primary cue for when to call it.
+2. Write a description that states what it does, when to use it, and when NOT to use it — this matters more than the schema for routing accuracy.
+3. Define a JSON-Schema for inputs: type every field, mark required vs optional, use enums for fixed choices, and add per-field descriptions.
+4. Constrain inputs to reduce ambiguity — prefer enums over free text, give formats (date, uri) and examples in field descriptions.
+5. Specify the return shape and keep it compact: return only what the model needs downstream, not raw dumps.
+6. Test with adversarial prompts (ambiguous, missing args, wrong tool) and confirm the model selects correctly and fills required fields.
+
+## Rules
+- One tool = one job; if the description needs "and", split it into two tools.
+- Make required fields truly required; optional-but-important fields get a description telling the model when to set them.
+- Avoid overlapping tools with near-identical descriptions — the model will pick at random; disambiguate explicitly.
+- Echo back enough context in the result for multi-step reasoning, but truncate large payloads (paginate or summarize).
+- Never trust model-supplied arguments for security decisions; re-validate and authorize server-side.

package/skills/trace-flow/SKILL.md

@@ -0,0 +1,23 @@
+---
+name: trace-flow
+description: Trace a request or data flow end-to-end across layers, from entry point to final effect
+category: code-understanding
+---
+
+# Trace Flow
+
+Use to follow a single request, event, or piece of data through the system — e.g. "what happens when a user submits this form?" — across the layers it touches.
+
+1. Find the entry point: the route, handler, listener, CLI command, or subscriber where the flow begins.
+2. Step forward through each call, recording the file, function, and what transforms the data at that hop.
+3. Cross boundaries deliberately: middleware, service calls, queues, DB reads/writes, external APIs, and async/await or callback handoffs.
+4. Track the data shape as it changes — note where it is validated, mapped, enriched, or persisted.
+5. Identify the terminal effect: the response returned, row written, message published, or file emitted.
+6. Lay out the path as an ordered list of hops with file:line, and mark branch points, retries, and error/rollback paths.
+
+## Rules
+- Async boundaries break the call stack — connect producers to consumers by the queue/topic/event name, not by control flow.
+- Note where the flow forks (conditionals, fan-out) instead of silently following one branch.
+- Call out side effects along the way (logging, caching, metrics) separately from the main data path.
+- If a hop dispatches dynamically and you cannot resolve the target, say so rather than guessing.
+- Anchor every hop to a concrete file:line so the reader can follow along.

package/skills/tracing/SKILL.md

@@ -0,0 +1,23 @@
+---
+name: tracing
+description: Add distributed tracing spans with OpenTelemetry to follow requests across services
+category: observability
+---
+
+# Tracing
+
+Use this when a request crosses service or async boundaries and you need to see where time goes and how calls fan out.
+
+1. Install the OpenTelemetry SDK plus auto-instrumentations for your HTTP/DB/queue libraries, and configure an OTLP exporter to your collector or backend (Jaeger, Tempo, Honeycomb).
+2. Set a `service.name` resource attribute and a sampler (parent-based, with a ratio for high-traffic services) in the tracer provider.
+3. Enable auto-instrumentation first — it covers inbound/outbound HTTP, DB clients, and frameworks for free; verify spans appear before adding manual ones.
+4. Add manual spans only around meaningful units of work the libraries don't cover (business logic, batch steps), naming them `verb.noun` (`charge.card`).
+5. Attach attributes for high-signal context (`tenant.id`, `job.kind`, row counts) and record exceptions with `span.recordException` + set status `ERROR`.
+6. Ensure W3C `traceparent` propagation across service calls and into async work (queues, background jobs) so traces stay connected; verify an end-to-end trace links all hops.
+
+## Rules
+- One trace per logical request; don't start a new root span mid-request — continue the propagated context.
+- Keep span names low-cardinality (no IDs in the name — put IDs in attributes).
+- Always `end()` spans, including on error paths; use a try/finally or scoped helper.
+- Sample at the head consistently across services so traces aren't half-recorded.
+- Never put secrets, full request bodies, or PII in span attributes.

package/skills/train-model/SKILL.md

@@ -0,0 +1,24 @@
+---
+name: train-model
+description: Scaffold a reproducible model training script with proper splits and checkpoints
+category: data-ml
+---
+
+# Train Model
+
+Use when setting up a training run for a classical ML or deep learning model and you want a reproducible, debuggable script rather than a notebook mess.
+
+1. Split data into train/validation/test up front with a fixed seed; for time series or grouped data, split by time/group to prevent leakage.
+2. Fit all preprocessing (scaling, encoding, imputation) on train only, then apply to val/test — wrap in a pipeline so it travels with the model.
+3. Set and log seeds, hyperparameters, data version, and code commit so the run is reproducible.
+4. Train with a small subset first to confirm the loss decreases and the script runs end-to-end before the full run.
+5. Track train and validation metrics each epoch/iteration; checkpoint the best model by the validation metric, not train loss.
+6. Add early stopping or a fixed budget, then evaluate the final model on the untouched test set exactly once.
+7. Save the model, the fitted preprocessing, and a metrics summary as artifacts.
+
+## Rules
+- The test set is touched once, at the very end — never for tuning or model selection.
+- Fit preprocessing on train only; fitting on the full dataset leaks the target into training.
+- Always run an overfit-one-batch smoke test before committing to a long run.
+- Log seed, config, and data version with every run so results can be reproduced.
+- Select and checkpoint on the validation metric; report the held-out test metric as the headline number.

package/skills/tree-shake/SKILL.md

@@ -0,0 +1,23 @@
+---
+name: tree-shake
+description: Eliminate unused imports and exports so dead code is dropped from the bundle
+category: dependencies
+---
+
+# Tree Shake
+
+Reach for this when dead code is shipping because imports/exports aren't being eliminated by the bundler.
+
+1. Run a static analyzer (`knip`, `ts-prune`, ESLint `no-unused-vars`/`unused-imports`) to list unused imports and unreferenced exports.
+2. Remove unused imports and delete or stop exporting symbols nothing consumes.
+3. Replace whole-module/namespace imports with named imports so the bundler can drop the rest.
+4. Break up barrel (`index.ts` re-export) files or mark them side-effect-free so importing one symbol doesn't pull the whole directory.
+5. Set `"sideEffects": false` (or an explicit file list) in package.json and keep the build target ESM.
+6. Rebuild and confirm the removed code is gone from the output via the bundle analyzer.
+
+## Rules
+- Don't remove an export that's part of the public API just because it's unused internally.
+- Watch for imports kept only for side effects (polyfills, CSS, registrations) — flagging `sideEffects: false` wrongly drops them.
+- Named imports tree-shake; `import * as x` and default-object imports usually don't.
+- Barrel files defeat tree-shaking in many bundlers — import from the source module directly.
+- Verify the result in the actual build output, not just the linter — analysis and bundling differ.

package/skills/ts-generics/SKILL.md

@@ -0,0 +1,23 @@
+---
+name: ts-generics
+description: Improve TypeScript generics and inference so call sites stay type-safe without manual annotations
+category: languages
+---
+
+# Ts Generics
+
+Reach for this when an API forces callers to annotate types manually, returns `any`, or loses the relationship between input and output types.
+
+1. Identify where types are flowing through: a function/class that takes a value and should return a type derived from it is a generics candidate.
+2. Introduce type parameters that get inferred from arguments (`function get<T>(obj: T, key: keyof T)`) so callers never pass `<...>` explicitly.
+3. Constrain parameters with `extends` (`<T extends Record<string, unknown>>`) to enable property access and reject bad inputs at the call site.
+4. Use conditional and mapped types (`T extends U ? A : B`, `{ [K in keyof T]: ... }`) and `infer` to transform types instead of widening to `any`.
+5. Preserve literal types where they matter with `const` type parameters (`<const T>`) or `as const`, so unions don't collapse to `string`/`number`.
+6. Verify inference with type-level tests (`expectTypeError` / `// @ts-expect-error`) and by hovering real call sites — confirm no caller needs explicit args.
+
+## Rules
+- A generic that appears only once in a signature is usually pointless — each type parameter should connect at least two positions (input↔output).
+- Constrain before you access: you can't read `t.id` off an unconstrained `T` — add `extends { id: ... }`.
+- Don't over-engineer; if a plain union or overload is clearer than a conditional type, use it.
+- Keep error messages legible — deeply nested conditional types produce inscrutable errors; name intermediate types as aliases.
+- Default type parameters (`<T = unknown>`) for ergonomics, but never default to `any`.

package/skills/ts-strict/SKILL.md

@@ -0,0 +1,23 @@
+---
+name: ts-strict
+description: Enable TypeScript strict mode and fix the resulting type errors safely
+category: languages
+---
+
+# Ts Strict
+
+Use this when turning on `strict` (or its sub-flags) in a TypeScript project that compiled loosely, and you need to clear the error wave without papering over real bugs.
+
+1. Enable flags incrementally in `tsconfig.json`: start with `strictNullChecks`, then `noImplicitAny`, then `strictFunctionTypes`, rather than flipping `strict: true` blind.
+2. Run `tsc --noEmit` and triage by file/error code; fix the highest-frequency code (often `TS2532` undefined / `TS7006` implicit any) first.
+3. For null/undefined errors, narrow with guards (`if (x == null) return`), optional chaining `?.`, or nullish coalescing `??` — not `!` non-null assertions by default.
+4. Replace implicit `any` with real types or `unknown` plus a narrowing check; type function params and exported signatures explicitly.
+5. Fix unsafe index access (`noUncheckedIndexedAccess`) by handling the `undefined` case from `arr[i]` and `map[key]`.
+6. Re-run `tsc --noEmit` until clean, then commit each flag separately so regressions are bisectable.
+
+## Rules
+- Prefer `unknown` over `any` when a type is genuinely open — it forces a check at the use site.
+- Use `!` and `as` casts sparingly; each one is a place the compiler can no longer protect you — leave a comment justifying it.
+- Don't add `// @ts-ignore`/`// @ts-expect-error` to bulk-clear errors; reserve them for known upstream typing bugs and prefer `@ts-expect-error` so they self-remove when fixed.
+- Keep `tsconfig` changes and code fixes in lockstep; turning on a flag without fixing its errors breaks the build for everyone.
+- Don't loosen library types you don't own — wrap them in a typed adapter instead.

package/skills/tui-app/SKILL.md

@@ -0,0 +1,23 @@
+---
+name: tui-app
+description: Build a terminal UI app with a render loop, input handling, and clean teardown using ratatui, ink, or textual
+category: shell
+---
+
+# TUI App
+
+Reach for this when building an interactive full-screen terminal application — dashboards, pickers, file browsers — with keyboard navigation and live updates.
+
+1. Pick a framework: Rust → `ratatui` + `crossterm`, Node → `ink` (React-style), Python → `textual` or `urwid`.
+2. Model state explicitly (a single app struct/store) and render the whole UI as a pure function of that state each frame — never mutate widgets imperatively from scattered handlers.
+3. Run an event loop that blocks on input/timer events, updates state, then redraws; keep heavy or blocking work (I/O, network) off the UI thread via async tasks or a worker channel.
+4. On startup enter raw mode and the alternate screen; on exit — including panics and Ctrl-C — restore the terminal so the user's shell isn't left corrupted.
+5. Handle resize events and recompute layout; never hardcode width/height, and degrade gracefully on tiny terminals.
+6. Provide clear key hints and a quit binding (`q`/Ctrl-C), and test the render-from-state logic without a real TTY.
+
+## Rules
+- Always restore the terminal on exit: wrap teardown in a guard/`defer`/panic hook so a crash mid-frame doesn't leave a broken shell.
+- Keep the event loop non-blocking; spawn long tasks elsewhere and feed results back as events, or the UI freezes.
+- Throttle redraws (only on state change or a frame tick) instead of busy-looping the CPU at full speed.
+- Don't print to stdout/stderr while in alternate-screen mode — it scrambles the display; route logs to a file.
+- Make every action keyboard-reachable and show the active keymap; assume no mouse.

package/skills/tutorial/SKILL.md

@@ -0,0 +1,24 @@
+---
+name: tutorial
+description: Write a getting-started tutorial that takes a new user from install to a first working result
+category: docs
+---
+
+# Tutorial
+
+Use this to create a guided, linear walkthrough that gets a newcomer to a small success quickly. Unlike reference docs, a tutorial is a single happy path the reader follows top to bottom.
+
+1. Pick one concrete end goal a beginner can reach in 10-15 minutes ("send your first request", "render a page").
+2. State prerequisites up front: tools, accounts, versions the reader must have.
+3. Break the path into numbered steps; each step is one action with the exact command or code to paste.
+4. After each step, show the expected output so the reader can confirm they're on track.
+5. End with a working result, then a short "next steps" pointing to deeper docs.
+6. Add a brief troubleshooting note for the one or two failures beginners actually hit.
+7. Run the whole tutorial from a clean environment yourself and fix anything that doesn't work verbatim.
+
+## Rules
+- One linear happy path — defer options, edge cases, and theory to reference docs.
+- Every code block must be copy-pasteable and produce the shown output.
+- Show expected output after steps so readers can self-correct.
+- Test it end to end from a fresh setup; a tutorial that fails at step 3 is worse than none.
+- Keep prerequisites honest and minimal; don't assume tools the reader hasn't installed.

package/skills/type-tighten/SKILL.md

@@ -0,0 +1,23 @@
+---
+name: type-tighten
+description: Strengthen types and remove anys/implicit untyped code in TS or mypy
+category: refactoring
+---
+
+# Type Tighten
+
+Use when types are loose, missing, or littered with `any`/`Any`, letting bugs slip past the checker. The goal is precise types that document intent and catch errors.
+
+1. Turn on or raise strictness incrementally (`strict`, `noImplicitAny`; mypy `--strict` / `disallow-untyped-defs`) and read the new errors.
+2. Replace `any`/`Any` with concrete types, unions, generics, or `unknown` plus a narrowing check.
+3. Annotate function signatures (params and returns) so call sites are checked, not just bodies.
+4. Add narrowing at boundaries — validate or guard external/JSON input rather than asserting its type.
+5. Run the type checker and the test suite; fix real type errors instead of suppressing them.
+6. Confirm no runtime behavior changed — types should be erased/ignored at runtime.
+
+## Rules
+- Prefer `unknown` over `any` when a type is truly open, then narrow before use.
+- Avoid `as`/`cast` and `# type: ignore` as fixes; each one is a hole — justify any you keep with a comment.
+- Don't let added types change runtime behavior (e.g. introducing a default value via an annotation).
+- Tighten at the edges first (public APIs, I/O boundaries); internal inference often follows for free.
+- If a precise type is genuinely impractical, narrow as far as cheaply possible rather than defaulting to `any`.

package/skills/typography/SKILL.md

@@ -0,0 +1,24 @@
+---
+name: typography
+description: Set an intentional modular type scale and font pairing with deliberate rhythm, measure, and hierarchy
+category: ui-design
+---
+
+# Typography
+
+Reach for this when text feels flat or noisy — everything the same weight, headings barely larger than body, lines too long to read. Typography carries most of a UI's perceived quality.
+
+1. Pick a scale ratio and generate sizes from one base: 1.2 (minor third) for dense product UI, 1.25–1.333 for marketing. Use `clamp()` for fluid headings: `clamp(2rem, 1.2rem + 3vw, 3.5rem)`.
+2. Pair at most two families with real contrast in role — e.g. a characterful display serif (Fraunces) over a neutral workhorse sans (Inter), or one superfamily across weights. More than two fonts reads as chaos.
+3. Set body deliberately: 15–18px, `line-height` 1.5–1.65, and constrain measure to 60–75ch with `max-width: 65ch`. Long lines are the most common readability failure.
+4. Build hierarchy with weight and size and color together — not size alone. A muted `--text-muted` for captions, a heavier 600–700 for headings, tight tracking (`-0.02em`) on large display text.
+5. Tighten leading as size grows (headings 1.1–1.2, body 1.5) and add `text-wrap: balance` on headings, `pretty` on paragraphs to kill orphans.
+6. Enable OpenType features that fit the context: `font-feature-settings` for tabular numerals in tables/dashboards, ligatures for prose; `font-variant-numeric: tabular-nums` stops number jitter.
+7. Verify the rendered rhythm at real sizes and viewports, not in the abstract — print a paragraph plus h1–h4 and adjust.
+
+## Rules
+- Two type families maximum; if you need a third role, change weight, not font.
+- Body measure 60–75ch; never let prose run the full container width.
+- Pair every font-size with an intentional line-height — don't inherit a global 1.5 onto display text.
+- Use tabular numerals anywhere numbers align in columns or update live.
+- Establish scale steps as tokens; reaching for an off-scale `font-size: 19px` is a smell.

package/skills/ui-bug-repro/SKILL.md

@@ -0,0 +1,23 @@
+---
+name: ui-bug-repro
+description: Turn a screenshot or screen recording of a UI bug into a deterministic, scripted reproduction
+category: visual-test
+---
+
+# UI Bug Repro
+
+Reach for this when someone hands you a screenshot or recording of broken UI and you need to reproduce it reliably before you can fix it.
+
+1. Extract the context from the artifact: read the visible URL/route, viewport dimensions (from image size + DPR), theme, locale, and any error text or console overlay.
+2. Reconstruct the path: from a recording, step frame-by-frame to list the exact actions (clicks, inputs, scrolls, resizes) and the data state that triggered the bug.
+3. Script those steps in the app's driver (browser automation / e2e runner) at the same viewport and DPR, seeding the same data, until you see the bug live.
+4. Capture your reproduced screenshot and overlay/diff it against the reported one to confirm you've hit the *same* failure, not a lookalike.
+5. Bisect the trigger: remove steps and vary one input (viewport, data length, font, async timing) to find the minimal condition that produces it.
+6. Commit the repro as a failing test, then fix and watch it go green.
+
+## Rules
+- The viewport, DPR, and theme are often the whole bug; derive them from the image (pixel dimensions ÷ DPR) before guessing.
+- Reproduce with the reporter's *data shape* (long strings, empty states, RTL, huge numbers) — most "only on my screen" UI bugs are data-driven.
+- Race conditions and animation-timing bugs need controlled async (fake timers, throttled network) to reproduce on demand.
+- Confirm the repro by diffing against the original artifact; "looks similar" is how you fix the wrong bug.
+- Land the failing repro test first — a UI bug without a reproducing test regresses within a sprint.

package/skills/ui-polish/SKILL.md

@@ -0,0 +1,24 @@
+---
+name: ui-polish
+description: Elevate a rough but working UI — fix spacing, alignment, hierarchy, and the small details that read as quality
+category: ui-design
+---
+
+# UI Polish
+
+Reach for this on a UI that functions but feels amateur — cramped, misaligned, flat. Polish is mostly subtraction and precision, not adding more.
+
+1. Establish a spacing rhythm: snap every margin/padding/gap to the 4px (or 8px) scale, and make whitespace intentional — generous around groups, tight within them. Inconsistent gaps are the #1 tell.
+2. Fix alignment to an actual grid: align edges and baselines, give content a `max-width` and consistent gutters, and make optical adjustments (icons often need a nudge to look centered).
+3. Sharpen hierarchy: there should be an obvious first, second, and third thing on every screen. Use size, weight, and `--text-muted` color to demote secondary text instead of cramming everything at one level.
+4. Tame the details: soften pure-black text to a near-black, swap harsh `0 1px 2px #000` shadows for layered low-alpha ones, align radii across siblings, and ensure border colors are subtle (low-contrast neutrals).
+5. Polish interaction: add `:focus-visible` rings, hover/active feedback, and tasteful transitions (120–200ms, `ease-out`) on color and transform — never on `width`/`height` (use `transform`).
+6. Handle the real states: empty, loading (skeletons over spinners), error, and long-content overflow. Unpolished UIs only ever show the happy path.
+7. Do a final squint test and a 50%-zoom pass — blurred vision exposes weak hierarchy and ragged alignment instantly.
+
+## Rules
+- Every spacing value is on the scale; an unexplained `padding: 13px` is a defect.
+- Increase contrast in hierarchy, decrease it in chrome — borders and shadows should whisper.
+- Animate `transform`/`opacity` only; transitions 120–250ms with `ease-out`/custom cubic-bezier.
+- Never ship without focus-visible, hover, empty, and loading states.
+- When in doubt, remove an element or add whitespace before adding decoration.

package/skills/ui-review/SKILL.md

@@ -0,0 +1,24 @@
+---
+name: ui-review
+description: Critique a UI for visual quality, consistency, and hierarchy, returning specific, prioritized fixes
+category: ui-design
+---
+
+# UI Review
+
+Use this to evaluate an existing screen with a senior designer's eye and produce concrete, actionable critique — not "looks good" but "the h2 and body are too close in size; bump the scale ratio to 1.25."
+
+1. Read intent first: what is this screen for, what's the one primary action? Judge everything against whether the design serves that goal and points the eye to it.
+2. Check hierarchy with the squint test: blur your vision (or zoom to 50%) and confirm the most important element dominates. If everything competes, that's finding #1.
+3. Audit consistency: collect the distinct spacings, font sizes, colors, radii, and shadows in play. Off-scale or near-duplicate values (15px vs 16px, two almost-equal grays) are concrete defects to list.
+4. Measure the fundamentals: contrast ratios on text (AA 4.5:1), body measure (60–75ch), alignment to a grid, and spacing rhythm. Flag exact violations with the failing value.
+5. Inspect states and motion: are focus-visible, hover, empty, loading, and error handled? Are transitions tasteful (120–250ms, eased) or janky/missing?
+6. Assess the aesthetic: is there a point of view, or does it read templated? Name the one change that would most raise perceived quality.
+7. Return findings ranked by impact, each as observation → why it hurts → specific fix, separating must-fix from nice-to-have.
+
+## Rules
+- Every critique is specific and actionable — name the element, the failing value, and the fix.
+- Lead with hierarchy and consistency; they drive perceived quality more than color choice.
+- Cite measurable thresholds (contrast, measure, spacing scale) instead of vibes.
+- Prioritize: 3 high-impact fixes beat 30 nitpicks.
+- Acknowledge what works so good decisions survive the next iteration.

package/skills/vendor/SKILL.md

@@ -0,0 +1,23 @@
+---
+name: vendor
+description: Vendor a tiny dependency into the repo to drop the package and its install/supply-chain cost
+category: dependencies
+---
+
+# Vendor
+
+Reach for this when a dependency is small enough that copying its source in beats carrying the package and its tree.
+
+1. Confirm it's worth vendoring: the package is tiny, stable, and has few/no transitive deps — otherwise keep the dependency.
+2. Check the license permits copying and note the requirement (attribution, header retention) for the vendored file.
+3. Copy the minimal source you actually use into a clearly named `vendor/` (or `internal/`) path, preserving the license header.
+4. Record provenance: a comment or NOTICE with the package name, version, source URL, and license.
+5. Replace imports of the package with the local path, then remove the dependency from the manifest and lockfile.
+6. Run tests and a build; reinstall clean to confirm the package is fully gone.
+
+## Rules
+- Only vendor small, slow-moving code — vendoring something that gets security patches means you now own those patches.
+- Preserve the original license header and attribution; stripping it is a license violation.
+- Pin the exact version you copied and write down where it came from for future updates.
+- Trim to what you use, but don't refactor the vendored code — keep it diffable against upstream.
+- After removing the dep, confirm nothing else (peer deps, types) still references it.