@modeloslab/modelcode 0.1.0

package/package.json

@@ -0,0 +1,66 @@
+{
+  "name": "@modeloslab/modelcode",
+  "version": "0.1.0",
+  "description": "modelOS-native AI coding agent CLI — remembers like Hermes, codes like Claude Code, runs on modelOS (pay-per-use in MDL, no rate limits). Knowledge-graph memory, subagents, MCP, vision, spend caps.",
+  "type": "module",
+  "bin": {
+    "modelcode": "dist/cli.mjs"
+  },
+  "files": [
+    "dist",
+    "agents",
+    "skills",
+    "README.md",
+    "SPEC.md"
+  ],
+  "scripts": {
+    "dev": "bun run src/cli/main.ts",
+    "build": "bun run scripts/build.ts",
+    "typecheck": "tsc --noEmit",
+    "test": "bun test",
+    "start": "node dist/cli.mjs",
+    "smoke": "bun run build && node dist/cli.mjs config",
+    "prepublishOnly": "bun run typecheck && bun test && bun run build"
+  },
+  "engines": {
+    "node": ">=22.5.0"
+  },
+  "os": [
+    "darwin",
+    "linux"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": [
+    "ai",
+    "coding-agent",
+    "cli",
+    "llm",
+    "modelos",
+    "claude-code",
+    "agent",
+    "mcp",
+    "pay-per-use"
+  ],
+  "dependencies": {
+    "@noble/curves": "^1.9.7",
+    "@noble/hashes": "^1.8.0",
+    "@scure/base": "^1.2.6",
+    "@scure/bip32": "^1.7.0",
+    "@scure/bip39": "^1.6.0",
+    "@scure/btc-signer": "^1.8.1",
+    "ink": "^7.1.0",
+    "openai": "^4.77.0",
+    "puppeteer-core": "^25.1.0",
+    "react": "^19.2.7",
+    "zod": "^3.23.8"
+  },
+  "devDependencies": {
+    "@types/better-sqlite3": "^7.6.11",
+    "@types/bun": "^1.1.14",
+    "@types/react": "^19.2.17",
+    "typescript": "^5.7.2"
+  },
+  "license": "MIT"
+}

package/skills/commit/SKILL.md

@@ -0,0 +1,34 @@
+---
+name: commit
+description: Stage changes, write a clear conventional-commit message grounded in the diff, and commit. Never pushes unless asked.
+---
+
+# Commit: Stage and Commit
+
+## Goal
+Produce one clean, conventional commit whose message accurately reflects the diff.
+
+## Steps
+
+### 1. Inspect
+Run `git status` and `git diff` (and `git diff --staged`). Understand what actually changed and why
+before writing anything.
+**Success criteria**: you can describe the change in one sentence.
+
+### 2. Stage deliberately
+If nothing is staged, stage the relevant files — do NOT blindly `git add -A`. Exclude junk, build
+artifacts, debug scratch, and anything secret-looking (`.env`, keys, tokens). If the changes are
+logically separate concerns, prefer splitting into multiple commits.
+**Success criteria**: the staged set is exactly the intended change.
+
+### 3. Write the message
+Conventional-commit subject ≤ ~72 chars: `feat:` / `fix:` / `refactor:` / `docs:` / `test:` / `chore:` /
+`perf:` (+ optional scope). Imperative mood. Add a short body explaining the **why** when it's not
+obvious from the subject. Match the repo's existing commit style if it has one.
+
+### 4. Commit
+Commit, then show `git log -1` to confirm. Do NOT push unless the user explicitly asks. If a commit hook
+fails, fix the issue (or report it) rather than bypassing with `--no-verify`.
+
+## Notes
+Never commit secrets — if you spot one in the diff, stop and warn instead of committing.

package/skills/debug/SKILL.md

@@ -0,0 +1,44 @@
+---
+name: debug
+description: Systematically root-cause a bug, failing test, or unexpected behavior and apply the minimal fix. Use for "X is broken", a stack trace, a failing test, or wrong output.
+---
+
+# Debug: Root-Cause and Fix
+
+## Goal
+Find and fix the ROOT cause, not the symptom — via hypothesis and evidence, never guess-and-change.
+
+## Steps
+
+### 1. Reproduce
+Run the failing command/test via bash; capture the exact error + full stack. If you can't reproduce it,
+stop and get the exact steps/inputs/env from the user first — a fix you can't verify is a guess.
+**Success criteria**: you can trigger the failure on demand.
+
+### 2. Localize
+Read the code at the failure site AND one level up the call chain. Narrow to the smallest region that
+must contain the cause. Form ONE concrete hypothesis ("X is null because Y returns early when Z").
+**Success criteria**: a single, testable hypothesis.
+
+### 3. Confirm
+Prove the hypothesis before changing anything — a focused log/assertion, reading the actual state, or a
+minimal probe. If it's wrong, return to step 2 with what you learned. Don't fix on a hunch.
+**Success criteria**: evidence the hypothesis is the actual cause.
+
+### 4. Fix minimally
+Make the smallest change that addresses the confirmed cause. No scope creep, no drive-by refactors.
+If the real fix is bigger than the ask (design flaw, missing abstraction), say so and propose it rather
+than papering over it.
+
+### 5. Verify
+Re-run the repro → green. Run the surrounding test suite to confirm you didn't break neighbors. Remove
+any temporary probes you added.
+**Success criteria**: repro passes, suite green.
+
+### 6. Report
+Root cause → the fix → verification output, in 2–3 lines.
+
+## Heisenbugs (intermittent / can't-reproduce)
+Check ordering/races, async timing, shared mutable state, uninitialized values, env differences
+(versions, locale, timezone), and test pollution (state leaking between tests). Add logging to capture
+the bad run rather than trying to catch it live.

package/skills/docker/SKILL.md

@@ -0,0 +1,18 @@
+---
+name: docker
+description: Containerize or run an app with Docker — write a correct, slim Dockerfile, .dockerignore, and compose, or build/run/debug containers. Use for "dockerize this", build failures, or local container runs. (Hermes DevOps.)
+---
+
+Produce correct, production-lean containers.
+
+- **Dockerfile**: multi-stage (build stage → slim runtime); pin a specific base tag; copy only what's
+  needed; install deps before copying source (cache layers); run as a **non-root** user; set a
+  `HEALTHCHECK`; `EXPOSE` the port; use exec-form `CMD ["...", "..."]`.
+- **.dockerignore**: exclude node_modules, .git, build artifacts, secrets, .env — keeps the build
+  context small and avoids leaking secrets.
+- **compose**: define services + networks + volumes; never bake secrets into the image (use env/secrets).
+- **Run/debug**: `docker build -t app .` then `docker run --rm -p ...`; for failures read the build log
+  (usually a missing dep or wrong path), and `docker logs` / `exec -it sh` to inspect a running container.
+
+Verify: image builds, container starts + passes its healthcheck, app reachable on the mapped port. Keep
+the final image small (check `docker images`).

package/skills/init/SKILL.md

@@ -0,0 +1,36 @@
+---
+name: init
+description: Generate a MODELCODE.md describing this codebase — structure, build/test/run commands, conventions — so future sessions start with accurate project context.
+---
+
+# Init: Generate Project Context
+
+## Goal
+Produce a concise, ACCURATE `MODELCODE.md` at the repo root that gives every future session the context
+it needs to work correctly here. This file is loaded as context every session, so every line must earn
+its place and be true.
+
+## Steps
+
+### 1. Explore
+glob/grep/read the signal files: package manifests (`package.json`, `pyproject.toml`, `go.mod`, `Cargo.toml`),
+README, CI config, lockfiles, and the `src` layout. Identify the language(s), framework(s), runtime, and
+package manager.
+**Success criteria**: you can state what the project is and how it's built without guessing.
+
+### 2. Verify the commands
+Don't copy commands blindly — confirm them against the actual scripts/config (e.g. `package.json`
+scripts, Makefile, CI). Wrong commands here are worse than none.
+**Success criteria**: build/test/run/lint commands are the ones this repo actually uses.
+
+### 3. Write MODELCODE.md
+- **Overview**: one paragraph — what the project is and does.
+- **Commands**: exact build / test / run / lint / typecheck commands.
+- **Layout**: the important directories and what lives in each (not every file).
+- **Conventions**: style, patterns, and do/don'ts the agent must follow (e.g. "bun not npm",
+  "diff-based edits", naming rules) — pull real conventions from the code, don't invent.
+- **Gotchas**: anything non-obvious that would trip up a change (codegen, required env, monorepo quirks).
+
+### 4. Keep it lean
+Concise > exhaustive. If a CLAUDE.md / AGENTS.md already exists, build on it rather than duplicating.
+Confirm the file was written.

package/skills/nextjs-app-router/SKILL.md

@@ -0,0 +1,16 @@
+---
+name: nextjs-app-router
+description: Scaffold or work with the Next.js App Router (app/ dir) — pages, layouts, nested routes, loading/error/not-found states. Use for new routes or restructuring a Next.js app.
+---
+
+Work in the **App Router** (`app/`), not the legacy `pages/`. Core conventions:
+- `app/<route>/page.tsx` = a route's UI; `layout.tsx` = shared shell (persists across navigation);
+  `loading.tsx` = Suspense fallback; `error.tsx` (must be a Client Component) = error boundary;
+  `not-found.tsx` = 404. Route groups `(group)/` organize without affecting the URL.
+- Components are **Server Components by default**; add `"use client"` only where you need state, effects,
+  or browser APIs. Keep client components small + at the leaves.
+- Dynamic segments: `app/blog/[slug]/page.tsx` → `params.slug`. Use `generateStaticParams` for SSG.
+- Colocate components/tests next to routes; share UI via a top-level `components/`.
+
+Steps: confirm the route tree, create `page.tsx` (server) + a `layout.tsx` if shared, add
+`loading`/`error` where useful, wire links with `next/link`. Verify with `next build` / `next lint`.

package/skills/nextjs-data-fetching/SKILL.md

@@ -0,0 +1,16 @@
+---
+name: nextjs-data-fetching
+description: Fetch + cache data correctly in the Next.js App Router — static vs dynamic, fetch cache options, revalidation (ISR), tags, and Suspense streaming. Use when adding/fixing data loading or stale data.
+---
+
+Fetch directly in Server Components (`const data = await fetch(...)` / DB call). Control caching:
+- `fetch(url)` is cached by default. Opt out per-request with `{ cache: "no-store" }` (dynamic) or set
+  time-based ISR with `{ next: { revalidate: 60 } }`. Tag for on-demand invalidation:
+  `{ next: { tags: ["posts"] } }` → later `revalidateTag("posts")`.
+- Route-level: `export const revalidate = 60` (ISR) or `export const dynamic = "force-dynamic"`.
+- Parallelize independent fetches (`Promise.all`) to avoid request waterfalls. Use `generateStaticParams`
+  for SSG of dynamic routes.
+- Stream slow data: wrap in `<Suspense fallback={...}>` so the shell renders immediately.
+
+Diagnose stale/slow data: check the cache option + revalidate, confirm tags are invalidated on mutation,
+and look for accidental waterfalls. Verify with `next build` (it prints which routes are static/dynamic).

package/skills/nextjs-env-config/SKILL.md

@@ -0,0 +1,18 @@
+---
+name: nextjs-env-config
+description: Manage environment variables + config safely in Next.js — .env files, NEXT_PUBLIC_ exposure rules, server-only secrets, runtime vs build-time, typed env. Use when adding config/keys or fixing "undefined env".
+---
+
+Env rules that prevent leaks and "undefined in the browser":
+- Files: `.env.local` (local secrets, gitignored), `.env` (defaults, committed if non-secret),
+  `.env.production`. NEVER commit real secrets.
+- **Exposure**: only vars prefixed `NEXT_PUBLIC_` are sent to the browser (inlined at build). Everything
+  else is **server-only** — reading a non-public var in a Client Component yields `undefined`. Keep API
+  keys server-side (Server Components, Route Handlers, Server Actions).
+- Public vars are inlined at BUILD time → rebuild after changing them. Server vars are read at runtime.
+- Validate at startup with zod (a small `env.ts` that parses `process.env`) so missing/invalid config
+  fails fast with a clear message instead of a runtime `undefined`.
+- Mark server-only modules with `import "server-only"`.
+
+Fix "undefined env": confirm the prefix (needs `NEXT_PUBLIC_` for client), the file is loaded, and you
+rebuilt. Verify with a typed `env.ts` that throws on missing keys.

package/skills/nextjs-metadata-seo/SKILL.md

@@ -0,0 +1,17 @@
+---
+name: nextjs-metadata-seo
+description: Add SEO + social metadata in the Next.js App Router — the Metadata API, dynamic generateMetadata, Open Graph/Twitter cards, sitemap & robots. Use for titles, descriptions, sharing previews, indexing.
+---
+
+Use the **Metadata API** (no manual `<head>` tags):
+- Static: `export const metadata: Metadata = { title, description, openGraph, twitter }` in a
+  `layout.tsx` or `page.tsx`. Use a title template in the root layout:
+  `title: { default: "Site", template: "%s · Site" }`.
+- Dynamic: `export async function generateMetadata({ params }): Promise<Metadata>` — fetch and build
+  per-page title/description/OG image.
+- Social images: `opengraph-image.tsx` (or `.png`) in a route generates the OG card; same for
+  `twitter-image`. Use `next/og` `ImageResponse` for dynamic cards.
+- Indexing: `app/sitemap.ts` (export default returning the URL list) and `app/robots.ts`.
+- Set `metadataBase` in the root layout so relative OG image URLs resolve.
+
+Verify: view source for correct `<title>`/`og:` tags; test the OG card with a preview tool.

package/skills/nextjs-middleware/SKILL.md

@@ -0,0 +1,18 @@
+---
+name: nextjs-middleware
+description: Add Next.js middleware (middleware.ts) for auth gating, redirects/rewrites, headers, and edge logic that runs before a request completes. Use for protecting routes, A/B, locale, or setting headers.
+---
+
+`middleware.ts` at the project root runs on the Edge before matched requests. Keep it FAST and light
+(no heavy deps, no DB) — it's on the hot path.
+
+- Export `middleware(req: NextRequest)` returning `NextResponse.next()`, `.redirect(url)`,
+  `.rewrite(url)`, or a response with headers/cookies set.
+- Scope it with `export const config = { matcher: ["/dashboard/:path*"] }` so it only runs where needed
+  (exclude `_next`, static assets).
+- **Auth gating**: read the session cookie/token, redirect unauthenticated users to `/login`. Do a cheap
+  presence/JWT check here; do full verification in the page/handler.
+- Also good for: setting security headers, locale/geo rewrites, maintenance mode, simple A/B.
+
+Verify: hit a protected route logged-out (should redirect) and logged-in (should pass); confirm the
+matcher doesn't accidentally run on assets.

package/skills/nextjs-performance/SKILL.md

@@ -0,0 +1,17 @@
+---
+name: nextjs-performance
+description: Optimize a Next.js app's performance — next/image, next/font, dynamic import/code-splitting, bundle analysis, reducing client JS, Core Web Vitals. Use when the app is slow, heavy, or has layout shift.
+---
+
+High-leverage Next.js performance moves:
+- **Images**: use `next/image` (auto resize/lazy/AVIF); always set width/height (or `fill`) to avoid CLS;
+  add `priority` to the LCP image.
+- **Fonts**: `next/font` (self-hosted, zero layout shift) instead of `<link>` to Google Fonts.
+- **Less client JS**: keep components as Server Components; move `"use client"` to leaves; `dynamic(() =>
+  import(...), { ssr: false })` for heavy/below-the-fold client widgets.
+- **Data**: parallelize fetches, cache/ISR appropriately (see nextjs-data-fetching), stream slow parts
+  with Suspense.
+- **Bundle**: run the analyzer (`@next/bundle-analyzer`) to find big deps; replace/trim them.
+
+Process: measure first (Lighthouse / `next build` output / analyzer), fix the biggest offenders (LCP
+image, fonts, oversized client bundles), re-measure. Target good LCP/CLS/INP.

package/skills/nextjs-route-handler/SKILL.md

@@ -0,0 +1,18 @@
+---
+name: nextjs-route-handler
+description: Build a Next.js API endpoint with App Router Route Handlers (app/api/.../route.ts) — GET/POST/etc, request parsing, JSON/streaming responses, status codes. Use for backend endpoints/webhooks.
+---
+
+Create `app/api/<name>/route.ts` exporting async functions named for HTTP methods (`GET`, `POST`, `PUT`,
+`DELETE`, `PATCH`). Use the Web `Request`/`Response` (and `NextRequest`/`NextResponse` for helpers).
+
+Patterns:
+- Read input: `await req.json()`, `req.nextUrl.searchParams`, headers via `req.headers`.
+- Respond: `NextResponse.json(data, { status })`. Set proper status codes (400 bad input, 401/403 auth,
+  404, 500). Validate input (zod) before use.
+- Dynamic: `app/api/items/[id]/route.ts` → second arg `{ params }`.
+- Caching: route handlers are dynamic by default for non-GET; force with `export const dynamic =
+  "force-dynamic"` / `revalidate`. For streaming, return a `ReadableStream` with the right headers.
+- Webhooks: read the RAW body for signature verification before parsing.
+
+Verify: hit it with curl, check status + shape; add error handling so failures return clean JSON, not 500 HTML.

package/skills/nextjs-server-actions/SKILL.md

@@ -0,0 +1,17 @@
+---
+name: nextjs-server-actions
+description: Implement Next.js Server Actions for mutations and forms (no manual API route) — "use server", form actions, validation, revalidation, optimistic UI. Use for create/update/delete from the UI.
+---
+
+Server Actions run on the server and are callable from components/forms without a separate API route.
+
+- Define with `"use server"` (top of file for a module of actions, or inline in a Server Component).
+- Wire to a form: `<form action={myAction}>`; read `FormData` in the action. Or call from a Client
+  Component (e.g. inside a transition). Actions must be async and take serializable args.
+- ALWAYS validate input server-side (zod) and check authz — actions are public endpoints.
+- After a mutation, call `revalidatePath("/path")` or `revalidateTag("tag")` so the UI reflects new data;
+  or `redirect()` to navigate.
+- UX: use `useFormStatus` for pending state and `useOptimistic` for optimistic updates in client forms.
+
+Steps: write the action (validate → mutate → revalidate/redirect), bind it to the form, add pending +
+error states. Verify the mutation persists and the page refreshes without a full reload.

package/skills/nextjs-server-components/SKILL.md

@@ -0,0 +1,18 @@
+---
+name: nextjs-server-components
+description: Decide and implement Server vs Client Components correctly in Next.js — minimize client JS, keep data/secrets on the server. Use when a component needs state/effects, or when trimming bundle size.
+---
+
+Default to **Server Components**. Reach for `"use client"` ONLY when the component needs: useState/
+useReducer, useEffect/lifecycle, event handlers, browser-only APIs, or a client-only library.
+
+Rules that prevent the common mistakes:
+- Server Components can be async and fetch data directly (DB, secrets, `fetch`) — never ship secrets to
+  the client. Client Components cannot be async and must not import server-only code.
+- Push `"use client"` to the LEAVES. A server parent can render client children and pass
+  serializable props (no functions/Dates that don't serialize). Pass Server Components to client ones
+  via `children`/slots instead of importing them inside client code.
+- Shared server-only utilities: mark with `import "server-only"` so they can't leak into client bundles.
+
+When converting: split the interactive bit into a small `"use client"` component, keep data-fetching +
+composition in the server parent. Verify the client bundle didn't balloon (`next build` output).

package/skills/power-ui/SKILL.md

@@ -0,0 +1,40 @@
+---
+name: power-ui
+description: Design and build a genuinely premium UI — the kind that looks shipped by a top product team. Use for new screens/components, redesigns, or when a UI "works but looks generic". Produces a small design system + polished, accessible, responsive implementation.
+---
+
+You are an elite product designer-engineer. Your job is to make interfaces that feel **considered,
+calm, and premium** — not generic framework defaults. Taste is the deliverable. Work in the user's
+existing stack; if none, default to clean semantic HTML + CSS (no heavy UI kit unless asked).
+
+## Operating procedure
+1. **Understand the job.** One line: who uses this, the one primary action, the emotional tone
+   (e.g. trustworthy / playful / serious). If unclear, ask ONE question, then proceed.
+2. **Establish the system before the screen.** Define tokens first — never hardcode scattered values:
+   - **Type scale** (modular, ~1.2–1.25 ratio), 2 weights max, generous line-height (1.5 body).
+   - **Spacing scale** (4px base: 4/8/12/16/24/32/48/64) — consistent rhythm everywhere.
+   - **Color**: one neutral ramp (bg/surface/border/text-muted/text) + ONE accent. Check contrast.
+   - **Radius + shadow**: one radius family, soft layered shadows (not a single harsh drop).
+   - **Motion**: 150–250ms ease-out for hover/enter; respect `prefers-reduced-motion`.
+3. **Layout with intent.** Strong grid, deliberate alignment, real whitespace. One clear visual
+   hierarchy (size → weight → color → position). Limit to ~2 emphasis levels per view.
+4. **Implement to a high bar.** Semantic HTML, keyboard-navigable, visible focus rings, ARIA where
+   needed, AA contrast, responsive (mobile-first, fluid type/space), empty/loading/error states.
+5. **Then polish — the 20% that signals quality:** optical alignment, hover/active/focus states on
+   every interactive element, micro-interactions, consistent icon weight, no orphan/overflow, dark
+   mode if the project has it. Pixel-check spacing.
+6. **Verify.** Build/lint it; if there's a browser tool, render and sanity-check layout + a11y.
+   Summarize the design decisions in 3–4 bullets (tokens, hierarchy, motion, accessibility).
+
+## Principles (Claude-grade taste)
+- Restraint > decoration. Remove before you add. White space is a feature.
+- Consistency is the whole game — reuse tokens; never one-off values.
+- Default state should be beautiful AND every state designed (hover/active/disabled/empty/error/loading).
+- Accessibility is not optional: contrast, focus, reduced-motion, semantics.
+- Performance is design: no layout shift, fast first paint, lightweight.
+
+## Anti-patterns to refuse
+- Center-everything with no hierarchy; rainbow palettes; 5 font weights; harsh pure-black shadows;
+  tiny low-contrast gray text; emoji as UI icons; copy-pasted Bootstrap look; motion that can't be disabled.
+
+Deliver the tokens + component/screen + a short rationale. Make it look like it shipped.

package/skills/pr/SKILL.md

@@ -0,0 +1,38 @@
+---
+name: pr
+description: Open a clean GitHub pull request from the current changes — branch, commit, push, and create the PR with a strong title + body via the gh CLI. Use to ship a change for review.
+---
+
+# PR: Ship a Pull Request
+
+## Goal
+Turn the working changes into one focused, reviewable PR with a body a reviewer can act on. Only do this
+when the user asked to ship.
+
+## Steps
+
+### 1. Branch
+If on the default branch (`main`/`master`), create a descriptive feature branch first:
+`git switch -c <type>/<short-desc>`. NEVER open a PR from the default branch.
+**Success criteria**: on a dedicated branch.
+
+### 2. Commit
+Review `git diff`, stage the relevant files (skip junk/secrets), and write a conventional commit
+(`feat:`/`fix:`/…) with a short **why**. Split unrelated concerns into separate commits.
+
+### 3. Push
+`git push -u origin <branch>`.
+
+### 4. Create the PR
+`gh pr create` with:
+- **Title**: conventional-commit style, concise.
+- **Body**: ## Summary (what + why) · ## Changes (bullets) · ## Testing (how you verified) · ## Risk /
+  rollout (migrations, flags, breaking changes). Link issues with `Closes #123`.
+**Success criteria**: a reviewer could understand and verify the change from the body alone.
+
+### 5. Finish
+Output the PR URL. Do NOT merge unless asked.
+
+## Discipline
+One logical change per PR — if the diff spans unrelated concerns, propose splitting it. Confirm the
+target base branch if it's not obvious.

package/skills/refactor/SKILL.md

@@ -0,0 +1,40 @@
+---
+name: refactor
+description: Safely restructure code without changing behavior — extract, rename, dedupe, simplify, improve types — backed by tests. Use for "clean up", "refactor X", or reducing complexity in a module.
+---
+
+# Refactor: Behavior-Preserving Restructure
+
+## Goal
+Change structure, NOT behavior — safely and reversibly, with tests proving nothing changed.
+
+## Steps
+
+### 1. Pin behavior first
+Ensure tests exist and pass for the code you'll touch. If coverage is thin, add a characterization test
+that captures current behavior BEFORE refactoring — otherwise you can't prove you preserved it. Note the
+existing behavior/contract.
+**Success criteria**: a green test you can re-run after each change.
+
+### 2. One transformation at a time
+Apply a single named transformation, then run tests, then the next:
+- extract function/component/module
+- rename for clarity
+- remove duplication (DRY) — but only real, drift-prone duplication, not incidental similarity
+- simplify control flow (early returns, collapse nesting, guard clauses)
+- tighten types (replace `any`/stringly-typed with precise types/unions)
+- delete dead code
+**Success criteria**: tests green after EVERY step (so a regression is bisectable to one change).
+
+### 3. Match the codebase
+Follow existing patterns, naming, and file layout. A refactor that introduces a new style is just churn.
+
+### 4. Keep diffs reviewable
+Prefer the diff-based `edit` tool; avoid sweeping rewrites that obscure what actually changed.
+
+### 5. Verify
+Tests green + typecheck/lint clean + behavior identical. Run the build.
+
+## Discipline
+Refuse scope creep. If you spot a real bug, call it out SEPARATELY — don't silently "fix" it inside a
+refactor (that defeats the whole point of a behavior-preserving change and hides the fix from review).

package/skills/remember/SKILL.md

@@ -0,0 +1,39 @@
+---
+name: remember
+description: Save a durable fact to long-term memory (cross-session) — preferences, project facts, conventions, constraints. Dedupes against existing memory.
+---
+
+# Remember: Save to Long-Term Memory
+
+## Goal
+Capture something worth recalling in a FUTURE session as a concise, well-categorized fact — and avoid
+duplicating what's already stored.
+
+## Steps
+
+### 1. Distill the fact
+Reduce what the user wants remembered to ONE clear sentence. Strip the conversational framing — store the
+durable fact, not "the user said X today". Convert relative dates to absolute.
+**Success criteria**: a standalone sentence that makes sense with no other context.
+
+### 2. Categorize
+Tag it: `[identity]` / `[role]` / `[project]` / `[preference]` / `[constraint]` / `[interest]`, or
+`[style]` for tone/format preferences. Pick the single best fit.
+
+### 3. Scope it
+Decide if it's **global** (applies everywhere — who the user is, broad preferences) or **project-scoped**
+(this repo's conventions, current work). Store with the right scope so recall surfaces it in the right
+places.
+
+### 4. Dedupe + write
+Check existing memory first. If a similar fact exists, UPDATE it rather than adding a duplicate; if a new
+fact contradicts an old one, replace the old. Otherwise add it to the modelcode memory store
+(`~/.modelcode/memory.db`, FTS5).
+**Success criteria**: exactly one current entry per fact, no duplicates.
+
+### 5. Confirm
+State what was saved (and its category/scope) in one line.
+
+## Don't store
+Secrets, anything already obvious from the repo/CLAUDE.md, or session-only context that won't matter next
+time. When unsure whether something is durable, ask rather than cluttering memory.

package/skills/review/SKILL.md

@@ -0,0 +1,22 @@
+---
+name: review
+description: Review the pending diff for correctness, security, and design issues. Delegates to the code-reviewer subagent; can apply agreed fixes.
+---
+
+# Review: Diff Code Review
+
+## Phase 1: Scope
+Run `git diff` and `git diff --staged` for the working tree. If the user named a branch/PR, use
+`git diff <base>...HEAD`. If there are no changes, review the files edited earlier in this conversation.
+**Success criteria**: you have the complete diff to review.
+
+## Phase 2: Review
+Delegate to the **code-reviewer** subagent with the full diff (and enough surrounding context that
+changes are judged in context, not in isolation). For a large/sensitive change, also run the
+**security-auditor** subagent in parallel.
+
+## Phase 3: Report (and optionally fix)
+Present findings grouped by severity (CRITICAL → HIGH → MEDIUM → LOW → NIT), each with `file:line`, the
+concrete trigger scenario, and the fix. End with the verdict (✅ ready / ⚠️ fix HIGH+CRITICAL first /
+❌ not ready). If the user passed `--fix`, apply the agreed fixes with `edit` after showing them, skip
+false positives without arguing, then re-run the build/tests to confirm.

package/skills/security-review/SKILL.md

@@ -0,0 +1,21 @@
+---
+name: security-review
+description: Security review of the pending changes (or a target path) — finds exploitable vulnerabilities with attack scenarios. Delegates to the security-auditor subagent.
+---
+
+# Security Review
+
+## Phase 1: Scope the attack surface
+Get the diff (`git diff` / `git diff --staged`) or the target path. Identify where untrusted input
+enters and what sensitive actions/data the changes can reach.
+**Success criteria**: you know the entry points and sinks touched by the change.
+
+## Phase 2: Audit
+Delegate to the **security-auditor** subagent with the diff + context. It traces tainted data
+source→sink and checks: injection (SQL/shell/path/template), authn/authz + IDOR, secrets handling,
+SSRF, unsafe deserialization, crypto misuse, input limits/DoS, supply chain, and web vulns (XSS/CSRF).
+
+## Phase 3: Report
+Group by severity (CRITICAL → HIGH → MEDIUM → LOW/INFO). Per finding: `file:line`, the concrete
+**attack scenario** (steps/payload), the **impact**, and the **fix**. Flag only real, exploitable
+issues — no theoretical noise. If the user asks, apply the remediations with `edit` after showing them.

package/skills/simplify/SKILL.md

@@ -0,0 +1,47 @@
+---
+name: simplify
+description: Clean up the changed code for reuse, quality, and efficiency — no bug hunting, no behavior change. Launches parallel review agents, then applies the fixes.
+---
+
+# Simplify: Code Review and Cleanup
+
+Review all changed files for reuse, quality, and efficiency, then fix what's found. Do NOT change
+behavior and do NOT hunt for bugs (that's `/review`).
+
+## Phase 1: Identify changes
+Run `git diff` (and `git diff --staged`). If there are no git changes, review the files you edited
+earlier in this conversation or that the user named.
+**Success criteria**: you have the full diff in context.
+
+## Phase 2: Review in parallel (three angles)
+Launch three **subagent** reviews concurrently (one message), passing each the full diff:
+
+### Agent 1 — Reuse
+1. Search for existing utilities/helpers that could replace newly written code (utility dirs, shared
+   modules, files adjacent to the change).
+2. Flag any new function duplicating existing functionality → name the existing one to use.
+3. Flag inline logic that should use an existing util (hand-rolled string/path handling, ad-hoc env
+   checks, custom type guards).
+
+### Agent 2 — Quality
+1. Redundant state (duplicates existing state, derivable cached values, effects that could be direct calls).
+2. Parameter sprawl (new params instead of restructuring).
+3. Copy-paste with slight variation → unify with a shared abstraction.
+4. Leaky abstractions / broken encapsulation.
+5. Stringly-typed code where a constant/union/branded type already exists.
+6. Unnecessary nesting/wrappers that add no value.
+7. Unnecessary comments — narrating WHAT or the change/task → delete; keep only non-obvious WHY.
+
+### Agent 3 — Efficiency
+1. Unnecessary work (redundant compute, repeated reads, duplicate calls, N+1).
+2. Missed concurrency (independent ops run sequentially).
+3. Hot-path bloat (new blocking work in startup / per-request / per-render).
+4. Recurring no-op updates in loops/intervals → add a change-detection guard.
+5. Existence pre-checks before operating (TOCTOU) → operate and handle the error.
+6. Memory: unbounded structures, missing cleanup, listener leaks.
+7. Overly broad ops (reading whole files / loading all when one is needed).
+
+## Phase 3: Apply
+Aggregate the findings and fix each directly with `edit`, matching surrounding style. If a finding is a
+false positive or not worth it, skip it — don't argue. Re-run the build/tests if behavior could be
+affected (it shouldn't be). Summarize what you simplified.