ada-agent 0.1.0

package/skills/adr/SKILL.md

@@ -0,0 +1,24 @@
+---
+name: adr
+description: Write an Architecture Decision Record capturing context, the decision, and consequences
+category: docs
+---
+
+# Adr
+
+Use this to record a significant, hard-to-reverse technical decision so the reasoning survives past the people who made it. One ADR per decision, immutable once accepted.
+
+1. Find or create `docs/adr/` (or `doc/decisions/`); number the new file sequentially, e.g. `0007-use-postgres.md`.
+2. Write a short noun-phrase title describing the decision.
+3. Set Status: Proposed, then Accepted (or later Deprecated/Superseded by ADR-NNNN).
+4. Context: the forces, constraints, and problem driving the decision — neutral, no conclusion yet.
+5. Decision: state what you're doing in active voice ("We will use ...").
+6. Consequences: the resulting trade-offs, both positive and negative, including what becomes harder.
+7. List the alternatives considered and why each was rejected.
+
+## Rules
+- One decision per record; keep it to a page.
+- ADRs are immutable — to change course, write a new ADR that supersedes the old one, don't edit it.
+- Capture the why and the rejected options; that context is the whole point.
+- Be honest about downsides in Consequences — every real decision has them.
+- Keep filenames numbered and titles stable so cross-references hold.

package/skills/aesthetic-direction/SKILL.md

@@ -0,0 +1,24 @@
+---
+name: aesthetic-direction
+description: Choose an intentional, non-templated visual direction and reference before building any UI
+category: ui-design
+---
+
+# Aesthetic Direction
+
+Do this before writing component code. The difference between a forgettable, templated UI and a memorable one is a deliberate point of view chosen up front — not defaults stacked by accident.
+
+1. Name the feeling in 2–3 adjectives and a reference: "editorial and confident, like Linear meets a print magazine" or "warm utilitarian, like a well-made tool." Vague intent yields vague output.
+2. Pick a stance on each axis deliberately: density (airy vs. compact), shape language (sharp vs. rounded), contrast (muted vs. punchy), and ornament (flat vs. layered/textured). Write the choices down.
+3. Choose ONE signature move the design hangs on — a distinctive typeface, a bold accent, a grain/noise texture, an unusual grid, a motion personality. Without a signature, it reads generic.
+4. Anchor with real references: pull 3–5 screenshots you admire and articulate *what specifically* works (the oversized headers, the restrained palette, the tight grid) — then translate, don't copy.
+5. Pressure-test against templates: if it could be any Bootstrap/default-shadcn site, push harder — change the type, break the symmetry, commit to one strong color, vary the rhythm.
+6. Encode the direction into tokens immediately so the rest of the build inherits the decision instead of re-litigating it per component.
+7. Sanity-check feasibility and accessibility — a daring direction still has to pass contrast and perform.
+
+## Rules
+- Decide the direction before components; retrofitting taste onto built UI rarely works.
+- Commit to one signature element rather than three half-measures.
+- "Modern/clean/minimal" is not a direction — name a feeling, a reference, and a specific move.
+- Default shadcn/Bootstrap/Tailwind-gray is a starting point to subvert, not a destination.
+- Distinctive still means accessible and fast — daring is not an excuse for 2:1 contrast.

package/skills/agent-loop/SKILL.md

@@ -0,0 +1,23 @@
+---
+name: agent-loop
+description: Build a minimal agent loop that streams, calls tools, and repeats until done
+category: agent-llm
+---
+
+# Agent Loop
+
+Reach for this to implement the core "model decides, tools run, repeat" cycle that turns a chat completion into an agent.
+
+1. Seed a message list with a system prompt (role, tools available, stop conditions) and the user's request.
+2. Call the model with the messages and the tool schemas; stream tokens to the user as they arrive.
+3. If the response contains tool calls, append the assistant turn, execute each tool, and append a tool-result message per call.
+4. Loop back to step 2 with the appended results; if the response has no tool calls, it's the final answer — stop.
+5. Cap iterations (e.g. max 10) and total tokens to prevent runaway loops; surface a clear message when a cap is hit.
+6. Handle errors per tool — return the error text as the tool result so the model can retry or change approach, rather than crashing the loop.
+
+## Rules
+- Always append the assistant's tool-call turn BEFORE the tool results, in the order the API expects, or the next call rejects the history.
+- Execute independent tool calls concurrently, but preserve result ordering when appending them back.
+- Enforce a hard iteration cap and a wall-clock/token budget; an agent with no brake will spin.
+- Make tool execution idempotent or guard destructive actions, since the model may retry after a transient error.
+- Stream text deltas but buffer tool-call arguments until complete — partial JSON is not parseable.

package/skills/alerting/SKILL.md

@@ -0,0 +1,23 @@
+---
+name: alerting
+description: Define actionable alerts and SLOs that page on symptoms, not noisy causes
+category: observability
+---
+
+# Alerting
+
+Use this to turn metrics into alerts that wake someone only when users are actually affected — and to back them with SLOs.
+
+1. Define the SLO first: pick a user-facing SLI (availability or latency), a target (e.g. 99.9% over 30 days), and compute the error budget.
+2. Alert on symptoms (elevated error rate, p99 latency, budget burn) rather than causes (high CPU) — page on what users feel.
+3. Use multi-window burn-rate alerts: a fast window (e.g. 5m) and a slow window (e.g. 1h) both breaching, so you page on sustained burn, not single spikes.
+4. Set `for:` durations to require the condition to persist, suppressing flaps; add `severity` labels routing critical→page, warning→ticket.
+5. Write a runbook link and a clear, templated summary into each alert annotation so the on-call knows what broke and what to do.
+6. Test by injecting a failure or backfilling data, confirm the alert fires, routes, and resolves; tune thresholds against historical data to bound false positives.
+
+## Rules
+- Every alert must be actionable — if there's no human response, make it a dashboard, not a page.
+- Page on customer impact; ticket or silence everything else.
+- Tie thresholds to the error budget, not arbitrary round numbers.
+- Always include a runbook URL and the affected service/component in annotations.
+- Add an "absent data" alert so a dead exporter doesn't silently hide outages.

package/skills/alpha-compositing/SKILL.md

@@ -0,0 +1,23 @@
+---
+name: alpha-compositing
+description: Fix alpha blending, transparency, and premultiplied-alpha bugs — dark/white halos, wrong order, additive glow
+category: graphics
+---
+
+# Alpha Compositing
+
+Reach for this when transparent images show dark or white fringes, edges glow, layers stack wrong, or "transparent" pixels aren't.
+
+1. Reproduce on a stark background: composite the asset over pure red AND pure white. Dark halos on light backgrounds (or bright fringes on dark) are the classic premultiplied-vs-straight-alpha mismatch.
+2. Decide one alpha convention end-to-end. If the source is premultiplied, the blend func must be `ONE, ONE_MINUS_SRC_ALPHA`; if straight, `SRC_ALPHA, ONE_MINUS_SRC_ALPHA`. Mixing the upload flag and the blend func is the #1 cause of halos.
+3. Check the upload/decode flag: in WebGL toggle `UNPACK_PREMULTIPLY_ALPHA_WEBGL`; in canvas/CSS the browser premultiplies. Verify whether your PNG was authored premultiplied and align the flag to it.
+4. For correct blending of semi-transparent geometry, draw back-to-front and disable depth writes (keep depth test) for the transparent pass — out-of-order alpha produces hard wrong edges where far fragments overwrite near ones.
+5. For unexpected additive "glow", confirm you didn't leave an additive blend (`ONE, ONE`) set from a particle/bloom pass; blend state is sticky across draws.
+6. Confirm the texture even has an alpha channel and an internal format that keeps it (`RGBA`, not `RGB`); a dropped alpha makes everything opaque.
+
+## Rules
+- Pick premultiplied OR straight alpha and keep the upload flag and blend function consistent — never mix.
+- Dark fringes on light bg = treating premultiplied data as straight (or vice versa); test on red+white to confirm.
+- Transparent geometry: sort back-to-front, depth-test on, depth-write OFF.
+- Blend mode is global state; reset it after additive/special passes or it leaks.
+- "Transparent" needs an actual alpha channel AND a blend enabled — `RGB` format or `disable(BLEND)` makes alpha a no-op.

package/skills/android-compose/SKILL.md

@@ -0,0 +1,23 @@
+---
+name: android-compose
+description: Build a Jetpack Compose screen with hoisted state and a ViewModel
+category: mobile
+---
+
+# Android Compose
+
+Use this when building a screen in Jetpack Compose, separating stateless composables from the state held in a `ViewModel` and exposed as `StateFlow`.
+
+1. Write the screen as a `@Composable` function in PascalCase that takes its state and event lambdas as parameters (state hoisting), keeping it stateless and previewable.
+2. Hold real state in a `ViewModel` exposed via `StateFlow`/`MutableStateFlow`, and collect it with `collectAsStateWithLifecycle()`.
+3. For purely local UI state (expanded, text input) use `remember { mutableStateOf(...) }`, and `rememberSaveable` for state that must survive config changes.
+4. Provide a route composable that pulls the `ViewModel` (`viewModel()` / Hilt) and passes state + callbacks down into the stateless screen.
+5. Use `Modifier` for layout/styling, scaffold structure with `Scaffold`/`Column`/`LazyColumn`, and pull colors from `MaterialTheme`.
+6. Add an `@Preview` composable with sample state, then verify recomposition and clicks with a Compose UI test (`createComposeRule`, `onNodeWithText`).
+
+## Rules
+- Hoist state up and keep leaf composables stateless so they're easy to preview and test.
+- Never read or mutate `mutableStateOf` outside composition without `remember` — it resets every recomposition.
+- Keep composables side-effect free; launch coroutines via `LaunchedEffect`/`rememberCoroutineScope`, not inline in the body.
+- Pass stable types and lambdas to avoid needless recomposition; use `key` in lazy lists.
+- Don't hold Android `Context`/`Activity` references in a `ViewModel`; survive rotation via the ViewModel, not the composable.

package/skills/angular-module/SKILL.md

@@ -0,0 +1,23 @@
+---
+name: angular-module
+description: Scaffold an Angular feature module (or standalone feature) with lazy routing
+category: frameworks
+---
+
+# Angular Module
+
+Use to add a self-contained feature to an Angular app — a feature module (or standalone components) with its own components, routing, and services.
+
+1. Generate the scaffold: `ng generate module features/<name> --routing` (or skip the module and use `--standalone` components on modern Angular).
+2. Add components/services with `ng generate component features/<name>/<comp>` and `ng generate service features/<name>/<svc>`.
+3. Define the feature's routes in its routing module/`routes` array, with a default child route and any guards/resolvers.
+4. Wire lazy loading from the root router: `loadChildren: () => import('./features/<name>/<name>.module').then(m => m.<Name>Module)` (or `loadComponent` for standalone).
+5. Provide feature-scoped services in the module `providers` (or `providedIn` a route) so they aren't global unless intended.
+6. Run `ng serve`, navigate to the route, and confirm the chunk loads lazily and the feature renders.
+
+## Rules
+- Declare each component in exactly one NgModule; for standalone components, list deps in `imports` instead.
+- Export only the components other modules actually use; keep internals private.
+- Import `CommonModule` (not `BrowserModule`) in feature modules for `*ngIf`/`*ngFor`.
+- Prefer lazy-loaded routes for features to keep the initial bundle small.
+- Follow the generated file/selector naming and folder structure; don't hand-roll boilerplate the CLI produces.

package/skills/ansible-playbook/SKILL.md

@@ -0,0 +1,24 @@
+---
+name: ansible-playbook
+description: Write an idempotent Ansible playbook with roles, variables, and handlers
+category: cloud
+---
+
+# Ansible Playbook
+
+Use this to automate configuration of one or more hosts — installing packages, templating configs, managing services — in a repeatable, idempotent way.
+
+1. Define the inventory (hosts/groups) and confirm connectivity with `ansible all -m ping`.
+2. Structure logic into roles (`roles/<name>/{tasks,handlers,templates,defaults}`) rather than one monolithic play.
+3. Write tasks using purpose-built modules (`apt`, `copy`, `template`, `service`) — not `command`/`shell` unless unavoidable.
+4. Put tunables in `defaults/main.tf` (lowest precedence) and environment specifics in group/host vars; reference with `{{ }}`.
+5. Use `notify` + `handlers` to restart services only when a config actually changes.
+6. Dry-run with `ansible-playbook --check --diff`, then apply for real.
+7. Lint with `ansible-lint` and keep tasks `--check`-clean so re-runs report no changes.
+
+## Rules
+- Every task must be idempotent — re-running the playbook should report `changed=0` once converged.
+- Encrypt secrets with `ansible-vault`; never commit plaintext credentials to vars files.
+- Prefer modules over `shell`; when you must use `shell`, add `creates`/`removes` or a `when`/`changed_when` guard.
+- Name every task descriptively so output and failures are readable.
+- Use `become` only on tasks that need privilege escalation, not blanket at play level when avoidable.

package/skills/api-docs/SKILL.md

@@ -0,0 +1,24 @@
+---
+name: api-docs
+description: Generate API reference docs from the code, grouped by module with signatures and examples
+category: docs
+---
+
+# Api Docs
+
+Reach for this to produce a reference that lists every public endpoint, function, or class with its signature and contract. Distinct from a tutorial: this is exhaustive lookup material, not a guided walkthrough.
+
+1. Decide the API surface: HTTP routes, exported library symbols, or CLI commands — and where docs should live (`docs/`, `/reference`).
+2. Prefer a generator that reads the source of truth: OpenAPI/Swagger from route defs, TypeDoc/Sphinx/rustdoc/godoc from doc-comments.
+3. If generating, ensure source comments/annotations are complete first, then run the generator and commit its config.
+4. If writing by hand, group by module/resource; for each entry give signature, params, return/response, errors, and status codes.
+5. Add at least one request/response or call example per entry, with realistic values.
+6. Cross-link related entries and note auth, versioning, and deprecations.
+7. Build the docs and verify examples against the running code or test suite.
+
+## Rules
+- Derive from the code so docs can't silently drift; wire generation into CI if it exists.
+- Every entry needs an example — a signature alone isn't reference documentation.
+- Document error responses and edge cases, not just the happy path.
+- Mark deprecated and unstable APIs explicitly with the version they changed.
+- Keep ordering stable (alphabetical or by resource) so diffs stay readable.

package/skills/app-store-prep/SKILL.md

@@ -0,0 +1,23 @@
+---
+name: app-store-prep
+description: Prepare a store listing and run the release-build checklist before submission
+category: mobile
+---
+
+# App Store Prep
+
+Use this when readying a mobile app for App Store / Google Play submission: building the signed release artifact and assembling the metadata a reviewer needs.
+
+1. Bump the version: set a human-facing version name and increment the build/version code (each upload must be unique and monotonically increasing).
+2. Produce a signed release build — iOS archive (`.ipa`) with the correct distribution profile, Android `.aab` signed with the upload key — using release config, not debug.
+3. Strip debug artifacts: remove logging, test endpoints, and unused permissions; confirm release flags (minify/shrink, no debuggable) and crash reporting are on.
+4. Assemble store assets: icon, screenshots per required device size, a privacy policy URL, and the data-collection / privacy questionnaire (App Privacy / Data safety).
+5. Write the listing: title, subtitle, description, keywords, category, age rating, and accurate "what's new" notes.
+6. Run a final pre-submit pass on a real device from the release artifact, then upload, fill review notes (and demo credentials if login is required), and submit.
+
+## Rules
+- Keep signing keys/keystores backed up and out of version control; losing the Android upload key blocks future updates.
+- Every store upload needs a higher build number than the last — reusing one is rejected.
+- Match declared permissions and privacy answers to actual behavior; mismatches are the top rejection cause.
+- Provide working demo/login credentials in review notes for any gated feature, or review will fail.
+- Test the release (not debug) build on a physical device — debug-only crashes and ProGuard/R8 stripping surface here.

package/skills/architecture-diagram/SKILL.md

@@ -0,0 +1,21 @@
+---
+name: architecture-diagram
+description: Map a project's components and data flow into a clean architecture diagram (Mermaid or SVG).
+category: docs
+---
+
+# Architecture Diagram
+
+Use to show how a system fits together — components, boundaries, and how data/control flows between them.
+
+1. Discover the pieces: entry points, modules/services, data stores, external dependencies (read the README, the manifest, and the top-level directories).
+2. Trace the main flow: how a request/task moves through the system (client → service → store → external), and which parts own state vs. are stateless.
+3. Lay it out in tiers (left→right or top→down): ≤ ~4 boxes per tier, group related pieces in subgraphs, draw arrows for the *real* call/data direction (and a return path only if it matters).
+4. Render it: a fenced ` ```mermaid ` flowchart for a committed, editable diagram, or a hand-authored SVG for a polished on-brand one. Save to `docs/architecture.{md,svg}` and embed it in the README.
+5. Add a one-line caption of the key design idea (e.g. "one adapter per wire format").
+
+## Rules
+- Diagram the system as it IS in the code, not an idealized version.
+- Components and boundaries, not every file — keep it at the level a newcomer needs.
+- Label arrows with what flows (requests, events, SSE) and mark external/3rd-party pieces distinctly.
+- Keep the source (Mermaid/SVG) in the repo so the picture stays in sync with the code.

package/skills/architecture-doc/SKILL.md

@@ -0,0 +1,24 @@
+---
+name: architecture-doc
+description: Write a concise architecture overview of components, data flow, and key decisions
+category: docs
+---
+
+# Architecture Doc
+
+Use this when a new contributor (or future you) needs the mental model of how the system fits together, without reading every file. Aim for a short ARCHITECTURE.md, not a spec.
+
+1. Map the major components/modules and what each is responsible for — read entry points and directory layout first.
+2. Trace the primary data/request flow end to end (input → processing → storage → output).
+3. Draw one diagram (ASCII or Mermaid) showing components and the arrows between them.
+4. Document the key technical decisions and constraints (datastore choice, sync vs async, boundaries) and the why.
+5. Note external dependencies and integration points (APIs, queues, third-party services).
+6. Add a "where things live" map so readers can jump from a concept to the directory/file.
+7. Keep it to a couple of screens; link to deeper docs/ADRs instead of expanding inline.
+
+## Rules
+- Explain the why behind structure, not just the what — that's the part code can't show.
+- One clear diagram beats three; prefer Mermaid so it renders in-repo.
+- Describe boundaries and data flow, not implementation line-by-line.
+- Call out the non-obvious: surprising couplings, intentional duplication, hot paths.
+- Date it lightly and link related ADRs so it stays anchored as the system evolves.

package/skills/audit-log/SKILL.md

@@ -0,0 +1,23 @@
+---
+name: audit-log
+description: Add a tamper-evident audit log of security-relevant actions with who/what/when
+category: observability
+---
+
+# Audit Log
+
+Reach for this when you must record who did what to which resource and when — for compliance, security forensics, or accountability.
+
+1. Define the events worth auditing: authentication, authorization changes, data access/exports, config and permission changes, and admin actions.
+2. Design a stable record schema: `actor` (id + type), `action`, `resource` (type + id), `timestamp` (UTC), `source_ip`, `outcome`, and a `correlation_id`.
+3. Write audit records to a separate, append-only store (dedicated table/stream), never the same mutable rows the app edits, and never only to app logs.
+4. Make it tamper-evident: hash-chain each entry (`hash = H(prev_hash + entry)`) or use a WORM/immutable backend so silent edits are detectable.
+5. Emit the record in the same transaction as the action where possible so an action can't succeed without its audit trail.
+6. Restrict write/read access, set a retention policy matching your compliance regime, and add a verification job that walks the hash chain to detect breaks.
+
+## Rules
+- Audit logs are append-only — no updates or deletes outside the retention policy.
+- Record the outcome (success/denied/error), not just attempts; failed-access events are the point.
+- Don't store raw secrets or full sensitive payloads — log identifiers and the fact of access.
+- Use a trusted server-side clock in UTC; never trust client-supplied timestamps.
+- Separate audit storage and permissions from application data so an app compromise can't rewrite history.

package/skills/authz-review/SKILL.md

@@ -0,0 +1,23 @@
+---
+name: authz-review
+description: Review authentication and authorization logic for missing or broken access checks
+category: security
+---
+
+# Authz Review
+
+Use this to audit who-can-do-what: missing access checks, broken object-level authorization (IDOR), and privilege escalation paths.
+
+1. List every protected resource and action, then map which endpoint/handler serves each and what check it performs.
+2. Verify each handler enforces BOTH authentication (who you are) and authorization (what you may touch) — and that authorization is object-level, not just "is logged in".
+3. Hunt for IDOR: any handler that reads an id from the request and fetches the record without scoping to the current user/tenant.
+4. Check role/permission logic for default-allow, missing server-side enforcement (client-only gating), and admin routes lacking checks.
+5. Inspect token/session handling: expiry, revocation, signature verification, and that role/tenant claims are server-validated, not trusted from the client.
+6. Write a test (or curl repro) proving an unauthorized actor is now blocked for each gap found.
+
+## Rules
+- Default deny: access must be explicitly granted, never implicitly assumed.
+- Enforce authorization on the server for every request — UI hiding is not a control.
+- Scope every record lookup by owner/tenant; never trust an id alone from the client.
+- Re-check authorization on every step of multi-step flows, not just the first.
+- Confirm fixes with a negative test (the forbidden action returns 403/404), not just a happy-path test.

package/skills/aws-lambda/SKILL.md

@@ -0,0 +1,24 @@
+---
+name: aws-lambda
+description: Scaffold an AWS Lambda with a least-privilege IAM role and a clean handler
+category: cloud
+---
+
+# AWS Lambda
+
+Use this to create a deployable Lambda function — handler code, an execution role scoped to exactly what it touches, and the wiring (env, timeout, trigger).
+
+1. Write the handler with the runtime's expected signature (`handler(event, context)`), keeping the entry thin and the logic in testable functions.
+2. Initialize clients and read config (env vars) at module scope so they're reused across warm invocations.
+3. Define an IAM execution role granting only the actions/resources this function needs, plus `AWSLambdaBasicExecutionRole` for logs.
+4. Declare the function in IaC (Terraform/SAM/CDK): runtime, `handler`, `memory_size`, `timeout`, env vars, and the role ARN.
+5. Wire the trigger (API Gateway, EventBridge, SQS, S3) and grant the source permission to invoke.
+6. Test locally (`sam local invoke` or a unit test passing a sample event) before deploying.
+7. Add structured logging and set a `CloudWatch` log retention so logs don't accumulate forever.
+
+## Rules
+- Scope IAM to specific resource ARNs and actions — never attach `*` or broad managed policies like `AdministratorAccess`.
+- Pull secrets from Secrets Manager/SSM at runtime, not from plaintext env vars.
+- Set a realistic `timeout` and `memory_size`; the default 3s timeout silently fails many functions.
+- Make handlers idempotent — retries (SQS, async) will re-deliver events.
+- Don't store state in `/tmp` expecting persistence; treat every invocation as potentially cold.

package/skills/bash-script/SKILL.md

@@ -0,0 +1,23 @@
+---
+name: bash-script
+description: Write a robust, safe bash script with strict mode, quoting, traps, and clear failure handling
+category: shell
+---
+
+# Bash Script
+
+Use this when authoring a bash script that must run reliably and fail loudly — automation, glue, CI steps, or setup scripts.
+
+1. Start with `#!/usr/bin/env bash` and `set -euo pipefail` so unset vars, failed commands, and broken pipes abort the run.
+2. Set `IFS=$'\n\t'` if you iterate over lines/paths, and quote every expansion (`"$var"`, `"${arr[@]}"`) to survive spaces and globs.
+3. Wrap logic in functions with a `main "$@"` entrypoint at the bottom; keep top-level code to argument parsing and the `main` call.
+4. Add `trap 'cleanup' EXIT` (and `ERR` if useful) to remove temp files made with `mktemp`, even on early exit.
+5. Validate prerequisites up front: required args, `command -v tool` for each dependency, and writable paths — exit with a message before doing work.
+6. Run `shellcheck` on the script and fix every warning before considering it done.
+
+## Rules
+- Never `cd` without checking it succeeded; prefer `cd "$dir" || exit 1` or compute absolute paths instead.
+- Avoid parsing `ls` output; use globs or `find ... -print0` with `read -d ''` for filenames.
+- Send errors and progress to stderr (`>&2`); keep stdout for the script's actual output.
+- Use `[[ ]]` over `[ ]` for tests, and `$(...)` over backticks for command substitution.
+- For anything with nested data structures, arrays of structs, or heavy text processing, stop and switch to Python — bash is the wrong tool past ~100 lines.

package/skills/batch/SKILL.md

@@ -0,0 +1,23 @@
+---
+name: batch
+description: Batch requests/operations to cut per-call overhead and round-trips
+category: performance
+---
+
+# Batch
+
+Reach for this when many small, similar operations each pay fixed overhead — network round-trips, DB statements, or API calls in a loop.
+
+1. Find the chatty loop: per-item HTTP calls, single-row inserts, or one API request per element when a bulk form exists.
+2. Group items into batches and use the bulk primitive — `INSERT ... VALUES (many)`, `WHERE id IN (...)`, bulk/multi endpoints, or a pipeline.
+3. Choose a batch size that balances throughput against memory and payload limits; chunk large sets rather than one giant call.
+4. Optionally add a short time-window or size-trigger buffer (debounce/flush) to accumulate items before sending.
+5. Handle partial failure: know whether the batch is atomic or per-item, and retry or report the failed subset without redoing successes.
+6. Measure round-trips and total time before/after to confirm the overhead reduction is real.
+
+## Rules
+- Batch the overhead, not the work — the win comes from fewer round-trips, not less computation.
+- Cap batch size; an unbounded batch hits payload limits, timeouts, or memory blowups.
+- Respect ordering and idempotency — retries on a partially-applied batch must not double-apply.
+- Don't add buffering/debounce latency to operations that need to be immediate.
+- Preserve per-item error reporting so one bad item doesn't silently sink the whole batch.

package/skills/bisect/SKILL.md

@@ -0,0 +1,23 @@
+---
+name: bisect
+description: Use git bisect to pinpoint the commit that introduced a regression
+category: git
+---
+
+# Bisect
+
+Reach for this when something worked before and is broken now, but you don't know which commit broke it. `git bisect` binary-searches history so you test ~log2(N) commits instead of all of them.
+
+1. Reproduce the bug reliably and define a clear pass/fail test — ideally a single command that exits 0 when good, non-zero when bad.
+2. Start the search: `git bisect start`, then mark the current broken state `git bisect bad`, and a known-good commit/tag `git bisect good <sha-or-tag>`.
+3. At each step git checks out a midpoint commit; run your test and answer `git bisect good` or `git bisect bad` (use `git bisect skip` if a commit can't be tested, e.g. won't build).
+4. Repeat until git prints "`<sha> is the first bad commit`" and shows that commit's details.
+5. Inspect the culprit with `git show <sha>` to understand the regression, then `git bisect reset` to return to your original HEAD.
+6. To fully automate, write a script that exits 0/non-zero and run `git bisect run ./test.sh` — git drives the whole search unattended.
+
+## Rules
+- The good/bad answers must be reliable; a flaky test will send bisect to the wrong commit.
+- For `git bisect run`, your script must exit 125 for "skip/untestable", 0 for good, 1–124 for bad — not just any non-zero.
+- Pick a `good` commit you're confident actually predates the bug, or the search range is wrong from the start.
+- Always finish with `git bisect reset` to restore HEAD and clean up bisect state.
+- If the breakage is environmental (deps, data) rather than in code, bisect will mislead you — confirm it's a code regression first.

package/skills/bounding-box/SKILL.md

@@ -0,0 +1,24 @@
+---
+name: bounding-box
+description: Debug bounding-box bugs — xyxy vs xywh, normalized vs pixel, scaling after resize, axis order
+category: image
+---
+
+# Bounding Box
+
+Reach for this when detection/annotation boxes draw in the wrong place, are shifted/scaled, or are off-screen tiny/huge.
+
+1. Reproduce by drawing the boxes on the source image and saving it — visual overlay instantly shows whether boxes are shifted, scaled, swapped, or in the wrong coordinate frame.
+2. Identify the format: `xyxy` (x1,y1,x2,y2) vs `xywh` (x,y,w,h) vs center-based `cxcywh` (YOLO). Feeding one where another is expected produces boxes that are offset or sized wrong in a consistent way.
+3. Check normalized vs pixel coordinates: values in `0–1` mean normalized (multiply by width/height); values up to image size are pixels. A box at the top-left corner with tiny dimensions usually means normalized coords drawn as pixels.
+4. Account for resize/letterbox: if the image was resized or padded before inference, boxes are in the model's input space and must be scaled back (and un-padded) to original-image coordinates.
+5. Verify axis order: `(x, y)` vs `(row, col)`/`(y, x)` swaps width and height. A box that looks transposed or lands at a mirrored position is an axis swap.
+6. Clamp and sanity-check: ensure `x2 > x1`, `y2 > y1`, and coords within image bounds; negative or out-of-range values point to a sign or scaling error.
+7. Confirm with one hand-labeled box whose correct pixel coordinates you know, end to end.
+
+## Rules
+- State the format explicitly (xyxy / xywh / cxcywh) at every interface; conversions are where boxes break.
+- Normalized boxes need image w/h to render; mixing 0–1 and pixel values is the most common error.
+- After any resize/pad/letterbox, transform boxes back to original coordinates — scale AND offset.
+- `(x, y)` ordering for boxes vs `(row, col)` numpy indexing swaps W/H; pin it down.
+- Always validate by overlaying on the actual image, not by reading numbers alone.

package/skills/branch-cleanup/SKILL.md

@@ -0,0 +1,23 @@
+---
+name: branch-cleanup
+description: Prune merged and stale local and remote branches safely
+category: git
+---
+
+# Branch Cleanup
+
+Use this to clear out branches that have already merged or gone stale, keeping the branch list readable without deleting unmerged work.
+
+1. Sync references first: `git fetch --prune` to update remotes and drop refs for branches deleted on the remote.
+2. List merged branches: `git branch --merged main` shows locals fully merged into main (safe to delete); review the list before acting.
+3. Delete merged locals: `git branch -d <name>` (the lowercase `-d` refuses to delete unmerged branches, which is the safety you want).
+4. Find stale branches: `git branch -vv` flags ones whose upstream is `[gone]`, and `git for-each-ref --sort=committerdate refs/heads --format='%(committerdate:short) %(refname:short)'` surfaces the oldest.
+5. Clean remotes deliberately: `git push origin --delete <name>` for branches you own and confirm are merged; don't delete others' active branches.
+6. Re-check `git branch --merged` and `git branch` to confirm only intended branches remain.
+
+## Rules
+- Use `git branch -d` (safe) not `-D` (force) unless you've verified the branch is truly disposable — `-D` discards unmerged commits.
+- Exclude protected branches (`main`, `develop`, release/*) from any bulk delete; filter them out explicitly.
+- `git fetch --prune` only cleans remote-tracking refs, not local branches — do both steps.
+- Confirm a remote branch is merged and unowned by an active developer before `--delete`.
+- Recover an accidentally-deleted branch via `git reflog` / `git checkout -b <name> <sha>` while the object is still reachable.

package/skills/bundle-analyze/SKILL.md

@@ -0,0 +1,23 @@
+---
+name: bundle-analyze
+description: Analyze the production bundle to find the heaviest modules and shrink the shipped size
+category: dependencies
+---
+
+# Bundle Analyze
+
+Use when the shipped bundle is too large and you need to know what is taking up space before cutting it.
+
+1. Produce a production build with stats enabled and open a treemap (`webpack-bundle-analyzer`, `vite-bundle-visualizer`, `source-map-explorer`, `rollup-plugin-visualizer`).
+2. Rank modules by gzipped size and flag the worst offenders — large libs, duplicated packages, and accidentally-bundled dev/test code.
+3. Replace heavy dependencies with lighter or native equivalents (e.g. date helpers, lodash → per-method or stdlib).
+4. Split routes and lazy-load rarely-used chunks; defer anything not needed for first paint.
+5. Ensure tree-shaking works: prefer ESM imports, drop side-effect-y barrel files, and set `sideEffects` correctly.
+6. Rebuild, compare gzipped sizes against the baseline, and record the before/after numbers.
+
+## Rules
+- Measure gzipped (or brotli) size, not raw bytes — that's what users actually download.
+- Always analyze a production build; dev builds include unminified helpers and skew the picture.
+- Confirm a smaller alternative is genuinely lighter after tree-shaking, not just on paper.
+- Duplicated versions of one library are a common, easy win — dedupe before swapping libs.
+- Re-run the analyzer after each change so you attribute the savings correctly.

package/skills/cache/SKILL.md

@@ -0,0 +1,23 @@
+---
+name: cache
+description: Add caching (memoize/LRU/HTTP) where it pays off, with correct keys and invalidation
+category: performance
+---
+
+# Cache
+
+Reach for this when the same expensive computation or fetch repeats with identical inputs and recomputing is the bottleneck.
+
+1. Confirm the work is cacheable: deterministic for a given key, read-heavy, and expensive enough that caching beats the lookup overhead.
+2. Define the cache key precisely — include every input that changes the result; exclude volatile or irrelevant fields.
+3. Pick the layer: memoize a pure function, an in-process LRU with a size cap, a shared store (Redis), or HTTP `Cache-Control`/`ETag` for responses.
+4. Set bounds: max entries or memory cap plus a TTL, so the cache can't grow unbounded or serve stale data forever.
+5. Define invalidation up front — TTL expiry, write-through on update, or explicit bust on the events that change the source.
+6. Measure hit rate and latency before/after; if the hit rate is low or correctness gets fragile, remove it.
+
+## Rules
+- An unbounded cache is a memory leak — always cap size and/or TTL.
+- A wrong key is worse than no cache: too broad serves stale results, too narrow never hits.
+- Don't cache cheap, fast, or rarely-repeated work — the bookkeeping costs more than it saves.
+- Cache invalidation is the hard part; prefer TTL or write-through over hand-rolled bust logic.
+- Never cache per-user or sensitive data in a shared/global cache without scoping the key to the user.

package/skills/call-graph/SKILL.md

@@ -0,0 +1,23 @@
+---
+name: call-graph
+description: Map the callers and dependencies of a symbol to understand blast radius before changing it
+category: code-understanding
+---
+
+# Call Graph
+
+Use before modifying or removing a function, method, or type when you need to know who depends on it and what it depends on.
+
+1. Pin down the exact symbol: its definition, signature, and the module/namespace that exports it.
+2. Find callers — grep for the name across the repo, then filter out shadowing, comments, and unrelated same-name symbols.
+3. Find dependencies — list the functions, types, and external modules this symbol calls or uses.
+4. Follow indirection: interfaces/abstract methods, dynamic dispatch, dependency injection, event handlers, and re-exports that hide real call sites.
+5. Note entry points that reach the symbol (HTTP routes, CLI commands, jobs, tests) so you know the real blast radius.
+6. Summarize as inbound (callers) and outbound (dependencies), flagging anything public/exported or crossing a package boundary.
+
+## Rules
+- A grep for the bare name over-matches; confirm each hit is the same symbol, not a namesake.
+- Account for indirect calls — interface implementations and string-keyed dispatch will not show as direct references.
+- Treat exported/public symbols as having unknown external callers; say so when the repo is a library.
+- Distinguish test-only callers from production callers; they imply different risk.
+- Report concrete file:line references, not vague counts.

package/skills/canvas-debug/SKILL.md

@@ -0,0 +1,23 @@
+---
+name: canvas-debug
+description: Debug HTML5 canvas rendering bugs: missing draws, smearing, wrong coordinates, broken transforms or clipping
+category: graphics
+---
+
+# Canvas Debug
+
+Reach for this when a 2D `<canvas>` shows nothing, smears frames together, draws in the wrong place, or scales oddly.
+
+1. Confirm you have a 2D context and a sized canvas: log `ctx`, `canvas.width`, `canvas.height`. A canvas styled with CSS but never given `width`/`height` attributes defaults to 300x150 and stretches.
+2. Reproduce in isolation: comment out the render loop and draw one hard-coded `fillRect(10,10,50,50)` in a solid color. If that shows, the bug is in your draw data/order, not the canvas.
+3. For smearing/ghosting across frames, confirm you `clearRect(0,0,canvas.width,canvas.height)` (or reset) at the top of every frame; accumulating trails means the clear is missing or sized wrong.
+4. For "everything shifted/rotated/gone after one draw", audit `save()`/`restore()` pairing — an unmatched `translate`/`rotate`/`scale` leaks into later draws. Add a counter or wrap each entity's draw in `save()`...`restore()`.
+5. For wrong coordinates on click/hit-test, map pointer coords through `getBoundingClientRect()` and the DPR scale, not raw `clientX/Y`; mismatched canvas pixel size vs CSS size is the usual culprit.
+6. For invisible draws, check `globalAlpha`, `fillStyle`/`strokeStyle` (transparent or same-as-background), `lineWidth` 0, paths not `beginPath()`-reset between shapes, and drawing outside an active `clip()` region.
+
+## Rules
+- Set `canvas.width`/`canvas.height` as attributes (or in JS), never only via CSS — CSS only stretches the bitmap.
+- Every `save()` needs exactly one `restore()`; never rely on resetting transforms by hand.
+- Call `beginPath()` before each new shape or strokes/fills bleed into prior subpaths.
+- Coordinates are in the transformed space — pointer hit-testing must invert the same transform.
+- Clear the frame explicitly; canvases never auto-clear between draws.

package/skills/cdn-setup/SKILL.md

@@ -0,0 +1,23 @@
+---
+name: cdn-setup
+description: Configure a CDN and cache layer in front of an origin for speed and offload
+category: cloud
+---
+
+# CDN Setup
+
+Reach for this to put a CDN (CloudFront, Cloudflare, Fastly) in front of an origin so static assets are served from the edge and the origin sees far less traffic.
+
+1. Define the origin (host, port, protocol) and create the distribution/zone pointing at it.
+2. Set cache behaviors: long TTLs for immutable static assets, short or bypass for HTML and authenticated routes.
+3. Honor or override caching with `Cache-Control`/`Surrogate-Control` headers from the origin; decide which query strings, headers, and cookies are part of the cache key.
+4. Attach TLS at the edge and force HTTPS; configure the custom domain (CNAME) and its certificate.
+5. Set a cache-busting strategy — hashed/fingerprinted asset filenames so new deploys invalidate naturally.
+6. Test cache behavior by inspecting `X-Cache`/`CF-Cache-Status`/`Age` response headers, then load-test to confirm origin offload.
+
+## Rules
+- Never cache authenticated or personalized responses at a shared edge — vary on auth or set `Cache-Control: private`.
+- Prefer fingerprinted filenames over manual cache invalidation; invalidations are slow, rate-limited, and sometimes billed.
+- Keep the cache key minimal — every cookie/header/query param you include fragments and dilutes the cache.
+- Set sensible `Cache-Control` at the origin so the CDN, browsers, and intermediaries all agree.
+- Watch for cache stampedes on misses; enable origin shielding / request coalescing for hot objects.