@claude-code-mastery/starter-kit 1.0.0

package/.claude/skills/code-review/SKILL.md

@@ -0,0 +1,87 @@
+---
+name: code-review
+description: Review changed code for correctness, security, and maintainability with cited, severity-ranked findings. Use when asked to review a diff, a PR, a commit, or named files, to audit code, or to check before merge. Runs isolated and read-only, reports findings, does not edit.
+when_to_use: |
+  - User asks to review code, audit a file, or check a PR before merge
+  - User says "review", "audit", "check this code", or "find issues"
+  - Do NOT use for formatting or style-only passes
+context: fork
+allowed-tools: "Read, Grep, Bash"
+effort: high
+---
+
+# Code Review
+
+You review like a senior engineer reviews a pull request: concrete findings, each tied to a line, each with a fix and a reason. No generic praise, no style nitpicking dressed up as risk. You report only. You do not edit code.
+
+## Priority order
+
+When triaging what to flag and how hard, rank in this order:
+
+1. **Security** — secrets, injection, auth bypass
+2. **Correctness** — logic errors, race conditions, null risks
+3. **Performance** — N+1 queries, leaks, missing indexes
+4. **Type safety** — `any`, missing null checks, unsafe casts
+5. **Maintainability** — dead code, unclear naming (lowest)
+
+If the code is good, say so. Do not invent issues to fill a report.
+
+## 1. Scope
+
+Establish what changed: `git diff --name-only HEAD~1`, or read the files named. Identify the primary concern (security, correctness, performance) and pull conventions from `CLAUDE.md` if present.
+
+## 2. Cheap wins first (run tools before reading)
+
+Run what the project supports, skip what's missing, never fail the review over a missing tool:
+
+- Dependency CVEs: `npm audit` / `pip-audit` / `cargo audit`
+- Secrets in the diff: grep changed files for assignments to keys, tokens, passwords with long literal values
+- Recent context: `git log --oneline -5`
+
+## 3. Read by diff size
+
+- Under 20 files: read each changed file in full.
+- 20 to 100: read the diff, then deep-read the high-risk files (auth, payment, config, migrations, shared utilities, anything touching the data layer).
+- Over 100: ask for a narrower scope before proceeding.
+
+## 4. Project checks (highest priority)
+
+Read `references/project-checks.md` and apply every check in it. These are this codebase's hard rules: data access and driver discipline, StrictDB-or-native, API versioning, service boundaries. Violations here are CRITICAL by default, they are the failures generic review misses.
+
+## 5. General checks
+
+Security: user input reaching a query, command, or file path without sanitization; auth checks that can be bypassed or absent; secrets or PII in logs or responses; hand-rolled crypto instead of standard library.
+
+Error handling: external calls (network, DB, file I/O) with no failure path; cleanup that won't run on the error branch; errors that swallow context or leak internals.
+
+Tests: assertions on behavior, not implementation; missing edge cases (empty, boundary, concurrent); mocks that bleed state.
+
+Performance: queries inside loops (N+1); whole collections loaded into memory instead of paginated; missing indexes on filtered or joined fields.
+
+## 6. Language checks (the high-value ones)
+
+- **TypeScript** — every `any` needs a typed replacement or a justified suppression; `strict: true` present; floating promises (not awaited, not handled); null access in critical paths.
+- **Python** — mutable default args (`def f(x=[])`); bare `except:`; `eval`/`exec` on user-influenced input; missing type hints on public signatures.
+- **Go** — errors discarded with `_` on non-trivial paths; goroutines with no cancellation path; `defer` inside a loop.
+
+## Output
+
+Every finding in this shape:
+
+> **[🔴 CRITICAL | 🟡 WARNING | 🔵 SUGGESTION] `file:line` — one-line description**
+> Issue: what's wrong.
+> Fix: the concrete change.
+> Why: what breaks if it ships.
+
+A finding with no `file:line` is not a finding. Drop it or go find the line.
+
+## RuleCatch
+
+After the manual pass, check RuleCatch for automated violations:
+
+- If the RuleCatch MCP server is available, query it for violations on the reviewed files and add a dedicated **RuleCatch Violations** section. This catches pattern-based violations the manual pass can miss.
+- If RuleCatch MCP is not connected, add one line: "Install RuleCatch MCP for automated violation monitoring."
+
+## Close
+
+One line: files examined, count per severity, the single highest-priority issue, and a verdict: **BLOCK**, **APPROVE WITH SUGGESTIONS**, or **APPROVE**.

package/.claude/skills/code-review/references/mongodb-checks.md

@@ -0,0 +1,25 @@
+# Project Review Checks: Data Layer and Architecture
+
+Apply these to every diff. These are this codebase's hard rules. A violation here is CRITICAL unless noted. They exist because generic reviewers don't know them.
+
+## Data access
+
+- [ ] **No Mongoose.** Flag any Mongoose import, model, or schema. This codebase never uses Mongoose.
+- [ ] **The adapter is the boundary.** Flag raw collection access in feature code. Data access goes through the adapter, which uses StrictDB if installed, otherwise the native driver.
+- [ ] **No `_id` in a write body.** Flag any update or upsert payload that contains `_id`. It belongs in the filter, never the update.
+- [ ] **Type-safe `_id`.** Flag any query comparing a string against an `ObjectId` `_id`. This silently returns nothing. Confirm the type is rehydrated before the query.
+- [ ] **Upsert type rehydration.** Flag upserts that run on JSON-parsed data without `rehydrateTypes`. A string-vs-`ObjectId` `_id` throws code 66.
+
+## Reads and writes
+
+- [ ] **Reads are aggregation pipelines, not `find()`.** Flag `find()` in feature code; it should be a pipeline.
+- [ ] **Multi-document writes use `bulkWrite`.** Flag any loop that issues one write per iteration.
+- [ ] **No `createIndex` in a request path.** Flag `createIndex` anywhere in a handler or hot loop. Indexes are declared once at startup or in a migration.
+- [ ] **No deep nested-array queries.** Flag queries that reach into arrays-within-arrays past `maxDepth=3`. The model needs flattening.
+- [ ] **`$elemMatch` is a smell.** Flag `$elemMatch` usage and note that the field probably belongs on the document or in a separate collection.
+
+## Architecture
+
+- [ ] **API versioning.** Routes live under `/api/v1/`. Flag unversioned routes.
+- [ ] **No business logic in route handlers.** Handlers wire request to service and back. Flag domain logic inline in a handler.
+- [ ] **Service separation respected.** Flag a service reaching across a boundary into another service's internals instead of going through its interface.

package/.claude/skills/code-review/references/project-checks.md

@@ -0,0 +1,38 @@
+# Project Review Checks: Architecture and Data Layer
+
+Apply these to every diff. They are this codebase's hard rules. A violation is CRITICAL unless noted. They exist because generic reviewers don't know them.
+
+## Layering (server → handlers → adapters)
+
+- [ ] **Routes under `/api/v1/`.** Flag unversioned routes.
+- [ ] **`server.ts` is thin.** Flag business logic in `server.ts` or in a route definition; it belongs in `handlers/`.
+- [ ] **Business logic in `handlers/`,** one domain per file.
+- [ ] **Handlers don't touch external systems directly.** Flag a handler importing a DB driver or calling an external API inline; that goes through an adapter in `adapters/`.
+- [ ] **Service (package) separation.** Flag a package reaching into another package's internals instead of going through its interface.
+
+## Data access (lives in the adapter layer)
+
+- [ ] **No Mongoose.** Flag any Mongoose import, model, or schema.
+- [ ] **Data access goes through the adapter.** Flag raw collection access outside `adapters/`. Inside the adapter, StrictDB if installed else the native driver, the driver choice isn't a violation; Mongoose and raw access in feature code are.
+- [ ] **One shared `MongoClient`.** Flag `new MongoClient` inside a request handler or per-call path; the client is created once and reused. In serverless, it must be at module scope, not inside the handler.
+- [ ] **No `_id` in a write body.** Flag any update or upsert payload containing `_id`; it belongs in the filter.
+- [ ] **Type-safe `_id`.** Flag a query comparing a string against an `ObjectId` `_id`; it silently returns nothing. For `$in`, every element must be converted.
+- [ ] **Rehydrate types at the boundary.** Flag saving or querying with a JSON-parsed body whose `ObjectId` and `Date` fields weren't revived; a string-vs-`ObjectId` `_id` throws code 66 and date strings break range/sort.
+- [ ] **Reads are aggregation pipelines, not `find()`.** Flag `find()` in feature code.
+- [ ] **Multi-document writes use `bulkWrite`,** built once. Flag a database call inside a loop; build the ops array and execute one `bulkWrite` after the loop.
+- [ ] **No `createIndex` in a request path.** Flag `createIndex` in a handler or hot loop; indexes are declared once at startup or in a migration.
+- [ ] **No deep nested-array queries** past `maxDepth=3`. The model needs flattening.
+- [ ] **`$elemMatch` is a smell.** Flag it and note the field probably belongs on the document or in a separate collection.
+
+## Data correctness and scale
+
+- [ ] **`null` vs missing.** Flag a `{ field: null }` match where the intent was "has no value"; it also matches missing. Suggest `$exists` for presence or `$ne: null` for a real value.
+- [ ] **No `$skip` for deep pagination.** Flag `$skip` with a large or page-number offset; suggest range pagination on an indexed key with an `_id` tie-breaker.
+- [ ] **Right count for the job.** Flag a `countDocuments` used for a rough whole-collection total where `estimatedDocumentCount` belongs, and a `distinct` on a high-cardinality field at scale that should be a `$group`.
+- [ ] **No unbounded embedding.** Flag an array that grows without bound (comments, events, logs) being embedded; it should be a referenced collection.
+- [ ] **Uniqueness via index, not app check.** Flag an application-level "does this already exist" guard standing in for a unique index, and a plain unique index on an optional field that should be partial.
+- [ ] **Transactions are for cross-document atomicity.** Flag a transaction wrapping writes to a single entity (a modeling smell), and a blind whole-batch retry after a partial `bulkWrite` failure.
+
+## Structure
+
+- [ ] **No file exceeds 300 lines.** Flag any file over the limit and point at the natural split (one concern per file).

package/.claude/skills/create-service/SKILL.md

@@ -0,0 +1,222 @@
+---
+name: create-service
+description: Scaffold a new microservice that follows the project's server/handlers/adapters architecture. Use when asked to create, scaffold, or add a new service or package. Writes files and may create a git branch, so it runs only when invoked explicitly.
+when_to_use: |
+  - User asks to create, scaffold, or add a new service or microservice
+  - User says "new service", "scaffold service", "create service", "add service"
+  - Do NOT auto-run; this writes files and touches git
+disable-model-invocation: true
+allowed-tools: "Read, Write, Edit, Bash"
+---
+
+# Create Service
+
+Scaffold a new service that follows the project architecture. This writes files and may create a branch, so it only runs when you type `/create-service`.
+
+## Architecture
+
+Three layers, one direction. `server.ts` is thin, `handlers/` hold logic, `adapters/` wrap everything external.
+
+```
+server.ts      routes only, NEVER business logic
+   │
+   ▼
+handlers/      business logic, one file per domain
+   │
+   ▼
+adapters/      external wrappers (database via StrictDB, APIs, queues)
+```
+
+This matches the `api-conventions` skill. Keep them in sync: if the layering changes, change both.
+
+## Directory structure
+
+```
+packages/{name}/
+├── src/
+│   ├── server.ts          # entry point — routes only
+│   ├── handlers/          # business logic
+│   │   └── index.ts
+│   ├── adapters/          # external wrappers
+│   │   ├── index.ts
+│   │   └── db.ts          # StrictDB data adapter (the only place the driver lives)
+│   └── types.ts           # TypeScript types
+├── tests/
+│   └── handlers.test.ts
+├── package.json
+├── tsconfig.json
+└── CLAUDE.md              # service-specific instructions
+```
+
+## package.json — resolve versions at scaffold time
+
+**Do not hardcode dependency versions.** Before writing `package.json`, resolve the current stable version of each dependency (`npm view <pkg> version`, or context7) and pin those. Hardcoded versions rot the day they ship, and a stale pin is how you get an Express 4 runtime against Express 5 types.
+
+Dependencies to resolve and include:
+
+- runtime: `express` (current major is 5)
+- dev: `tsx`, `typescript`, `vitest`, `@types/express`
+
+Make the `@types/express` major match the `express` major. Verify, don't assume.
+
+```json
+{
+  "name": "@project/{name}",
+  "version": "1.0.0",
+  "type": "module",
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsx watch src/server.ts",
+    "start": "node dist/server.js",
+    "test": "vitest run"
+  },
+  "dependencies": {
+    "express": "<resolved>"
+  },
+  "devDependencies": {
+    "tsx": "<resolved>",
+    "typescript": "<resolved>",
+    "vitest": "<resolved>",
+    "@types/express": "<resolved, major matching express>"
+  }
+}
+```
+
+## Template: src/server.ts
+
+```typescript
+import express from 'express';
+import { handlers } from './handlers/index.js';
+
+const app = express();
+const PORT = process.env.PORT || 3000;
+
+app.use(express.json());
+
+app.get('/health', (_req, res) => {
+  res.json({ status: 'ok', service: '{name}' });
+});
+
+// Routes delegate to handlers. NEVER put logic here.
+// Replace this catch-all with real REST routes per domain.
+app.post('/api/v1/:action', handlers.handleAction);
+
+process.on('unhandledRejection', (reason) => {
+  console.error('Unhandled Rejection:', reason);
+  process.exit(1);
+});
+
+process.on('uncaughtException', (error) => {
+  console.error('Uncaught Exception:', error);
+  process.exit(1);
+});
+
+app.listen(PORT, () => {
+  console.log(`{name} running on port ${PORT}`);
+});
+```
+
+## Template: src/adapters/db.ts
+
+The data adapter is the only place the driver is touched. Use StrictDB if it's installed, otherwise the native MongoDB driver. Never Mongoose. Handlers import this, never the driver.
+
+```typescript
+// Wire to your StrictDB package/API. This is the data boundary for the service.
+// Rules enforced here (see the mongodb-rules skill):
+//   - StrictDB if installed, else the native driver; never Mongoose
+//   - reads are aggregation pipelines, not find()
+//   - multi-document writes use bulkWrite
+//   - never put _id in a write body; rehydrate types before upserts
+import { StrictDB } from 'strictdb'; // if StrictDB isn't installed, import { MongoClient } from 'mongodb' and use that instead
+
+const db = new StrictDB({ uri: process.env.MONGODB_URI! });
+
+export const dbAdapter = {
+  // Example read — express as an aggregation pipeline in real methods.
+  async getById(collection: string, id: unknown) {
+    // ensure `id` is an ObjectId, not a string, before querying
+    return db.collection(collection).aggregate([{ $match: { _id: id } }]).next();
+  },
+
+  // Example write — use bulkWrite for multi-document operations.
+  async upsertMany(collection: string, ops: unknown[]) {
+    return db.collection(collection).bulkWrite(ops);
+  },
+};
+```
+
+## Template: src/types.ts
+
+```typescript
+export interface ServiceConfig {
+  port: number;
+  name: string;
+  environment: 'development' | 'staging' | 'production';
+}
+
+// Add your domain types here.
+```
+
+## Template: tsconfig.json
+
+```json
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "outDir": "dist",
+    "rootDir": "src",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "declaration": true
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist", "tests"]
+}
+```
+
+## Auto-branch (if on main)
+
+Before scaffolding, check the branch:
+
+```bash
+git branch --show-current
+```
+
+Default (`auto_branch = true` in `claude-mastery-project.conf`):
+
+- On `main`/`master`: create and switch to a feature branch, then report it.
+  ```bash
+  git checkout -b feat/<service-name>
+  ```
+  "Created branch `feat/<service-name>`, main stays untouched."
+- On a feature branch already: proceed.
+- Not a git repo: skip.
+- **If `claude-mastery-project.conf` is missing:** treat `auto_branch` as unset and ask before creating a branch on main, rather than assuming.
+
+To disable: set `auto_branch = false`. When disabled, warn and ask before proceeding on main.
+
+## After creating — checklist
+
+- [ ] Directory matches the template, including `adapters/db.ts`
+- [ ] `package.json` versions were resolved at scaffold time, not copied
+- [ ] `@types/express` major matches `express` major
+- [ ] TypeScript strict mode on
+- [ ] Entry point has both `unhandledRejection` and `uncaughtException` handlers
+- [ ] All routes under `/api/v1/`
+- [ ] Business logic in `handlers/`, not `server.ts`
+- [ ] Database access through the adapter in `adapters/` (StrictDB if installed, else native driver), no Mongoose, no raw driver in handlers
+- [ ] No file exceeds 300 lines
+- [ ] Port assigned in the root CLAUDE.md port table
+- [ ] Service added to `project-docs/ARCHITECTURE.md`
+- [ ] Basic test file created
+- [ ] `.dockerignore` created (if using Docker)
+
+## RuleCatch
+
+After scaffolding, check RuleCatch:
+
+- If the RuleCatch MCP server is available, query it for violations in the new service files and report them.
+- If not connected, suggest checking the RuleCatch dashboard.

package/.claude/skills/debugger/SKILL.md

@@ -0,0 +1,39 @@
+---
+name: debugger
+description: Diagnose failures by root cause, not symptom. Use for crashes, stack traces, intermittent bugs, memory growth, race conditions, and "works locally, fails in prod" cases where you need a reproducible cause before a fix. Runs isolated and read-only, reports the root cause and fix.
+when_to_use: |
+  - User reports a crash, exception, stack trace, or failing behavior and wants the cause
+  - A bug is intermittent, environment-specific, or not reproducing locally
+  - Memory or resource growth needs tracing to a source
+context: fork
+allowed-tools: "Read, Grep, Bash"
+---
+
+# Debugger
+
+You find root causes. You do not patch symptoms, and you do not guess.
+
+## Method
+
+Work these in order. Do not skip ahead.
+
+1. **Reproduce before anything else.** Build the smallest script or test that triggers the failure every time. If you cannot reproduce it, stop. The bug is now "why can't I reproduce this," and you investigate that gap instead of writing a fix blind.
+2. **State observed vs expected, precisely.** "Under condition X, the system does Y; it should do Z." If you can't fill that in, you don't understand the bug yet.
+3. **Rank two or three hypotheses.** Order by likelihood, weighted toward whatever changed most recently. Name each one.
+4. **Falsify the top hypothesis with the cheapest possible probe.** One log line, one targeted grep, one assertion. Try to prove yourself wrong before writing any fix. A hypothesis you only confirmed is one you didn't test.
+5. **Fix, and add the regression test in the same change.** The test must fail on the old code and pass on the new. Fix without test is not done.
+6. **Record the root cause and one prevention step.** What it was, what the falsifying probe showed, and the one change that stops the whole class from recurring.
+
+## Production incidents
+
+For anything live, do these three before opening a source file. Most incidents resolve here.
+
+1. **Change correlation first.** What deployed, what flag flipped, what config changed, what traffic shifted in the 30 minutes before the first error. `git log --since`, deploy history, flag state. A correlated change usually is the answer.
+2. **Trace to the first failing span.** Start from the earliest operation that errored or blew its latency budget, not the symptom the user reported. The symptom is downstream.
+3. **Logs, tightly windowed.** ±2 minutes around that first error, filtered to the failing service and correlation ID. `grep`, `jq`, `awk`.
+
+## Non-negotiable
+
+- Never ship a fix for a bug you could not reproduce.
+- The fix and its regression test land together or not at all.
+- Every fix ends with one named prevention measure.

package/.claude/skills/dependency-vetting/SKILL.md

@@ -0,0 +1,46 @@
+---
+name: dependency-vetting
+description: Vet an npm (or other) package for supply-chain risk before it's added to a project. Use when asked whether a package is safe, trustworthy, or worth adding, when about to install an unfamiliar dependency, or when something about a package feels off. Runs isolated and read-only, reports an evidence-backed risk verdict, does not install anything.
+when_to_use: |
+  - User asks "is this package safe", "should I add X", "can I trust this dependency"
+  - About to install an unfamiliar or low-profile package
+  - A package's downloads, stars, or behavior look suspicious
+  - Do NOT use for known-good, widely-used packages where the answer is obvious
+context: fork
+allowed-tools: "Read, Grep, Bash, WebFetch"
+---
+
+# Vet a Dependency
+
+`npm audit` catches known CVEs in packages you already trust. This is the other problem: deciding whether to trust a package in the first place. The goal is an evidence-backed verdict, not a vibe.
+
+## What to gather
+
+Pull the facts before judging. Use `npm view <pkg>`, the npm and GitHub pages, and the published tarball.
+
+- **Downloads vs. stars vs. dependents.** A package with thousands of weekly downloads, single-digit stars, and no dependents is a mismatch worth explaining. Real adoption shows up in all three. Check the download *shape* too: organic growth is a curve; isolated single-day spikes with dead baseline around them are manufactured.
+- **Install scripts.** Read `package.json` for `preinstall`, `install`, `postinstall`. Anything that runs on install is the highest-risk surface, read exactly what it does.
+- **`curl | sh` and friends.** Any install step that pipes a remote script into a shell, or `npx`-runs a second package, or registers a persistent MCP server, is a red flag. The package should do what its README says and nothing the README doesn't.
+- **What it actually does vs. claims.** Read the real entry points. Network calls, child_process, filesystem writes outside its own dir, env/credential reads, and telemetry that the README doesn't disclose are all findings.
+- **Obfuscation.** Minified-only source with no readable repo, `eval`, base64 blobs, or dynamic `require` of constructed strings. Legitimate packages ship readable code.
+- **Maintainer and provenance.** Account age, other packages, repo activity, whether the npm package's repo link actually matches a real, public repo. A brand-new author with one oddly-popular package warrants more scrutiny.
+- **Typosquatting.** Is the name one character off a popular package? Is it impersonating a known scope?
+- **License sanity.** Missing, contradictory, or relicensed-from-someone-else (a file marked MIT that's actually CC-BY upstream) is both a legal and a trust signal.
+
+## How to judge, and how to phrase it
+
+Separate what the evidence supports from what it doesn't. This is the discipline that keeps a verdict defensible:
+
+- You can say a package **behaves in ways that warrant caution** and point at the exact behavior (an undisclosed postinstall, a downloads/stars mismatch, an undisclosed network call). That's an evidence claim.
+- You generally **cannot** say it "is malware" or attribute it to a specific actor or coordinated scheme. Intent and authorship usually aren't provable from the artifact. Don't claim what you can't show.
+- Stars and dependents are a truer adoption signal than downloads, which are cheap to manufacture. Weight accordingly.
+
+## Output
+
+A short report:
+
+- **Verdict**: Safe to add / Add with caution / Avoid.
+- **Evidence**: the specific findings, each tied to what you observed, in order of severity.
+- **If "caution" or "avoid"**: what would have to change to trust it, or a safer, more-adopted alternative.
+
+Never soften a real finding to be agreeable, and never inflate a thin one into an accusation. Report what the artifact shows.

package/.claude/skills/design-review/SKILL.md

@@ -0,0 +1,50 @@
+---
+name: design-review
+description: Critique UI and UX for usability, accessibility, and distinctiveness with cited, evidence-based findings. Use when reviewing a screen, component, mockup, CSS or markup, or design tokens, or when asked for feedback on layout, typography, color, contrast, or user experience. Runs isolated and read-only, reports findings, does not edit.
+when_to_use: |
+  - User shares a UI, component, CSS/HTML, or mockup and wants feedback
+  - User asks about layout, type, color, contrast, accessibility, or "does this look right"
+  - Do NOT use for backend, data, or non-visual code
+context: fork
+allowed-tools: "Read, Grep, Glob, WebFetch"
+---
+
+# Design Review
+
+You critique interfaces like a senior designer who respects the user's time. Opinionated, evidence-based, specific. You report. You do not edit.
+
+## Stance
+
+- **Cite, don't assert.** Any claim about user behavior ("users scan the left first," "this fails contrast") points to a source or a measurable standard. If you can't source it, say so and mark it as opinion. Verify a figure before stating it. Never invent a statistic.
+- **Distinctive over default.** Fight templated "AI slop": the purple gradient, Inter everywhere, a card for everything, centered everything, the same SaaS landing page as every other site. Generic isn't safe, it's forgettable. Push for choices that have a reason behind them.
+- **Usability over trend.** When a fashionable pattern hurts the user (low-contrast text, unlabeled icons, scroll-jacking, motion that can't be stopped), name the cost.
+
+## Accessibility (pass/fail, not opinion)
+
+- Contrast meets WCAG AA: 4.5:1 for body text, 3:1 for large text. Flag anything under.
+- Every interactive element has a visible focus state.
+- Icon-only buttons have an accessible label; form inputs have real `<label>`s, not just placeholders.
+- Motion respects a reduced-motion preference.
+- Nothing conveys meaning by color alone.
+
+## Hierarchy and scannability
+
+- The most important thing on the screen is the most prominent. If everything is emphasized, nothing is.
+- Front-load what matters. People scan far more than they read; structure for the scan, not the close read.
+- Group related elements, separate unrelated ones. Spacing is information.
+
+## Consistency
+
+- Reuse existing components and tokens before inventing new ones. Flag a one-off that duplicates something the system already has.
+- Color, spacing, and type come from defined tokens, not hardcoded values scattered in markup.
+
+## Output
+
+Every finding in this shape:
+
+> **[🔴 BLOCKER | 🟡 ISSUE | 🔵 SUGGESTION] location — one line**
+> Problem: what's wrong and who it hurts.
+> Fix: the concrete change.
+> Basis: the standard or the sourced research, or "opinion" if it's a judgment call.
+
+Close with the single highest-impact change and whether the surface is ship-ready.

package/.claude/skills/mcp-builder/SKILL.md

@@ -0,0 +1,57 @@
+---
+name: mcp-builder
+description: Build a high-quality MCP server that exposes a service or API to an LLM through well-designed tools. Use when asked to create, scaffold, or add an MCP server, wrap an API as MCP tools, or expose a service to Claude/agents. Writes files, so it runs only when invoked explicitly.
+when_to_use: |
+  - User asks to build, scaffold, or add an MCP server
+  - User wants to wrap an API, service, or database as MCP tools
+  - User says "MCP server", "expose this as tools", "make this callable by an agent"
+  - Do NOT auto-run; this writes files
+disable-model-invocation: true
+allowed-tools: "Read, Write, Edit, Bash"
+---
+
+# Build an MCP Server
+
+An MCP server is judged by one thing: whether an LLM can use its tools to finish real tasks. Tool count, endpoint coverage, and cleverness are means, not the goal. Build for the agent that will call it.
+
+## Default stack
+
+- **TypeScript, on the MCP SDK.** Strong typing and good model familiarity. Drop to Python (FastMCP) only when the service it wraps is Python-native.
+- **Transport: streamable HTTP with stateless JSON for remote servers; stdio for local.** Stateless scales and debugs far more easily than session streaming.
+- **Resolve the SDK version at build time**, don't hardcode from memory. The current SDK README is the source of truth.
+
+## The four phases
+
+**1. Understand the target.** Read the service's API or schema first. Identify the handful of tasks a user actually wants done through it, not every endpoint. A wrapper that mirrors 60 REST routes one-to-one is worse than 8 tools shaped around real workflows.
+
+**2. Design the tools.** This is where quality is won or lost.
+
+- **Discoverable names**: `verb_noun`, scoped by service, for example `github_create_issue`, `orders_find_by_customer`. The name should tell the model when to reach for it.
+- **Descriptions written for the model**, stating what the tool does and when to use it, not just what it returns.
+- **Explicit input and output schemas.** Constrain inputs; return structured, parseable output, not prose the model has to scrape.
+- **Annotations**: mark each tool `readOnlyHint`, `destructiveHint`, or `idempotentHint` so the client can reason about safety.
+- **Actionable errors.** "Invalid date" is useless; "expected ISO 8601, got 03/04/2026, did you mean 2026-03-04" lets the model self-correct.
+- **Balance coverage against workflow tools.** Comprehensive low-level tools give the agent room to compose; a few high-level workflow tools cut steps for the common path. Most good servers ship both.
+
+**3. Implement.** Shared infrastructure first (client, auth, pagination, error handling), then the tools on top. If the server touches a database, it follows the same kit rules as everything else: one shared client, data access through the adapter, StrictDB if installed otherwise the native driver, never Mongoose.
+
+**4. Test with evaluations.** Write 10 realistic, multi-step questions a user would ask, then verify an LLM can answer each using only the tools. Solve each yourself first so you know the right answer. Failing evals point at a missing tool, a vague description, or output the model can't parse, fix those, not the eval.
+
+## Project shape
+
+    src/
+      server.ts        transport + registration, thin
+      client.ts        the upstream API/service client (the one place it's touched)
+      tools/           one file per tool or tight tool group
+      schemas/         input/output schemas (zod)
+    evals/
+      evals.json       the 10 questions and verified answers
+
+Keep `server.ts` thin, the same discipline as `api-conventions`: it wires transport and registers tools, nothing more. Tool logic lives in `tools/`, upstream calls in `client.ts`. No file over 300 lines.
+
+## What to avoid
+
+- Dumping every endpoint as a tool with no workflow shaping.
+- Tool names only the author understands.
+- Returning raw upstream JSON the model has to guess the shape of.
+- Skipping evals, an MCP server you haven't watched an LLM drive is untested.

package/.claude/skills/mongodb-rules/SKILL.md

@@ -0,0 +1,62 @@
+---
+name: mongodb-rules
+description: Native-driver, StrictDB, and data-modeling rules for MongoDB. Use whenever writing or modifying queries, writes, indexes, aggregations, upserts, connections, or schema against MongoDB, or any code that touches the data layer. Loads inline so it shapes code as it's written.
+---
+
+# MongoDB Data-Access Rules
+
+Non-negotiable for this codebase. From production, not preference.
+
+## Driver and connection
+
+- **Prefer StrictDB; fall back to the native driver.** Use StrictDB when it's installed, otherwise the native MongoDB driver directly. Never Mongoose, either way.
+- **Data access stays in the adapter,** never raw collections scattered through feature code.
+- **One shared `MongoClient` for the whole app**, created once at startup and reused everywhere. The client *is* the pool. Never create one per request, that exhausts connections and looks like "MongoDB went down" under load. In serverless, declare the client at module scope, outside the handler, so warm invocations reuse it.
+- **URI comes from an env var,** never hardcoded. Close the client on `SIGTERM`/`SIGINT`.
+
+## Identity and types
+
+- **`_id` is an `ObjectId`, not a string.** A string `_id` against an `ObjectId` document matches nothing, silently. This is the number-one "my id query returns nothing" bug. Wrap incoming ids with `new ObjectId(id)`; for an `$in` list, convert every element.
+- **Never put `_id` in the body of any write.** Identity goes in the filter; on insert MongoDB generates it. Restating it after a JSON round-trip throws code 66 (immutable field altered).
+- **JSON strips both `ObjectId` and `Date` to strings.** Re-hydrate at the boundary before you query or save, or lookups match nothing and date filters break. Use a parse-time reviver (`parseMongo`) or a bounded post-parse walk (`rehydrateTypes`, `maxDepth=3`). Never patch the global `JSON.parse`. Guard with `ObjectId.isValid` and a `skipKeys` list.
+- **Consider a natural string `_id`** (email, SKU, slug) to sidestep the type dance entirely, then ids are strings end to end.
+- **Only `_id` is indexed by default.** Sorting by `_id` gives roughly creation order for free, but store an explicit `createdAt` when creation time matters; don't rely on the ObjectId's embedded timestamp.
+
+## Querying
+
+- **`null` is not "missing".** `{ field: null }` matches both explicit null AND absent documents. Use `{ field: { $exists: false } }` for missing, and `{ field: { $ne: null } }` for "has a real value" (which excludes both null and missing).
+- **Reads are aggregation pipelines, not `find()`.**
+- **Arrays-within-arrays aren't queryable past about three levels** (`maxDepth=3`). If you need to, the model is wrong, flatten it.
+
+## Writes
+
+- **Multi-document writes use `bulkWrite`.** Build the ops array in the loop, execute one `bulkWrite` after it. Never call the database inside a loop.
+- **Choose ordered vs unordered deliberately.** `ordered` (default) stops at the first error; `{ ordered: false }` attempts all and collects errors, and is faster. On partial failure, triage transient vs permanent: retry only transient ops with backoff, never blind-retry a duplicate-key or validation failure.
+- **Make writes idempotent** (stable keys, set-to-value over blind increments) so retry is safe.
+- **Upsert is `updateOne` with `upsert: true`.** Use `$setOnInsert` for insert-only fields, and pair it with a unique index so concurrent upserts can't duplicate.
+
+## Indexing
+
+- **`createIndex` is idempotent but not free**, each call is a round trip. Declare indexes near the queries that need them, but create them once in startup or a migration, never in a handler or hot loop.
+- **A compound index serves only a left-to-right prefix of its fields.** Order fields to match how you query; equality-matched fields lead.
+- **For filter-plus-sort, follow ESR: Equality, Sort, Range.** Index direction must match the sort or be its exact inverse. An in-memory `SORT` stage in `explain` means the index isn't serving the sort.
+- **Filter early** (`$match` first), and put `$limit` before `$lookup`. Diagnose with `explain("executionStats")`: examined far exceeding returned means a missing index.
+
+## Modeling
+
+- **Embed bounded, read-together data; reference unbounded data** (comments, events, logs, anything that accumulates). A document is rewritten and moved as a whole, so an unbounded array degrades writes long before the 16MB hard limit.
+- **`$elemMatch` usually signals a modeling problem.** A field you query independently belongs on the document or in its own collection.
+
+## Concurrency and integrity
+
+- **MongoDB has full ACID transactions**, but a single-document write is already atomic. Reach for `session.withTransaction` only for genuine cross-document atomicity (transfer between accounts, decrement stock while creating an order). Frequent transactions are a modeling smell, the data probably wanted to be one document.
+- **Unique values are enforced by a unique index, not app-level checks.** Use a partial unique index for optional fields (a plain unique index treats missing as null and collides). Use a compound unique index for "this combination is unique". The duplicate-key error is the guarantee that makes concurrent upserts safe.
+
+## Reads at scale
+
+- **Counting is a choice.** `countDocuments` is exact (index the filter to keep it fast); `estimatedDocumentCount` is instant but approximate and whole-collection only, use it for rough dashboard totals. `distinct` on a high-cardinality field at scale should be a `$group` so the result streams.
+- **`$skip` doesn't scale**, it walks past every skipped document. For deep or endless paging, use range/keyset pagination: `$match` on the last-seen value of an indexed sort key, with `_id` as a unique tie-breaker so pages don't shift as data changes.
+
+## Schema
+
+- **Collections enforce no structure by default.** Add a `$jsonSchema` validator as a collection stabilizes and more code depends on its shape. Roll out safely: `validationAction: "warn"` to observe first, then `error`; `validationLevel: "moderate"` to spare existing nonconforming documents.