ada-agent 0.1.0

package/skills/react-native-screen/SKILL.md

@@ -0,0 +1,23 @@
+---
+name: react-native-screen
+description: Add a React Native screen and wire it into the navigation stack
+category: mobile
+---
+
+# React Native Screen
+
+Use this when adding a new screen to a React Native app and registering it with React Navigation so it can be pushed, linked, and typed.
+
+1. Create the screen component (e.g. `screens/DetailsScreen.tsx`) as a function component that destructures `navigation` and `route` from props.
+2. Register it on the navigator: add a `<Stack.Screen name="Details" component={DetailsScreen} />` in the stack where it belongs.
+3. Extend the param list type (`type RootStackParamList = { Details: { id: string } }`) and type props with `NativeStackScreenProps<RootStackParamList, 'Details'>`.
+4. Navigate in with `navigation.navigate('Details', { id })`; read inputs via `route.params` and go back with `navigation.goBack()`.
+5. Wrap content in `SafeAreaView` (or `useSafeAreaInsets`) and set `options={{ title }}` so the header and notches render correctly.
+6. Add a deep-link path under `linking.config.screens` if the screen should be reachable by URL, then test push + back + deep link on device.
+
+## Rules
+- Keep navigation param payloads small and serializable — pass IDs, not whole objects or functions.
+- Don't call `navigation.navigate` during render; do it in an effect or an event handler.
+- Use `useFocusEffect`/`useIsFocused` for work that should run when the screen gains focus, not `useEffect` alone.
+- Type the param list once and reuse it everywhere to catch wrong-param navigations at compile time.
+- Account for the header height and safe-area insets so content isn't clipped under the notch or status bar.

package/skills/react-perf/SKILL.md

@@ -0,0 +1,23 @@
+---
+name: react-perf
+description: Diagnose and eliminate needless React re-renders with memoization
+category: frameworks
+---
+
+# React Perf
+
+Use when a component tree re-renders too often or feels janky, and you need to find and cut the wasted work — measure first, optimize second.
+
+1. Profile with the React DevTools Profiler (or `<Profiler>`) to find which components re-render and why; don't guess.
+2. Identify the trigger: a new object/array/function prop created each render, an over-broad context, or state lifted too high.
+3. Stabilize prop identities with `useMemo` (values) and `useCallback` (functions) so memoized children actually skip renders.
+4. Wrap pure leaf/list components in `React.memo`; for lists, ensure stable `key`s that aren't array indices.
+5. Split or scope context, or lift state down, so a frequently-changing value doesn't re-render the whole subtree.
+6. Re-profile to confirm the render count dropped; remove any memoization that didn't move the needle.
+
+## Rules
+- Never optimize without a before/after measurement — memoization has its own cost.
+- `React.memo` is useless if you pass it a freshly-created object/callback each render; fix the parent first.
+- Inline `{}`/`[]`/`() => {}` in JSX create new references every render — hoist or memoize them.
+- A `useMemo`/`useCallback` with wrong deps reintroduces the bug or causes stale closures; keep deps honest.
+- Heavy work in render belongs in `useMemo` or out of the component; effects don't make render faster.

package/skills/readme/SKILL.md

@@ -0,0 +1,24 @@
+---
+name: readme
+description: Write or refresh a README covering what the project is, why it exists, install, and usage
+category: docs
+---
+
+# Readme
+
+Reach for this when a repo has no README, a stale one, or a wall of text nobody reads. The goal is a doc that gets a newcomer from clone to running in minutes.
+
+1. Skim the codebase to confirm what the project actually does: entry points, package manifest (`package.json`, `pyproject.toml`, `Cargo.toml`), and any existing docs.
+2. Open with a one-line description and a short "why" — the problem it solves, who it's for.
+3. Write an Install section with the exact commands you verified work (clone, dependency install, build).
+4. Write a Usage section with a minimal copy-pasteable example that produces visible output.
+5. Add Configuration (env vars, flags, config files) only if the project needs it — link don't inline long tables.
+6. Add short sections as warranted: Requirements/prerequisites, Development/contributing, License.
+7. Run the install and usage commands yourself; fix the README to match reality before finishing.
+
+## Rules
+- Lead with what it does and why, not a logo or badge wall.
+- Every command must be one you actually ran or verified — no aspirational steps.
+- Keep it scannable: headings, short paragraphs, fenced code blocks with language hints.
+- Don't document internals or every flag; link to deeper docs instead of bloating the README.
+- Match the project's existing tone and the real install method (npm vs pnpm, pip vs uv).

package/skills/rebase/SKILL.md

@@ -0,0 +1,24 @@
+---
+name: rebase
+description: Clean up branch history with interactive rebase without rewriting shared commits
+category: git
+---
+
+# Rebase
+
+Use this to tidy a feature branch's history — reorder, reword, fixup, or drop commits, or replay onto an updated base — while keeping commits that others have already pulled intact.
+
+1. Confirm the branch is yours and unshared, or that collaborators agree to a force-push; never rewrite history on `main`/shared branches.
+2. Snapshot a safety net: note the current SHA (`git rev-parse HEAD`) or create a backup branch (`git branch backup/<name>`) so you can recover.
+3. Update the base first: `git fetch origin` then `git rebase origin/main` (or `git rebase -i origin/main` to also clean history in one pass).
+4. In interactive mode pick actions per line — `reword`, `squash`/`fixup`, `edit`, `drop`, reorder — keeping the oldest commit at the top.
+5. Resolve any conflicts as they surface: fix files, `git add`, then `git rebase --continue`; use `git rebase --abort` to bail back to the pre-rebase state.
+6. Verify the result: `git log --oneline origin/main..HEAD` and run tests, since rebasing can silently break a previously-working intermediate state.
+7. Publish with `git push --force-with-lease` (safer than `--force`: it refuses if the remote moved unexpectedly).
+
+## Rules
+- Only rebase commits that exist solely on your local/feature branch; rebasing pushed-and-pulled commits breaks teammates.
+- Always force-push with `--force-with-lease`, never plain `--force`.
+- Keep a backup branch or recorded SHA before starting; `git reflog` is your fallback if you skipped that.
+- Resolve conflicts commit-by-commit — don't blindly `git checkout --theirs/--ours` without understanding each.
+- If a rebase gets messy, `git rebase --abort` and reconsider rather than fighting it.

package/skills/refactor/SKILL.md

@@ -0,0 +1,23 @@
+---
+name: refactor
+description: Make a safe, behavior-preserving refactor with tests green at every step
+category: refactoring
+---
+
+# Refactor
+
+Reach for this when you want to improve structure, names, or design without changing observable behavior. The contract: every commit compiles and passes tests.
+
+1. Establish a baseline — run the test suite and confirm it is green before touching anything.
+2. If coverage is thin around the target code, add characterization tests that pin current behavior first.
+3. Make one small structural change at a time (extract, rename, move, inline); avoid mixing in behavior changes.
+4. Re-run the relevant tests after each change; if red, revert that step rather than debugging forward.
+5. Commit each green step separately with a message describing the structural move.
+6. When done, diff against the start and verify no public API, output, or side effect changed.
+
+## Rules
+- Never refactor and fix a bug or add a feature in the same commit — split them.
+- If the suite is too slow, run a fast subset per step and the full suite before pushing.
+- Keep the diff reviewable; a refactor PR with logic changes hiding inside is a trap.
+- If tests are missing and can't be added cheaply, say so and proceed with extra caution, not silently.
+- Prefer mechanical, tool-assisted transforms (IDE/LSP rename, AST codemods) over hand edits.

package/skills/regression-test/SKILL.md

@@ -0,0 +1,23 @@
+---
+name: regression-test
+description: Reproduce a reported bug as a failing test before fixing it, so it can never silently return
+category: testing
+---
+
+# Regression Test
+
+Use when fixing a reported bug: capture it as a failing test first so the fix is proven and the bug stays dead.
+
+1. Reproduce the bug manually and nail down the exact inputs, state, and steps that trigger it.
+2. Write a test that reproduces it at the lowest practical level (unit if possible, integration/E2E if it needs the stack).
+3. Run the test and confirm it FAILS, demonstrating the bug — the failure should match the reported symptom.
+4. Implement the fix and run the test until it passes; confirm the failure mode is genuinely gone.
+5. Run the surrounding suite to make sure the fix didn't break anything else.
+6. Commit the test together with the fix, referencing the bug/issue id so the link is permanent.
+
+## Rules
+- Write the failing test before the fix; a fix without a failing test first proves nothing about the bug.
+- The test must fail for the bug's actual reason — verify it goes red on unfixed code, not on a setup error.
+- Reproduce at the narrowest level that still captures the bug; reserve E2E for bugs that only appear there.
+- Name the test after the bug/symptom (and issue id) so future readers know why it exists.
+- Keep the regression test even if it overlaps existing tests; it documents a specific past failure.

package/skills/release-notes/SKILL.md

@@ -0,0 +1,24 @@
+---
+name: release-notes
+description: Generate release notes from commits since the last tag
+category: git
+---
+
+# Release Notes
+
+Use this to draft a changelog for a new release by collecting and grouping the commits made since the previous tag.
+
+1. Find the last release point: `git describe --tags --abbrev=0` gives the most recent tag to diff against.
+2. Collect the commits: `git log <last-tag>..HEAD --oneline --no-merges` (or `--pretty=format:'- %s (%h) @%an'` for richer lines).
+3. Group by type: bucket commits into Features / Fixes / Performance / Docs / Breaking Changes — Conventional Commit prefixes (`feat:`, `fix:`) make this mechanical.
+4. Surface breaking changes prominently: scan for `BREAKING CHANGE` in bodies (`git log <last-tag>..HEAD --grep='BREAKING'`) and call them out at the top.
+5. Enrich with PR/issue links where useful and credit contributors (`git shortlog -sn <last-tag>..HEAD`).
+6. Write the notes top-down: highlights first, then grouped lists, then a full commit/PR reference; tag the release and attach.
+7. For a fully-automated draft, `gh release create <tag> --generate-notes` uses GitHub's auto-generated notes as a starting point.
+
+## Rules
+- Diff from the actual last tag, not an arbitrary date — `git describe --tags --abbrev=0` is the source of truth.
+- Exclude merge commits (`--no-merges`) so the list reads as real changes.
+- Lead with breaking changes and user-facing features; bury internal/chore commits or omit them.
+- Rewrite terse commit subjects into user-readable lines — release notes are for humans, not a raw `git log` dump.
+- Verify the tag/range covers exactly the intended release; an off-by-one tag drops or duplicates entries.

package/skills/rename-symbol/SKILL.md

@@ -0,0 +1,23 @@
+---
+name: rename-symbol
+description: Rename a variable, function, type, or file safely across the whole project
+category: refactoring
+---
+
+# Rename Symbol
+
+Use when a name is misleading, stale, or inconsistent. The goal is a complete rename with zero dangling references and no accidental collateral hits.
+
+1. Prefer a language-aware rename (LSP/IDE "rename symbol") so only real references change, not text matches.
+2. If renaming by search, scope it: match word boundaries and the correct case, and review every hit before applying.
+3. Update all sites — definitions, call sites, imports/exports, type annotations, and string references (DI keys, serialized names, configs).
+4. Check dynamic/reflective uses: JSON keys, ORM column maps, reflection, templates, docs, and comments.
+5. Build and run tests to catch missed or wrongly-changed references.
+6. Grep once more for the old name to confirm only intentional leftovers remain.
+
+## Rules
+- Beware short or common names (`id`, `data`) — text search will over-match; use semantic rename only.
+- Renaming a serialized field, DB column, env var, or public API name is a behavior change, not a pure refactor — flag it.
+- Keep the rename in its own commit so the diff is auditable.
+- If a public/exported symbol must keep backward compatibility, add an alias/deprecation rather than breaking callers.
+- Don't forget filenames and the imports that reference them when renaming modules.

package/skills/repro/SKILL.md

@@ -0,0 +1,23 @@
+---
+name: repro
+description: Build a minimal, reliable reproduction of a bug before attempting to fix it
+category: debugging
+---
+
+# Repro
+
+Use when a bug is reported vaguely or only happens "sometimes." A minimal repro turns a fuzzy report into a concrete, debuggable artifact — and often reveals the cause by itself.
+
+1. Capture the original conditions: inputs, environment, versions, and the exact observed failure.
+2. Get it failing once on your machine, however ugly — full app, real data, whatever it takes.
+3. Strip it down: remove unrelated code, mock external services, shrink the input toward the smallest case that still fails.
+4. Pin nondeterminism — fix random seeds, freeze clocks, force single-threaded, hardcode the offending input — until it fails every run.
+5. Turn it into a runnable script or a failing test that anyone can execute with one command.
+6. Confirm the repro fails for the right reason (same error/trace), not a new unrelated one.
+
+## Rules
+- A repro you can't run on demand isn't done — "it happened in prod once" is a lead, not a repro.
+- Remove things one at a time; if the failure disappears, you just found a clue about the cause.
+- Keep the input as small as possible — a 3-line case beats a 300-line dump for finding the bug.
+- Prefer a failing test over a throwaway script so the repro stays as a regression guard after the fix.
+- If you genuinely can't reproduce, add logging in the real environment to capture the conditions next time it fires.

package/skills/resolve-conflicts/SKILL.md

@@ -0,0 +1,23 @@
+---
+name: resolve-conflicts
+description: Work through merge or rebase conflicts safely without losing either side's intent
+category: git
+---
+
+# Resolve Conflicts
+
+Use this when a merge, rebase, cherry-pick, or stash pop stops with conflicts. The goal is a result that preserves the intent of both sides, not just one that compiles.
+
+1. See the lay of the land: `git status` lists conflicted files; `git diff` shows the conflict markers in context.
+2. Understand both sides before editing: `git log --merge -p <file>` or `git show :1:<file>`/`:2:`/`:3:` to inspect base, ours, and theirs.
+3. Edit each file to a correct merged result — delete the `<<<<<<<`, `=======`, `>>>>>>>` markers and reconcile the logic, not just pick a side.
+4. Mark resolved: `git add <file>` per file. To take one side wholesale use `git checkout --ours <file>` or `--theirs <file>` (note: in a rebase, ours/theirs are swapped vs a merge).
+5. Continue the operation: `git merge --continue` / `git rebase --continue` / `git cherry-pick --continue`. To bail out, use the matching `--abort`.
+6. Verify before trusting: build and run tests, since a conflict resolution can be syntactically clean but semantically wrong.
+
+## Rules
+- Read both sides' intent before resolving; a merge that drops one side's logic is a silent bug.
+- Remember ours/theirs is inverted during rebase (you're replaying your commits onto theirs) — verify with `git diff` rather than guessing.
+- Always run the test suite after resolving; clean markers do not mean correct behavior.
+- Use `git merge --abort` (or rebase/cherry-pick `--abort`) to get back to a known-good state instead of half-fixing.
+- Enable `git config rerere.enabled true` to auto-reuse recorded resolutions on repeated conflicts (e.g. long rebases).

package/skills/responsive/SKILL.md

@@ -0,0 +1,23 @@
+---
+name: responsive
+description: Make a layout adapt cleanly across mobile, tablet, and desktop breakpoints
+category: frontend
+---
+
+# Responsive
+
+Use when a layout breaks, overflows, or looks cramped at some viewport sizes and needs to flex across breakpoints.
+
+1. Identify the breakpoints from the existing system (Tailwind/CSS vars/theme) rather than inventing new ones, and design mobile-first — base styles target the smallest screen.
+2. Reach for intrinsic layout first: flexbox, CSS grid, `gap`, `minmax`, `clamp()`, and `%`/`fr` units before adding media queries.
+3. Layer `min-width` media queries (or container queries when the component must adapt to its parent, not the viewport) to progressively enhance toward larger screens.
+4. Make media fluid: `max-width: 100%` on images, responsive `srcset`/`sizes`, and `aspect-ratio` to prevent layout shift.
+5. Handle text and spacing: fluid type via `clamp()`, wrap/scroll long content, and ensure tap targets are at least ~44px on touch.
+6. Test at real breakpoints and in between (narrow, tablet, wide, and the awkward sizes), checking for overflow, clipped content, and horizontal scroll.
+
+## Rules
+- Write mobile-first: unconditional base styles, then `min-width` queries that add, not undo.
+- Avoid fixed pixel widths/heights on containers; let content and the grid dictate size.
+- Never cause horizontal scroll — watch for fixed widths, large images, and `100vw` + padding.
+- Use container queries when a reusable component lives in varying-width slots.
+- Don't hide content on small screens to "fix" layout unless it's genuinely redundant.

package/skills/rest-endpoint/SKILL.md

@@ -0,0 +1,23 @@
+---
+name: rest-endpoint
+description: Scaffold a REST endpoint with handler, input validation, and tests
+category: api
+---
+
+# Rest Endpoint
+
+Reach for this when adding a new HTTP route (GET/POST/PUT/PATCH/DELETE) that needs a handler, validated input, and coverage.
+
+1. Find the existing routing layer and copy the nearest sibling endpoint's structure (router registration, file layout, naming).
+2. Define request/response shapes: path params, query params, and body — derive types from the validation schema, don't hand-write both.
+3. Validate input at the boundary (e.g. zod/pydantic/joi) and return 400 with field-level errors on failure before any business logic.
+4. Implement the handler: call the service/data layer, never inline DB queries in the route if the codebase separates them.
+5. Map errors to status codes deliberately — 404 not-found, 409 conflict, 422 unprocessable, 401/403 auth — and avoid leaking internals in 500s.
+6. Register the route and write tests: happy path, one validation-failure case, and one auth/not-found case.
+
+## Rules
+- Match the project's existing conventions (status codes, error envelope, casing) over any external "best practice".
+- Validate and parse untrusted input before it reaches business logic; reject unknown fields if the codebase does.
+- Keep handlers thin — orchestration only; push logic into services so it's unit-testable.
+- Use the correct verb and idempotency: POST creates, PUT/PATCH update, DELETE is idempotent.
+- Never return raw exception messages or stack traces to clients.

package/skills/retro/SKILL.md

@@ -0,0 +1,23 @@
+---
+name: retro
+description: Write a sprint or project retrospective that turns observations into committed action items
+category: productivity
+---
+
+# Retro
+
+Use this at the end of a sprint, milestone, or project to capture what happened and convert it into concrete changes — a retro without owned action items is just venting.
+
+1. Set the window and gather inputs: the goals for the period, what shipped, plus signals from git log, merged PRs, closed issues, and CI history.
+2. Sort observations into three buckets: what went well (keep), what went poorly (stop), and what to try (start).
+3. For each "went poorly" item, dig one level past the symptom to a plausible cause rather than restating the complaint.
+4. Pull the highest-leverage themes — focus on the few that recur or hurt most, not an exhaustive list.
+5. Convert each theme into an action item with a clear owner, a concrete next step, and a check-back date.
+6. Write it up: a short summary, the keep/stop/start lists, and a table of action items (action, owner, due).
+
+## Rules
+- Keep it blameless — describe systems and decisions, not individuals' failures.
+- Every "went poorly" should map to at least one action item or an explicit "accept and move on".
+- Action items need an owner and a date; "the team should" with no owner is not an action item.
+- Ground claims in evidence (PRs, incidents, metrics) instead of vibes where you can.
+- Cap it: 3-5 action items the team will actually do beats 20 that get ignored.

package/skills/rtos-task/SKILL.md

@@ -0,0 +1,23 @@
+---
+name: rtos-task
+description: Create an RTOS task with the right stack, priority, and inter-task communication
+category: gamedev
+---
+
+# RTOS Task
+
+Use when adding a task/thread under an RTOS (FreeRTOS, Zephyr, ThreadX) and wiring it into the scheduler safely.
+
+1. Define the task function as an infinite loop that blocks on something (queue, semaphore, delay) — never a tight spin.
+2. Size the stack from worst-case call depth plus ISR/printf usage; start generous, then measure the high-water mark.
+3. Assign priority by deadline urgency, not importance; keep most tasks at the same level to avoid starvation.
+4. Use queues or message buffers for data hand-off and semaphores/notifications for signaling between tasks/ISRs.
+5. Block with `vTaskDelayUntil` (or equivalent) for periodic work so the period does not drift with execution time.
+6. From ISRs use only the `FromISR` APIs and yield if a higher-priority task was woken.
+
+## Rules
+- Never busy-wait in a task; block on a primitive so lower-priority tasks and idle/sleep can run.
+- Protect shared state with a mutex (with priority inheritance), not by disabling interrupts for long spans.
+- Keep ISRs short: defer work to a task via a queue or task notification, call only `FromISR` variants.
+- Validate stack high-water marks and enable stack-overflow checking during bring-up — overflow corrupts silently.
+- Beware priority inversion and unbounded blocking; prefer mutexes with inheritance over plain binary semaphores for locking.

package/skills/runbook/SKILL.md

@@ -0,0 +1,25 @@
+---
+name: runbook
+description: Write an operational runbook an on-call engineer can follow at 3am to detect, diagnose, and resolve an incident.
+category: docs
+---
+
+# Runbook
+
+Use when a recurring operational procedure (deploy rollback, failover, disk-full, cert rotation) needs to be executable by someone tired, paged, and unfamiliar with the system.
+
+1. State the trigger up front: the exact alert name, symptom, or condition that means "run this" — so on-call knows they're in the right doc.
+2. List prerequisites: required access/roles, tools, dashboards, and the blast radius / who to notify before acting.
+3. Add a fast diagnosis section — concrete commands and dashboard links to confirm the problem and rule out look-alikes.
+4. Write resolution as numbered, copy-pasteable steps with the *expected output* after each, so they can tell if it worked.
+5. Include a verification step ("service healthy when X") and a rollback/abort path if the fix makes things worse.
+6. End with escalation: who/what team to page, and how to capture state for the postmortem.
+7. Date the last test/review and note who owns it.
+
+## Rules
+- Every command must be copy-pasteable and parameterized with `<placeholders>`, never with real prod values inline.
+- Show expected output / success signal after risky steps — silence isn't confirmation.
+- Always give an abort/rollback path; a runbook with no exit is a trap.
+- Link the live dashboard/log query, don't paste a stale screenshot.
+- Test the runbook in a drill; an untested runbook is a guess. Mark it `UNTESTED` until then.
+- Keep it dumb-simple — assume zero context and high stress.

package/skills/rust-borrow/SKILL.md

@@ -0,0 +1,23 @@
+---
+name: rust-borrow
+description: Diagnose and fix Rust borrow-checker and lifetime errors without resorting to clone-everything
+category: languages
+---
+
+# Rust Borrow
+
+Use this when `cargo build` rejects code with E0499/E0502/E0515/E0597 or lifetime mismatches and you want a clean fix, not a clone band-aid.
+
+1. Read the error code and the borrow spans: the compiler points at where a value is borrowed, where it's used, and where the conflict happens — note the lifetimes involved.
+2. For "cannot borrow as mutable while borrowed as immutable", shorten the immutable borrow's scope (let it end before the mutation) or split into separate statements so NLL can release it.
+3. For "returns a value referencing data owned by the current function" (E0515), return an owned type (`String`, `Vec<T>`) or restructure so the caller owns the data.
+4. Resolve aliasing conflicts by splitting borrows: use `split_at_mut`, indices instead of references, or restructure into smaller functions that borrow disjoint fields.
+5. Add explicit lifetime parameters only when the compiler can't infer them; tie output lifetimes to the correct input, and prefer `'_` elision where it applies.
+6. When shared ownership is genuinely needed, reach for `Rc`/`Arc` (+ `RefCell`/`Mutex` for interior mutability) — deliberately, not reflexively.
+
+## Rules
+- `.clone()` to silence the borrow checker is a smell; use it only when the copy cost is acceptable and ownership truly must split — otherwise restructure.
+- Prefer narrowing scopes and splitting borrows over adding lifetime annotations; most errors are scope problems, not lifetime problems.
+- Don't reach for `unsafe` to bypass the checker — it converts a compile error into undefined behavior.
+- Avoid `Rc<RefCell<...>>` as a default; it moves borrow errors to runtime panics. Use it only when the ownership graph is genuinely shared.
+- Keep functions small — many borrow conflicts dissolve when you extract code so borrows don't overlap.

package/skills/rust-unsafe-audit/SKILL.md

@@ -0,0 +1,23 @@
+---
+name: rust-unsafe-audit
+description: Review Rust unsafe blocks for soundness and document the invariants they rely on
+category: languages
+---
+
+# Rust Unsafe Audit
+
+Use this when auditing `unsafe` code for undefined behavior — raw pointer derefs, FFI, transmutes, or hand-rolled data structures.
+
+1. Enumerate every `unsafe` block and the specific operation each performs (raw deref, `transmute`, `from_raw`, `get_unchecked`, FFI call) — group by the invariant each requires.
+2. For each block, write down the safety contract: what must be true (non-null, aligned, valid for the access, unique/aliasing rules, initialized, lifetime outlives use) and confirm a caller or surrounding code guarantees it.
+3. Add a `// SAFETY:` comment to every `unsafe` block stating why the invariants hold; if you can't write one, the code is suspect.
+4. Check the aliasing rules specifically: no two `&mut` to the same data, no `&` overlapping a `&mut`, and pointers derived correctly (no provenance violations).
+5. Run `cargo +nightly miri test` and `cargo test` under ASan/`-Zsanitizer` where possible to catch UB the compiler can't see; fuzz boundary inputs for FFI.
+6. Minimize the unsafe surface: shrink blocks to the exact unsafe operation, wrap them in a safe abstraction with checked preconditions, and prefer safe std APIs where they exist.
+
+## Rules
+- Every `unsafe` block needs a `// SAFETY:` comment naming the upheld invariant — no exceptions, including in tests.
+- `transmute` is the most dangerous tool here; prefer `as` casts, `from_le_bytes`, `bytemuck`, or explicit `union` access, and verify size/layout/`#[repr]`.
+- A safe public function wrapping unsafe internals must uphold the contract for all possible inputs — validate before the unsafe op, not after.
+- Miri-clean is not proof of soundness, but Miri-dirty is proof of a bug — never ship code Miri flags.
+- Don't widen lifetimes or fabricate `&mut` from `&` to dodge the borrow checker; that's instant UB even if it compiles.

package/skills/sanitize/SKILL.md

@@ -0,0 +1,23 @@
+---
+name: sanitize
+description: Fix injection, XSS, and path-traversal bugs by parameterizing, encoding, and confining paths
+category: security
+---
+
+# Sanitize
+
+Use this to remediate a concrete injection-class bug: SQL/command injection, XSS, or path traversal where untrusted input reaches a dangerous sink.
+
+1. Identify the sink and the injection class: query string, shell command, HTML/JS output, or filesystem path built from user input.
+2. SQL/NoSQL injection: replace string concatenation with parameterized queries / prepared statements or an ORM binding — never interpolate input into the query.
+3. Command injection: avoid the shell entirely — use an args array (`execFile`/`subprocess.run([...], shell=False)`); if a shell is unavoidable, allowlist and escape.
+4. XSS: encode output for its context (HTML body, attribute, JS, URL); render via the framework's auto-escaping; for rich HTML use a vetted sanitizer (DOMPurify) and a strict CSP.
+5. Path traversal: resolve the canonical path and assert it stays within an allowed base dir; reject `..`, absolute paths, and symlinks that escape; prefer an id-to-path map.
+6. Add a regression test that feeds the malicious payload and asserts it is now neutralized.
+
+## Rules
+- Fix at the sink with the right primitive (parameterize, encode, confine) — input filtering alone is bypassable.
+- Encode for the exact output context; HTML-escaping does not protect a JS or URL context.
+- Disable shell interpolation by default; pass arguments as a list, not a concatenated string.
+- Canonicalize paths before the boundary check, then verify the result is under the base directory.
+- Keep a regression test per payload so the hole cannot silently reopen.

package/skills/schema-design/SKILL.md

@@ -0,0 +1,23 @@
+---
+name: schema-design
+description: Design or normalize a database schema with sane keys, types, and relations
+category: database
+---
+
+# Schema Design
+
+Use when modeling a new feature's tables or untangling an existing schema that has grown redundant, ambiguous, or hard to query.
+
+1. List the entities and the real-world relationships between them (1:1, 1:many, many:many) before writing any DDL.
+2. Give every table a stable primary key; pick a surrogate key (auto-int or UUID) unless a natural key is truly immutable and unique.
+3. Choose the tightest correct type for each column (e.g. `timestamptz` not text dates, `numeric` not float for money, enums/check constraints for fixed sets).
+4. Normalize to 3NF first (no repeating groups, no transitive deps), then denormalize only where a measured read pattern demands it.
+5. Add foreign keys with explicit `ON DELETE` behavior, and `NOT NULL` / `UNIQUE` / `CHECK` constraints to encode invariants in the DB, not just the app.
+6. Resolve many:many with a join table; index the foreign-key columns you will filter or join on.
+
+## Rules
+- Let the database enforce integrity (FKs, constraints) — don't rely solely on application code.
+- Prefer `timestamptz` and store times in UTC; name booleans as `is_`/`has_` flags.
+- Avoid nullable columns that encode meaning; a separate table or status enum is usually clearer.
+- Don't over-index up front — add indexes to match actual query and constraint needs.
+- Use consistent naming (singular vs plural, snake_case) across the whole schema.

package/skills/screenshot-debug/SKILL.md

@@ -0,0 +1,22 @@
+---
+name: screenshot-debug
+description: Drive the app to the broken state, capture screenshots, and inspect a visual bug down to the offending element
+category: visual-test
+---
+
+# Screenshot Debug
+
+Reach for this when a UI looks wrong ("button overlaps text", "modal off-screen") and you need eyes on the actual render, not the code you imagine it produces.
+
+1. Reproduce the exact state: script the navigation (URL, clicks, form fills, viewport size) that leads to the bug so every capture is identical. Pin viewport and device-pixel-ratio.
+2. Capture full-page AND a tight element crop (`page.locator(sel).screenshot()`); the crop removes surrounding noise and shows sub-pixel issues.
+3. Dump the computed state next to the image: `getComputedStyle`, `getBoundingClientRect`, and the DOM subtree HTML — the screenshot shows *what*, these show *why*.
+4. Toggle one variable at a time (resize viewport, force `:hover`/`:focus`, disable a CSS rule via devtools protocol) and re-shoot to bisect the cause.
+5. Confirm the fix by re-running the same script and comparing the new screenshot to the broken one in the same dimensions.
+
+## Rules
+- Wait for the network/animations to settle before shooting (`waitForLoadState('networkidle')`, disable CSS transitions) or you capture a transient frame and chase a ghost.
+- Always record the viewport size, DPR, and theme (light/dark) in the filename; "looks fine for me" is usually a different viewport.
+- Screenshot the element, not just the page — a 1px misalignment is invisible at full-page scale.
+- Disable animations and freeze time/`Date.now` for deterministic frames before comparing shots.
+- Keep the repro script in the repo; a bug you can't re-capture on command isn't fixed, it's hidden.

package/skills/scroll-animation/SKILL.md

@@ -0,0 +1,23 @@
+---
+name: scroll-animation
+description: Build scroll-triggered and scroll-linked animations (GSAP/Framer Motion) that stay smooth and jank-free.
+category: ui-design
+---
+
+# Scroll Animation
+
+Reach for this when content should reveal, pin, or parallax as the user scrolls — done well it adds depth; done badly it stutters and hijacks the page.
+
+1. Decide trigger vs. scrub: reveal-on-enter (fire once when in view) vs. scroll-linked (progress tied to scroll position). Most sections want reveal; reserve scrubbing for hero/storytelling.
+2. For reveals, prefer the native `IntersectionObserver` (or Framer Motion `whileInView` with `viewport={{ once: true }}`) — cheap and battery-friendly. Add a `rootMargin` so it triggers slightly before the element hits the fold.
+3. For scrubbed/pinned sequences use GSAP ScrollTrigger with `scrub: true` (or a small smoothing number); animate only `transform`/`opacity` and let GSAP batch reads/writes.
+4. Build the parallax/depth illusion with differential `translateY` on layers via transform — never animate `background-position` or `top` during scroll.
+5. Stagger grouped reveals (40–80ms) and keep per-element distance small (16–40px rise) — large travel reads as laggy and forces reflow into view.
+6. Disable scroll effects (or make them instant) under `prefers-reduced-motion`, and lazy-init heavy ScrollTriggers below the fold so first paint stays fast.
+
+## Rules
+- Never block or rubber-band native scroll; smooth-scroll libraries (Lenis) are opt-in and must respect reduced-motion.
+- Keep work off the scroll thread: no layout-triggering properties, no `getBoundingClientRect` per frame in your own handlers — let IO/ScrollTrigger do it.
+- Content must be fully readable with JS disabled or before the observer fires — start visible, animate enhancement, never hide-until-scripted as the only path.
+- Test on a mid-tier phone at 60fps; if you see dropped frames, reduce simultaneous animated elements before tweaking easing.
+- `will-change: transform` only on elements actively animating, and remove it after — leaving it on bloats the compositor.

package/skills/secret-scan/SKILL.md

@@ -0,0 +1,23 @@
+---
+name: secret-scan
+description: Find secrets accidentally committed to the repo, in history and working tree, and remediate
+category: security
+---
+
+# Secret Scan
+
+Use this when you suspect (or want to rule out) API keys, tokens, passwords, or private keys committed to a repo.
+
+1. Scan the working tree and full history with a dedicated tool: `gitleaks detect --source . -v` or `trufflehog git file://.`; fall back to grep for high-signal patterns (`AKIA`, `-----BEGIN .* PRIVATE KEY-----`, `xox[baprs]-`, `ghp_`, `sk-`).
+2. Check `.env*`, config files, CI YAML, notebooks, and test fixtures — secrets hide outside source code.
+3. For each hit, decide if it is a true credential (live/format-valid) vs a placeholder/example, and confirm whether it is in current files, history, or both.
+4. For true secrets: rotate/revoke the credential first — assume it is compromised once committed.
+5. Remove it from current files, move it to env/secret manager, and add the path to `.gitignore`.
+6. If it must be purged from history, use `git filter-repo` (or BFG), force-push, and notify collaborators to re-clone.
+
+## Rules
+- Rotation comes before history rewriting — scrubbing git history does not un-leak a key that is already public.
+- Treat anything pushed to a remote or a forked/cloned repo as already exposed.
+- Add a pre-commit secret hook (gitleaks/`detect-secrets`) so this does not recur.
+- Do not print full secret values in logs or PRs; redact to a recognizable prefix.
+- Placeholder values (`changeme`, `xxxx`, `your-key-here`) are not findings — verify before alarming.

package/skills/security-audit/SKILL.md

@@ -0,0 +1,23 @@
+---
+name: security-audit
+description: Scan the codebase for common vulnerabilities and rank findings by exploitability
+category: security
+---
+
+# Security Audit
+
+Reach for this when you want a broad first-pass sweep of a repo for security bugs before a release, audit, or handoff.
+
+1. Map the attack surface: enumerate entry points (HTTP routes, CLI args, message consumers, file uploads, deserializers) and where untrusted data enters.
+2. Grep for dangerous sinks: `eval`, `exec`, `child_process`, raw SQL string concatenation, `dangerouslySetInnerHTML`, `pickle.loads`, `yaml.load`, `os.system`, template rendering with user input.
+3. Trace tainted data from each entry point to each sink; flag any path where user input reaches a sink without validation or parameterization.
+4. Check auth/session handling, secrets management, crypto usage (no MD5/SHA1 for passwords, no hardcoded keys/IVs), and CORS/CSRF config.
+5. Run available scanners (`semgrep --config auto`, `bandit`, `gosec`, `npm audit`) and merge their hits with your manual findings, deduping.
+6. Rank each finding by severity x exploitability, write a one-line repro/impact, and propose the minimal fix.
+
+## Rules
+- Confirm a real data flow before reporting; a dangerous function alone is not a vuln if input is trusted/constant.
+- Prefer parameterized queries, allowlists, and library escaping over hand-rolled sanitizers.
+- Never paste real secrets or live tokens into the report; redact to last 4 chars.
+- Separate "exploitable now" from "defense-in-depth" so the team fixes the bleeding first.
+- Cite file:line for every finding so it can be verified independently.

package/skills/security-review/SKILL.md

@@ -0,0 +1,23 @@
+---
+name: security-review
+description: Review the current diff for security vulnerabilities before it ships
+category: review
+---
+
+# Security Review
+
+Reach for this when a change touches auth, input handling, data access, secrets, or anything exposed to untrusted input, and you want a focused security pass before merging.
+
+1. Scope the diff with `git diff` (or `git diff main...HEAD`) and list which files cross a trust boundary (network, user input, file system, env, subprocess).
+2. Trace each untrusted input to its sink — look for injection (SQL/NoSQL/command/template), path traversal, SSRF, and unsafe deserialization.
+3. Check authz/authn on every new or changed endpoint, handler, or query: is the caller's identity verified and are they allowed to touch this resource?
+4. Grep the diff for hardcoded secrets, tokens, keys, and credentials; confirm none are logged or committed.
+5. Inspect crypto, randomness, and session handling — flag weak hashes, predictable tokens, missing TLS verification, and `eval`-style dynamic execution.
+6. For each finding, report file:line, the concrete attack, severity, and a minimal fix; verify the fix doesn't break the happy path.
+
+## Rules
+- Only flag issues reachable from untrusted input — don't pad the report with theoretical risks in trusted-only code paths.
+- Assume all external input is hostile, including headers, query params, filenames, and webhook payloads.
+- Never paste a discovered secret into output or logs; reference its location and recommend rotation.
+- Prefer parameterized queries, allowlists, and existing framework escaping over hand-rolled sanitization.
+- Rank findings by exploitability and blast radius, not by how many you found.

package/skills/seed-data/SKILL.md

@@ -0,0 +1,23 @@
+---
+name: seed-data
+description: Generate deterministic seed and fixture data for dev and test databases
+category: database
+---
+
+# Seed Data
+
+Use when you need realistic, repeatable data to populate a dev database or back a test suite, without hand-writing rows or depending on production dumps.
+
+1. Decide the scope: a small idempotent dev seed (a few records per table) vs. per-test fixtures (minimal data for one scenario).
+2. Insert in dependency order — parents before children — so foreign keys resolve; reuse the IDs you create downstream.
+3. Use a faker/factory library or fixed literals; seed any RNG so the data is deterministic and reproducible across runs.
+4. Make the seed idempotent: upsert or guard with "skip if already present" so re-running doesn't duplicate or crash.
+5. Cover the edge cases tests actually need (empty strings, nulls, boundary numbers, unicode), not just the happy path.
+6. Wire it to a single command (e.g. `npm run seed`, `make seed`, a migration's data step) and document how to reset.
+
+## Rules
+- Never point seed scripts at production or use real customer data; keep PII synthetic.
+- Keep seeds idempotent — running twice must leave the same state.
+- Isolate test fixtures per test (transaction rollback or truncate-between) so tests don't bleed state.
+- Seed the smallest dataset that exercises the case; large seeds slow the suite for no gain.
+- Keep seed data in version control and update it when the schema changes.