ucode-agent 1.0.0 → 1.2.0

package/skills/debug/SKILL.md

@@ -1,47 +1,89 @@
 ---
 name: debug
-description: Find the actual cause of a bug instead of the first plausible one — reproduce it, narrow it, prove the fix, and leave a test behind.
+description: Find and fix the real cause of a bug — reproduce it, narrow it down with evidence, prove the fix, guard it with a test, and check for the same bug elsewhere.
+auto: bug, crash, crashes, crashing, broken, not working, doesn't work, does not work, stack trace, exception, traceback, throws, failing, fails, regression, undefined is not, cannot read properties, 500 error, blank page, hangs, freezes
 ---
 
 # Debugging
 
-The temptation is to read the code, form a theory, change something, and
-declare victory when the symptom disappears. That is how a bug gets moved
-rather than fixed.
+The temptation is to read the code, form a theory, change something, and call
+it fixed when the symptom goes away. That moves bugs rather than fixing them.
+Work from evidence, in this order.
 
-## Reproduce it first
+## 1. Reproduce it yourself
 
-Do not start from the description. Run the thing and see the failure with your
-own eyes: the command, the input, the exact error and where it comes from. If
-you cannot reproduce it, say so and ask for what you need — the input, the
-version, the full stack. Guessing from a paraphrase wastes everyone's turn.
+Do not debug from the description. Run it and see it fail: the exact command,
+the input, the full error, the line it comes from. Write down the reproduction
+as a single command or a few steps — you will run it again at the end.
 
-## Narrow before you theorise
+If you cannot reproduce it, say so and ask for exactly what is missing: the
+input, the environment, the version, the full output. Guessing from a
+paraphrase wastes everyone's turn.
 
-- Read the whole stack trace, including the frames you assume are irrelevant.
-  The top frame is where it surfaced, not necessarily where it went wrong.
-- `grep` for the message text to find where it is produced.
-- Cut the search space in half at a time: does the smaller input fail? Does it
-  fail on the previous commit? Does the layer below get the right value?
-- Print or log the values at the boundary rather than reasoning about what they
-  should be. What you believe is in that variable is the thing under suspicion.
+## 2. Read the whole error
 
-## Fix the cause
+- The whole stack trace, including frames you assume are irrelevant. The top
+  frame is where it surfaced, not necessarily where it went wrong.
+- The first error, not the last. Later errors are often consequences.
+- `grep` for the exact message text to find where it is produced.
+- Check the obvious before the clever: is the file saved, the server restarted,
+  the right branch checked out, the env var set, the dependency installed, the
+  cache cleared (`.next`, `node_modules/.vite`, `__pycache__`)?
 
-State the cause in one sentence before you change anything: *this value is
-undefined here because the caller only sets it on the success path*. If you
-cannot write that sentence, you have not found it yet.
+## 3. Narrow it down
 
-Then fix that, not the symptom. A guard that hides the undefined value leaves
-the real defect in place, with one more layer over it.
+Cut the search space in half each step:
 
-## Prove it
+- **Input:** does a smaller or simpler input still fail? Find the smallest one
+  that does.
+- **Code:** comment out or bypass half the path. Does it still fail?
+- **Time:** did it work before? `git log` / `git diff` since then, or
+  `git bisect` between a good and a bad commit.
+- **Layer:** is the value right when it enters the function? When it leaves?
+  At the API boundary? In the database? Log it at each boundary and look,
+  rather than reasoning about what it "should" be.
 
-- Run the original reproduction. It must now pass.
-- Run the rest of the tests. A fix that breaks two other things is a trade,
-  and the user gets to make it, not you.
-- Write a test that fails without your fix. A bug with no regression test comes
-  back.
+The value you are sure about is the one under suspicion. Print it.
 
-Then say what the cause actually was, in one or two sentences. If you fixed
-something adjacent along the way, say that too.
+## 4. Know where bugs usually live
+
+- **Async:** a missing `await`, a race between two requests, state read before
+  it is set, a promise rejection nobody catches.
+- **State:** stale closures in React effects, mutation of shared objects, a
+  cache that was never invalidated.
+- **Boundaries:** off-by-one, empty arrays, `null` vs `undefined` vs `''`,
+  timezones, number parsing (`'10' + 1`), float rounding.
+- **Data shape:** the API returned something different from the type — an
+  error object, a wrapped payload, a string instead of JSON.
+- **Environment:** missing env var, wrong Node version, path case sensitivity,
+  Windows vs POSIX paths and line endings, a port already in use.
+- **Build tooling:** a stale build cache, a server/client boundary violation in
+  Next.js, a default vs named export mismatch, ESM vs CommonJS.
+
+## 5. State the cause before fixing it
+
+Write it in one sentence: *"`score` is `undefined` here because the parser
+returns `{ data: {...} }` and the component reads `result.score`."* If you
+cannot write that sentence, you have not found the cause yet — keep narrowing.
+
+## 6. Fix the cause, not the symptom
+
+A `?.` or a `try/catch` that hides the failure leaves the defect in place under
+one more layer. Fix it where it originates. Keep the change as small as the
+cause allows, and do not refactor unrelated code in the same change.
+
+## 7. Prove it
+
+- Run the original reproduction. It must pass now.
+- Run the whole test suite. A fix that breaks two other things is a trade the
+  user gets to decide on, not you.
+- Add a regression test that fails without the fix and passes with it — then
+  briefly revert the fix to confirm the test really catches it.
+- Look for the same mistake elsewhere: `grep` for the same pattern, call, or
+  assumption. Bugs come in families.
+
+## 8. Report
+
+The cause in one or two sentences, the fix, how you verified it, and anything
+adjacent you noticed but did not change. If you could not fully confirm it,
+say what is still uncertain.

package/skills/performance/SKILL.md

@@ -0,0 +1,84 @@
+---
+name: performance
+description: Make software measurably faster — measure first, find the real bottleneck, fix it, and prove the improvement with numbers. Covers web vitals, bundles, React rendering, APIs, databases and Node.
+auto: slow, slower, performance, perf, optimize, optimise, optimization, speed up, faster, lag, laggy, sluggish, bundle size, lighthouse, core web vitals, web vitals, lcp, cls, inp, memory leak, re-render, rerender, n+1, latency, takes too long
+---
+
+# Performance
+
+Guessing at performance is how people spend a day optimizing something that
+was never slow. Measure, change one thing, measure again.
+
+## 1. Measure before touching anything
+
+- **Define the slow thing precisely**: which page, action or endpoint, how slow
+  now, how fast it needs to be.
+- **Get a baseline number** you can re-run:
+  - Web page: Lighthouse / PageSpeed (LCP, INP, CLS, total JS), the browser
+    Performance panel, `next build` output (per-route JS size).
+  - API: time the request (`curl -w "%{time_total}\n"`), log durations per step.
+  - Node/Python: a profiler (`node --cpu-prof`, `clinic`, `py-spy`), or timers
+    around the suspect code.
+  - Database: `EXPLAIN ANALYZE` on the slow query.
+- Measure the production build, not dev mode — dev is deliberately slow.
+
+## 2. Find the actual bottleneck
+
+It is almost always one of these, in roughly this order of likelihood:
+
+1. **Network waterfalls** — requests that wait on each other when they could run
+   in parallel; data fetched on the client that could be fetched on the server.
+2. **Too much JavaScript** — heavy dependencies, everything marked
+   `"use client"`, no code splitting.
+3. **Unoptimized images and fonts** — huge images, no dimensions (layout shift),
+   blocking font loads.
+4. **Database** — N+1 queries, missing indexes, fetching whole tables, no
+   pagination.
+5. **Rendering** — React re-rendering large trees on every keystroke, expensive
+   work inside render, long lists without virtualization.
+6. **Algorithmic** — nested loops over large data, repeated work that could be
+   cached or computed once.
+
+## 3. Fixes by area
+
+**Web (Next.js / React)**
+- Server components by default; `"use client"` at the leaves only.
+- `next/image` with explicit sizes; `priority` on the LCP image; modern formats.
+- `next/font` with `display: swap`, only the weights used.
+- Dynamic `import()` for heavy, below-the-fold or rarely used components.
+- Replace heavy libraries (moment → date-fns/Intl, lodash → native, big chart
+  libs → lighter ones) and check the per-route JS in the build output.
+- Parallelize independent fetches with `Promise.all`; stream with `Suspense`.
+- Cache: static where possible, `revalidate` for data that changes slowly.
+
+**React rendering**
+- Keep state as low in the tree as possible; lift only what must be shared.
+- Stable props: memoize expensive values and callbacks passed to memoized
+  children — but only where the profiler shows a real cost.
+- Virtualize lists over a few hundred rows.
+- Debounce input-driven work (search, validation) at ~200–300ms.
+
+**APIs and databases**
+- Index columns used in `WHERE`, `JOIN` and `ORDER BY`; confirm with `EXPLAIN`.
+- Batch or join instead of querying in a loop (N+1).
+- Select only the columns needed; paginate everything user-sized.
+- Cache expensive, repeatable results (in memory, Redis, HTTP caching) with a
+  clear invalidation rule.
+- Move slow non-essential work (emails, analytics, thumbnails) to a background
+  job.
+
+**Node**
+- Never block the event loop with sync I/O or heavy CPU in a request handler.
+- Stream large files instead of reading them whole.
+- Reuse clients and connections (DB pools, HTTP keep-alive).
+
+## 4. Change one thing at a time, and prove it
+
+After each change, re-run the same measurement. Keep changes that move the
+number; revert ones that do not — complexity without a measured win is a cost.
+
+## 5. Report with numbers
+
+Before and after for each metric that changed ("LCP 4.1s → 1.6s, route JS
+312 kB → 148 kB"), what caused it, and anything left that would need a bigger
+change to fix.

package/skills/refactor/SKILL.md

@@ -0,0 +1,72 @@
+---
+name: refactor
+description: Restructure code without changing what it does — a safety net first, small verified steps, clear boundaries and names, and no behaviour change slipped in along the way.
+auto: refactor, refactoring, clean up, cleanup, clean this, restructure, reorganize, reorganise, simplify, tech debt, technical debt, extract, split this file, split up, dead code, duplicate code, duplication, messy code, spaghetti
+---
+
+# Refactoring
+
+A refactor changes the shape of code and nothing else. The moment behaviour
+changes, it is a rewrite, and a rewrite hidden inside a refactor is how
+regressions ship with nobody noticing.
+
+## 1. Know why, and where it stops
+
+- State the goal in one line: *split the 700-line page into components*,
+  *remove the duplicated fetch logic*, *make the scoring rules testable*.
+- State the boundary: which files are in scope. Resist improving everything you
+  pass on the way — note it and leave it.
+
+## 2. Build the safety net first
+
+- Run the existing tests and record the result. If there are none around the
+  code you are changing, **write characterization tests first**: tests that pin
+  down what the code does now, including its odd behaviour. You are preserving
+  behaviour, so you must be able to detect when it changes.
+- For UI with no tests, capture the current behaviour: what renders in each
+  state, what each control does.
+
+## 3. Read it all before moving anything
+
+Read every file in scope in full, and find every caller of what you will change
+(`grep` for the names, the imports, the routes). A rename that misses one
+dynamic reference is a runtime error waiting for the one path nobody tested.
+
+## 4. Small steps, each one green
+
+Do one kind of change at a time, and run the tests after each:
+
+- **Rename** to say what things are: `data` → `analysis`, `handle()` →
+  `submitLabel()`. Names are most of readability.
+- **Extract** a function or component for each distinct job; a function should
+  do one thing at one level of abstraction.
+- **Move** code next to what uses it: feature folders over type folders.
+- **Remove duplication** only when the copies really are the same concept —
+  two similar-looking pieces that change for different reasons should stay two.
+- **Delete dead code** — unused exports, unreachable branches, commented-out
+  blocks. Confirm it is unused with a search first.
+- **Simplify conditionals**: early returns over nesting, lookup tables over long
+  `if/else` chains, named booleans over complex expressions.
+- **Push side effects to the edges**: pure logic in the middle (easy to test),
+  I/O at the boundary.
+
+Use `multi_edit` for several changes in one file, and keep each step small
+enough that a failing test points straight at the cause.
+
+## 5. Keep behaviour identical
+
+- Same inputs, same outputs, same errors, same side effects, same order of
+  side effects.
+- Public APIs and stored formats unchanged, or every caller and every stored
+  record updated in the same change.
+- If you find a bug while refactoring, **do not fix it silently inside the
+  refactor**. Finish the refactor, then fix the bug as its own change — or
+  report it — so each can be reviewed and reverted on its own.
+
+## 6. Finish
+
+- All tests pass, the build passes, the linter and type checker are clean.
+- The code is measurably simpler: fewer lines, fewer branches, smaller files,
+  clearer names — say which.
+- Report what moved where, anything you noticed but deliberately left alone,
+  and any behaviour you had to pin down with new tests.

package/skills/security/SKILL.md

@@ -0,0 +1,110 @@
+---
+name: security
+description: Build and audit software so it is safe by default — secrets, authentication and authorization, input validation, injection, XSS, CSRF, SSRF, uploads, dependencies and headers, checked against how attacks actually happen.
+auto: security, secure, vulnerability, vulnerabilities, auth, authentication, authorization, login, sign in, signup, sign up, password, passwords, jwt, oauth, session cookie, xss, csrf, ssrf, sql injection, injection, secrets, api key, api keys, owasp, harden, hardening, permissions, rate limit
+---
+
+# Security
+
+Assume every input is hostile and every secret will be looked for. Most real
+breaches come from a short list of boring mistakes; this skill is that list,
+with what to do about each.
+
+## 1. Secrets
+
+- **Never in the browser.** Anything imported by client code ships to every
+  visitor — including a "temporary" hardcoded key. Keys live in server routes,
+  server actions or server-only modules (`import 'server-only'`).
+- **Never in the repository.** Use `.env.local` / `.env` (gitignored) and commit
+  a `.env.example` with placeholders. If a key was ever committed or pasted
+  somewhere public, rotate it — deleting the line does not un-leak it.
+- **Never in logs, errors or URLs.** Redact before logging; do not put tokens
+  in query strings.
+- If the user insists on hardcoding a key for now, put it in one server-only
+  file, say exactly where it is, and recommend moving it to an env var.
+
+## 2. Authentication
+
+- Use a proven library or provider (Auth.js/NextAuth, Clerk, Supabase Auth,
+  Lucia-style patterns) rather than hand-rolled sessions and hashing.
+- Passwords: argon2id or bcrypt, never reversible, never logged. Rate-limit
+  login and reset endpoints. Same error message for "no such user" and "wrong
+  password".
+- Sessions: `HttpOnly`, `Secure`, `SameSite=Lax` (or `Strict`) cookies. Rotate
+  the session on login. Expire idle sessions.
+- JWTs: short expiry, verify signature and algorithm server-side, never trust
+  claims the client can edit.
+
+## 3. Authorization — the most common real hole
+
+- **Check ownership on every request**, on the server, for every object:
+  `WHERE id = $1 AND user_id = $session.user`. Changing an ID in a URL or body
+  must never reveal someone else's data (IDOR).
+- Deny by default. Every route states who may call it.
+- Hiding a button is not authorization; the endpoint behind it must check too.
+
+## 4. Input validation and injection
+
+- Validate every input at the boundary with a schema (zod, pydantic): type,
+  length, range, format. Reject, do not "clean".
+- **SQL:** parameterized queries or an ORM only. Never string-build SQL with
+  user input.
+- **Shell:** avoid it; if unavoidable, pass arguments as an array
+  (`execFile`, `spawn` without `shell: true`), never interpolate.
+- **Paths:** resolve and verify the result stays inside the allowed directory;
+  reject `..` and absolute paths from users.
+- **SSRF:** when fetching a user-supplied URL, allow-list hosts, block private
+  and link-local ranges (127.0.0.0/8, 10/8, 172.16/12, 192.168/16, 169.254/16,
+  ::1), and do not follow redirects blindly.
+
+## 5. Output: XSS
+
+- Let the framework escape (React, templating engines). Treat
+  `dangerouslySetInnerHTML`, `innerHTML`, `v-html` and markdown-to-HTML as
+  red flags: sanitize with DOMPurify if you must render HTML.
+- Never put user input into `href` without checking the scheme
+  (`javascript:` URLs), or into inline `<script>` or event handlers.
+- Set a Content-Security-Policy where you can.
+
+## 6. Requests
+
+- **CSRF:** SameSite cookies plus a CSRF token or origin check on state-changing
+  requests that use cookie auth. Next.js server actions check origin; custom
+  routes need it done.
+- **CORS:** never `*` with credentials; allow-list the origins that need it.
+- **Rate limiting** on login, signup, password reset, and any expensive or paid
+  endpoint (AI calls especially) — per IP and per user.
+
+## 7. File uploads
+
+- Check type by content (magic bytes), not just the extension or MIME header.
+- Enforce a size limit on the server, not only the client.
+- Store outside the web root or in object storage with generated names; never
+  execute or serve uploads from the app's own origin as HTML.
+- Strip metadata (EXIF location) from images when privacy matters.
+
+## 8. Errors, headers, dependencies
+
+- Errors to users are generic; details go to server logs. No stack traces in
+  responses.
+- Headers: `Strict-Transport-Security`, `X-Content-Type-Options: nosniff`,
+  `Referrer-Policy: strict-origin-when-cross-origin`, `frame-ancestors` via CSP.
+- Dependencies: `npm audit` (or the ecosystem equivalent), remove unused
+  packages, pin versions with a lockfile, be wary of new packages with few
+  downloads or typo-like names.
+
+## 9. Auditing existing code
+
+Search rather than read everything:
+
+```
+grep for: api[_-]?key|secret|token|password   (hardcoded secrets)
+          dangerouslySetInnerHTML|innerHTML|eval\(|new Function
+          exec\(|execSync|shell: true|child_process
+          \$\{.*\}.*(SELECT|INSERT|UPDATE|DELETE)  (string-built SQL)
+          fetch\(.*req\.|axios\(.*req\.         (user-controlled URLs)
+```
+
+Then check every route for authentication and ownership checks. Report
+findings ranked by severity with the file, the attack, and the fix — and fix
+the critical ones first if asked to fix.