acuvo-code 0.2.0

package/skills/performance.md

@@ -0,0 +1,77 @@
+---
+name: performance
+description: Measure before optimising — images, bundle size, the render loop, and the costs that dominate
+when: When a page feels slow, before optimising anything, or when adding a dependency or an image
+---
+
+# Performance
+
+## ⚠️⚠️ Measure first. Optimising by intuition is how a day disappears.
+
+Intuition about what is slow is wrong often enough that acting on it unmeasured
+is gambling. Open the profiler, or time it:
+
+```js
+console.time('render'); doTheThing(); console.timeEnd('render');
+```
+
+⭐ And know what "slow" means here — a 400ms function called once on load is
+irrelevant; a 4ms function called 3,000 times in a scroll handler is the bug.
+
+## The costs that actually dominate a web page
+
+In rough order of how often they matter:
+
+1. **Images.** Usually most of the bytes. Wrong-sized hero images are the single
+   most common cause of a slow page.
+2. **Blocking requests** in the head — a font, a stylesheet, a synchronous
+   script — each one delays first paint.
+3. **JavaScript bundle size** — download, then parse, then execute.
+4. **Layout thrash** — reading a layout property after writing one, in a loop.
+5. Everything else.
+
+## Images
+
+- Size them for the box they land in. A 4000px photo in a 400px card wastes 99%
+  of its bytes.
+- Modern format (WebP/AVIF) with a fallback.
+- `loading="lazy"` for anything below the fold — never for the hero, which is
+  the one thing you want early.
+- **Always set `width` and `height`** (or `aspect-ratio`). Without them the page
+  reflows when each image arrives, which is both ugly and a Core Web Vital.
+
+## The render loop
+
+```js
+✗ items.forEach(i => list.appendChild(render(i)));   // layout per item
+✓ const frag = document.createDocumentFragment();
+  items.forEach(i => frag.appendChild(render(i)));
+  list.appendChild(frag);                             // one layout
+```
+
+⚠️ **Reading forces a recalculation.** `offsetHeight`, `getBoundingClientRect`
+and friends flush pending layout. Reading one in a loop that also writes makes
+the browser recompute every iteration. Batch: read everything, then write
+everything.
+
+Debounce input handlers; throttle scroll and resize.
+
+## ⚠️ Every dependency is bytes the user downloads
+
+Before adding one, check what it costs and whether a few lines would do. A date
+library for one `toLocaleDateString` is a bad trade. Import only what you use —
+`import { debounce } from 'lodash-es'`, never the whole namespace.
+
+## Do less work
+
+The fastest request is the one not made, and the fastest render is the one
+skipped. Cache what does not change; paginate instead of loading everything
+(see `api-design`); do not recompute a derived value on every render when it
+only changes when its inputs do.
+
+## ⚠️ Perceived speed is real speed
+
+A skeleton that appears in 100ms feels faster than a blank screen for 400ms and
+then everything at once — same total time. Show structure early, respond to
+input immediately even if the result takes a moment, and never leave a click
+with no visible acknowledgement.

package/skills/plan-before-building.md

@@ -0,0 +1,52 @@
+---
+name: plan-before-building
+description: Use the planning verbs and the whiteboard to think before writing code
+when: Any task with more than about three steps, or any ambiguous request
+---
+
+# Think first, then build
+
+## Why this pays
+
+An agent that starts typing immediately rewrites files it already wrote, loses
+track of what is done, and produces the same file three times. Planning is not
+ceremony — it is what keeps a long build coherent.
+
+Use `plan_start` / `plan_step` / `plan_status`. They exist so the plan survives
+the context, not just your intention.
+
+## The shape of a good plan
+
+1. **Restate the goal in one sentence.** If you cannot, you do not have one yet.
+2. **List what you do not know** and how you will find out — read a file, run a
+   command, check a schema. Do this BEFORE writing code that assumes an answer.
+3. **Order by risk, not by ease.** The step most likely to invalidate the others
+   goes first. Discovering the API shape after building the UI around it is the
+   expensive order.
+4. **Name what "done" looks like** in terms someone else could check.
+
+## Read before you write
+
+Before editing a file, read it. Before adding a helper, search for one that
+exists. Before designing a schema, look at the tables already there.
+
+Most duplicated code is not a naming failure — it is someone writing before
+looking. `list_files` and `search_text` are cheap; a second implementation of an
+existing thing is not.
+
+## Use the whiteboard to think, not just to output
+
+A whiteboard or diagram is most valuable BEFORE the code: laying out the screens,
+the data flow, the states. Using it only to render a finished result wastes the
+half where it actually helps.
+
+Sketch: what are the screens, what data does each need, where does that data come
+from, what happens when it is missing.
+
+## When to stop and ask
+
+Ask when two readings of the request produce materially different work and you
+cannot tell which is meant. Do not ask about things you can determine yourself by
+reading the code — that is slower for everyone and it is your job.
+
+State the assumption and keep moving when the cost of being wrong is low.

package/skills/planning-and-delegating.md

@@ -0,0 +1,72 @@
+---
+name: planning-and-delegating
+description: Multi-deliverable work — declare the plan, track it honestly, delegate to save context
+when: When a task has more than one deliverable, when the user names commands that must pass, or when a subtask would flood your context
+---
+
+# Planning And Delegating
+
+## ⭐⭐ Declare the deliverables BEFORE starting
+
+`plan_start` records what a task's deliverables are. Every later tool result
+then carries a line telling you how many remain.
+
+**Why it matters more than it looks:** the common failure on a five-part request
+is not doing a part badly, it is **finishing three and reporting done.** A plan
+you cannot see is a plan you will drift off. The reminder rides along with work
+you were doing anyway.
+
+Use it whenever the request has more than one deliverable — *"add the endpoint,
+write the test, and update the docs"* is three, not one.
+
+## ⚠️⚠️ `plan_step` done means the deliverable EXISTS and you CHECKED
+
+Marking a step done because you wrote the code that should produce it is how a
+plan becomes fiction. **Nothing else marks a step done** — so if the plan says
+done, that is a claim you made, and the user will read it as verified.
+
+`blocked` is a real state and an honest one. Use it. A blocked step that says so
+is worth far more than a done step that is not.
+
+⭐ **`plan_status` when you have lost the thread** — after a long detour, or
+resuming. Cheaper than re-reading the conversation, and it is authoritative.
+
+## ⭐⭐⭐ Acceptance criteria are the USER'S words, recorded early
+
+When the user says *"it's done when `npm test` passes"*, call
+**`declare_acceptance` with their command, verbatim, ONCE, before doing the
+work.**
+
+⚠️ **A criterion chosen AFTER the work is a criterion chosen to pass.** That is
+the whole reason it is recorded first — a test you picked because it goes green
+proves nothing about what was asked.
+
+**`check_acceptance` is the only thing that clears them.** Running the command
+yourself and seeing it pass does not; `evaluate` returning true does not. If the
+criteria are outstanding, the work is outstanding, however good the code looks.
+
+## ⭐⭐ `delegate` protects the thing you cannot get back: context
+
+Hand off a self-contained piece of work and you get back **a short summary, not
+everything the helper read.** The helper burns its own context; yours stays for
+the work only you can do.
+
+**Good delegation:** *"find every call site of `readRows` and report which ones
+ignore the status field"* — a big search, a small answer.
+
+⚠️ **Bad delegation:** anything where you need the intermediate detail, or where
+the task is not self-contained. The helper cannot see your conversation. If the
+brief needs three paragraphs of background, you are better off doing it.
+
+⭐ **It only READS by default.** That is the safe setting and it should stay the
+default in your head: send it to find out, come back to decide.
+
+## ⭐ `remember` for what a future session would otherwise get WRONG
+
+Not a diary. One durable fact, with **why**, and only if a future session would
+otherwise repeat a mistake or rediscover something expensive.
+
+*"The dev server needs `npm install` first — `node_modules` ships incomplete"* is
+worth remembering. *"Fixed the header"* is not.
+
+Related skills: `plan-before-building`, `verify-your-own-work`, `debugging`.

package/skills/refactoring.md

@@ -0,0 +1,70 @@
+---
+name: refactoring
+description: Changing code safely without a rewrite — small steps, a green check between each, no behaviour change
+when: Before restructuring code, when tempted to rewrite, or when a change touches many files
+---
+
+# Refactoring
+
+## ⚠️⚠️ Refactoring means behaviour does NOT change
+
+If the output changes, it is not a refactor — it is a rewrite with a reassuring
+name, and it will be reviewed as if nothing could have broken.
+
+Do them one at a time:
+
+- **Refactor**, verify it still behaves identically, commit.
+- **Then** change the behaviour, in its own commit.
+
+Mixing the two produces a diff where nobody — including you next month — can
+tell which lines were meant to change anything.
+
+## Small steps with a green check between each
+
+The safety comes from the size of the step, not from care. Rename, run. Extract,
+run. Move, run. If something breaks you know exactly what did it, because you
+did exactly one thing.
+
+⚠️ A refactor that cannot be verified between steps is a rewrite. **Get a check
+in place FIRST** — if the code has no test, the first commit is a test that
+pins current behaviour, before you touch anything.
+
+⭐ And confirm that check can fail: break the code deliberately, see it go red,
+restore. A green suite that would stay green through a mistake gives you
+confidence you have not earned (`verify-your-own-work`).
+
+## ⚠️ The rewrite trap
+
+"This is a mess, I will just rewrite it" loses everything the mess encodes: the
+edge cases, the bug fixes, the reason for the strange branch on line 40 that
+turns out to be a customer's data. The ugly code has been in production; the
+clean replacement has not.
+
+Rewrite when the requirements genuinely changed. Refactor when the code is hard
+to work with. They are different problems and only one is solved by starting
+over.
+
+## What to do first
+
+1. **Rename** to what things actually are. Free, reversible, and often the
+   whole problem — a lot of "confusing code" is code with lying names.
+2. **Extract** a well-named function from a comment that says what the next ten
+   lines do.
+3. **Delete** what nothing calls. Dead code is read, maintained and believed by
+   everyone who comes after.
+4. **Split** only once the seams are obvious. Splitting early puts boundaries in
+   the wrong places, and a wrong boundary is harder to remove than no boundary.
+
+## Duplication is cheaper than the wrong abstraction
+
+Two similar blocks that evolve differently are fine. One "shared" helper with
+four boolean flags to serve four callers is worse than the duplication it
+replaced. **Wait for the third occurrence** before generalising — by then you
+can see what is genuinely common.
+
+## Leave the campsite tidy, not rebuilt
+
+Touching a file is a good moment to fix the name you had to squint at. It is not
+a good moment to restructure the module — that lands in someone's review of an
+unrelated change, and it is where "small fix" becomes a 400-line diff nobody can
+approve with confidence.

package/skills/security-basics.md

@@ -0,0 +1,76 @@
+---
+name: security-basics
+description: The handful of vulnerabilities that actually occur — XSS, injection, secrets, and safe defaults
+when: When handling user input, rendering it back, calling a database, or touching a credential
+---
+
+# Security basics
+
+Not the whole OWASP list — the few that actually turn up in application code.
+
+## ⚠️⚠️ XSS: never build HTML by concatenating input
+
+```js
+✗ el.innerHTML = `<p>Hello ${name}</p>`;     // name = "<img src=x onerror=alert(1)>"
+✓ el.textContent = `Hello ${name}`;
+✓ el.append(document.createTextNode(name));
+```
+
+`textContent` cannot execute anything. Reach for `innerHTML` only with a string
+you built entirely yourself, and treat every alternative as better.
+
+Also XSS, and easier to miss:
+
+```js
+✗ <a href={userSupplied}>          // "javascript:…" runs on click
+✗ el.setAttribute('onclick', …)
+✗ eval(…) / new Function(userInput) / setTimeout("string")
+```
+
+For a URL, check the scheme against an allowlist (`https:`, `http:`, `mailto:`)
+rather than looking for bad ones.
+
+## Injection: the query is code, the input is data
+
+```js
+✗ db.query(`SELECT * FROM users WHERE email = '${email}'`)
+✓ db.query('SELECT * FROM users WHERE email = $1', [email])
+```
+
+Parameterise. Escaping by hand fails on the case you did not think of. The same
+rule applies to shell commands: pass an argument array, never build a string.
+
+## ⚠️⚠️ Secrets
+
+- Never in client code. Anything shipped to a browser is public — a "hidden"
+  API key in a bundle is a published API key.
+- Never in the repository. `.env` is gitignored; `.env.example` holds the names
+  with no values.
+- Never in a log line, an error message, or a URL (URLs land in history and in
+  access logs).
+- A leaked key is rotated, not deleted from the history — assume it was read.
+
+## CSRF
+
+A cookie-authenticated state-changing request needs more than the cookie, since
+the browser attaches it automatically from any origin. `SameSite=Lax` covers
+most of it; add a token for the rest. `GET` must never change anything.
+
+## Validate on the server, always
+
+The client's validation is for the user's benefit. Re-check types, ranges,
+lengths and permissions on arrival — every value, every time, including ones a
+dropdown "could only" have produced.
+
+## Safe defaults
+
+- **Deny by default.** New endpoint, no explicit permission check → it should
+  fail closed, not open.
+- **Least privilege.** The database user for the app does not need `DROP`.
+- **Do not tell an attacker why.** "Email or password is incorrect" — not
+  "no such user", which turns your login form into a list of who has an account.
+
+## ⚠️ Dependencies are your code
+
+A package you added runs with your permissions. Prefer fewer, prefer maintained,
+and read what a postinstall script does before it runs on your machine.

package/skills/state-management.md

@@ -0,0 +1,73 @@
+---
+name: state-management
+description: One source of truth, derive the rest, and knowing when local state stops being enough
+when: When adding state, when two components disagree, or before reaching for a state library
+---
+
+# State
+
+## ⚠️⚠️ One source of truth. Derive everything else.
+
+The bug where two parts of the screen disagree is almost always two copies of
+one fact.
+
+```js
+✗ let items = [...]; let itemCount = 0;   // now they can differ, and they will
+✓ let items = [...]; const count = items.length;   // derived, cannot drift
+```
+
+If a value can be computed from another value, **compute it**. Store only what
+cannot be derived. A cached derived value is a second source of truth wearing a
+disguise.
+
+## Where state should live
+
+In order — take the first that works:
+
+1. **In the component that uses it.** Most state is local and should stay there.
+2. **In the nearest common parent**, when two siblings need it.
+3. **In the URL**, when it should survive a refresh or be shareable — filters,
+   the current tab, a search query, pagination. This is the most under-used
+   option and it is free.
+4. **On the server**, when it is data rather than interface state.
+5. **In a global store**, only when many distant components genuinely need it.
+
+⚠️ Reaching for a global store first makes every piece of state everyone's
+business, and nothing can then be changed locally with confidence.
+
+## Server data is not UI state
+
+Data fetched from an API has its own concerns — loading, error, stale, refetch,
+cache — and modelling it as plain state means re-implementing all of them badly.
+Keep it separate from interface state (which panel is open, what is typed).
+
+⭐ And remember the third outcome: a request is **loading**, **failed**, or
+**succeeded**. A component modelling only "have data / no data" shows an empty
+state during loading and after a failure, which are three different things
+flattened into one. See `error-handling`.
+
+## Never mutate what you are about to compare
+
+```js
+✗ state.items.push(x);            // same reference — a change detector sees nothing
+✓ state = { ...state, items: [...state.items, x] };
+```
+
+This is the cause of "the data is right but the screen did not update".
+
+## ⚠️ Do not put derived data in the URL or in storage
+
+Persist the minimum: an id, not the whole object it points at; a filter, not the
+filtered result. Anything stored is a copy that can go stale, and stored copies
+outlive the code that wrote them — `localStorage` from a version you shipped
+last year will be handed to today's code.
+
+Validate anything read back from storage. It is untrusted input: the user can
+edit it, and an old version of your app may have written it.
+
+## Keep updates close to the event
+
+State that changes in five places for one user action is state nobody can
+follow. One action → one update → the screen follows from the new state. If you
+cannot say what a click changes in a sentence, the shape is wrong, not the
+library.

package/skills/supabase-multitenant.md

@@ -0,0 +1,72 @@
+---
+name: supabase-multitenant
+description: Supabase with real multi-tenant safety — RLS, service role, and the leaks that look like working code
+when: Reading or writing any database table, or adding a migration
+---
+
+# Supabase, multi-tenant
+
+## The two clients, and why mixing them leaks data
+
+- **Anon / user client** — respects Row Level Security. Use for anything a user
+  triggers about their own data.
+- **Service role** — BYPASSES RLS entirely. Use only in operator/admin paths,
+  and never where a tenant id came from the request.
+
+⚠️⚠️ **The classic leak looks like working code:**
+```ts
+// WRONG — the client chose whose data to read
+const { data } = await admin.from('invoices').select('*').eq('tenant_id', body.tenantId);
+```
+Derive the tenant from the session, never from the payload.
+
+## RLS: a GRANT and a POLICY are different things
+
+- `GRANT` missing → `42501 permission denied`
+- `POLICY` missing → **zero rows, no error**
+
+⚠️ The second is the dangerous one: it renders as an innocent empty state. If a
+table "has no rows" and you are sure it should, check the policy before the code.
+
+```sql
+alter table app.invoices enable row level security;
+grant select on app.invoices to authenticated;
+create policy invoices_own on app.invoices
+  for select to authenticated
+  using (tenant_id in (select tenant_id from app.tenant_users where user_id = auth.uid()));
+```
+
+⚠️ **A VIEW does not inherit the underlying table's RLS** — it runs with the
+definer's rights. A view over a tenant table is a leak unless it filters
+explicitly or is operator-only.
+
+## Reading honestly
+
+A failed read and an empty result are DIFFERENT FACTS and must render
+differently. Never `?? []`:
+
+```ts
+const { data, error } = await supabase.from('x').select('*');
+if (error) return { rows: [], unreadable: error.message };  // "we could not read"
+return { rows: data ?? [], unreadable: null };              // "there is nothing"
+```
+
+## Counting and caps
+
+`.limit(n)` without a count silently turns a partial sample into a confident
+total. Ask for the count and say when you hit the cap:
+```ts
+const { data, count } = await supabase.from('x').select('*', { count: 'exact' }).limit(5000);
+const truncated = (count ?? 0) > (data?.length ?? 0);
+```
+⭐ The real fix at scale is aggregating in SQL (a view with `sum()`/`group by`)
+so the row count stops mattering. Raising the limit only moves the cliff.
+
+## Migrations
+
+- Number them sequentially and **check the highest number on disk first** — two
+  files claiming one number breaks whoever applies them next.
+- Idempotent always: `add column if not exists`, `create index if not exists`.
+- A `GENERATED` column cannot be written to. If code needs to insert it, it must
+  be a plain column.
+- Add the `GRANT` and the `POLICY` in the same migration as the table.

package/skills/typescript-strict.md

@@ -0,0 +1,90 @@
+---
+name: typescript-strict
+description: The types that catch real bugs versus the ones that are ceremony — and why `any` costs more than it saves
+when: When adding types, when tempted to write `any` or a cast, or when configuring tsconfig
+---
+
+# TypeScript
+
+## Turn `strict` on. It is where the value is.
+
+```json
+{ "compilerOptions": { "strict": true, "noUncheckedIndexedAccess": true } }
+```
+
+Without `strict`, `null` and `undefined` are assignable to everything and the
+compiler cannot catch the single most common runtime error there is. Without
+`noUncheckedIndexedAccess`, `arr[10]` is typed as present when it is not.
+
+## ⚠️⚠️ `any` does not silence one error, it disables checking downstream
+
+```ts
+✗ const data: any = await res.json();
+  data.user.name          // no error here, and no error anywhere it flows
+✓ const data: unknown = await res.json();
+  // now you MUST narrow it — which is the check you actually wanted
+```
+
+`unknown` is the honest version of `any`. It says "we do not know yet" and
+forces exactly one narrowing at the boundary, instead of letting a wrong shape
+travel silently through ten functions.
+
+The same applies to `as`. A cast is you telling the compiler to stop checking:
+
+```ts
+✗ const user = json as User;        // asserted, never verified
+✓ if (!isUser(json)) throw new Error('unexpected response shape');
+```
+
+## Types that catch bugs
+
+**Make illegal states unrepresentable.** This is the highest-value thing types
+do:
+
+```ts
+✗ { loading: boolean; error?: string; data?: Invoice[] }
+    // loading AND error AND data — eight states, five of them nonsense
+✓ | { status: 'loading' }
+  | { status: 'error'; error: string }
+  | { status: 'ready'; data: Invoice[] }
+```
+
+Now "loading with an error" cannot be written, and every consumer is forced to
+handle all three — which is the `error-handling` rule (empty ≠ failed ≠ never
+ran) enforced by the compiler.
+
+**Distinguish things that are both strings:**
+
+```ts
+type TenantId = string & { readonly __brand: 'TenantId' };
+```
+
+Passing a `UserId` where a `TenantId` belongs is a multi-tenant data leak, and
+it is a compile error rather than an incident.
+
+## Ceremony to skip
+
+- Annotating what is obvious: `const n: number = 5`. Inference is not weaker
+  typing — it is the same type, without the noise.
+- An `interface` per function argument list used once.
+- `Promise<void>` return annotations on every async function.
+- Enums where a union of string literals reads better and needs no runtime.
+
+⭐ Type the BOUNDARIES — function signatures, exported values, anything crossing
+the network — and let inference handle the inside.
+
+## ⚠️ Types are erased, so they are not validation
+
+A `User` type proves nothing about what the API actually sent; it is a comment
+the compiler checks *your* code against. Data arriving from outside — a
+response, `localStorage`, a query param — must be checked at runtime, and only
+then does its type mean anything (`security-basics`).
+
+## `satisfies`, when you want both
+
+```ts
+const config = { port: 3000 } satisfies Config;   // checked AND still literal
+```
+
+Checks the shape without widening the type, which is what `as Config` would
+have done while also disabling the check.