vybekiit 0.4.0 → 0.6.0

package/dist/global-skills/web-to-native/references/native-patterns.md

@@ -0,0 +1,39 @@
+# Native patterns: redesigning web UX for native
+
+Disclosed reference for [`web-to-native`](../SKILL.md), step 4. `false-friends.md` translates *idioms* (`div` → `View`); this translates *UX patterns* — a web interaction into its native equivalent. Step 4 isn't a port, it's this redesign.
+
+**Reach for `@expo/ui` first.** It renders real SwiftUI (iOS) and Jetpack Compose (Android), so its components look and feel *exactly* like the OS — the difference between "native-ish RN" and "indistinguishable from an app Apple/Google shipped." See the `expo-ui` skill. Drop to styled RN primitives only for what `@expo/ui` doesn't cover: custom layouts (chat bubbles, bespoke cards) and **large data lists** (`@expo/ui` `List` is a JS-thread node per item — use `FlashList`/`FlatList` for feeds). `@expo/ui` runs in **Expo Go** (SDK 56+) — no dev build needed; reach for a dev build (the `expo-dev-client` skill) only for *custom* native modules.
+
+| Web pattern | Native redesign — reach for first | Why |
+|---|---|---|
+| Top tab bar / nav links | **NativeTabs** — bottom, liquid glass on iOS 26 (`building-native-ui`) | Thumb-reachable, OS-native bar |
+| Page header / breadcrumb | **large-title** Stack header + header **search field** (`building-native-ui`) | The native screen frame |
+| In-page tabs / toggle group | **SegmentedControl** — `@expo/ui` (`community/segmented-control`) | Native segmented switch |
+| Modal / dialog | **BottomSheet** — `@expo/ui` | Sheets *are* the native modal |
+| `<select>` / dropdown | **Picker**, or long-press **MenuView** — `@expo/ui` (`community/menu`) | Native wheel / menu, no popover |
+| Accordion / "show more" | **Collapsible** — `@expo/ui` | Native disclosure |
+| Settings / short list | **List** + **FieldGroup** rows (Switch / Picker / TextInput) — `@expo/ui` | The Settings-app look |
+| Data feed / table / long list | **FlashList** / `FlatList`, virtualized + momentum | Tables don't exist on mobile; `@expo/ui` `List` isn't for big data |
+| Checkbox / toggle | **Switch** (on/off) or **Checkbox** (multi-select) — `@expo/ui` | Native control, not a styled box |
+| Date / time input | **DateTimePicker** — `@expo/ui` (`community/datetime-picker`) | Native wheel / calendar |
+| Range slider | **Slider** — `@expo/ui` | |
+| Onboarding / carousel / swipe pages | **PagerView** — `@expo/ui` (`community/pager-view`) | Native paging, not a scroll strip |
+| Refresh button / auto-poll | pull-to-refresh (`RefreshControl`) | The native refresh gesture |
+| Hover menu / tooltip | long-press **MenuView** context menu — `@expo/ui` (`community/menu`) | No hover on touch |
+| Toast / snackbar | native banner + **haptic** (`expo-haptics`) | |
+| Buttons | `@expo/ui` **Button**; `Pressable` for custom | Native press + haptics |
+| Multi-column layout | single column + tabs / stack | One thing at a time on a phone |
+
+**The test:** if a screenshot of the native screen could pass for the web version, you reskinned it. Redesign until it could pass for a screen the OS shipped.
+
+## Feel — beyond the components
+
+The table gets the right *components*; "native" also lives in *motion and touch* — and a web port arrives with almost none, so you must add it. The tooling is all in `building-native-ui`; reach for it, don't hand-roll:
+
+- **Transitions for free** — use Expo Router's native-stack so push/pop, modals, and sheets animate with real platform physics; shared-element zoom via `building-native-ui` `zoom-transitions.md`.
+- **Motion** — Reanimated (`withSpring`/`withTiming`; `entering`/`exiting` for list items) + `react-native-gesture-handler` for swipes/drags → `building-native-ui` `animations.md`.
+- **Touch** — `expo-haptics` on commits, selection changes, and pull-to-refresh — choreography, not just a toast buzz.
+- **Native rhythm** — large-title collapse on scroll, momentum / inverted scroll, a keyboard that pushes content (`KeyboardAvoidingView`).
+- **Respect reduced motion** — gate non-essential animation on Reanimated's `useReducedMotion()`.
+
+**Feel can't be screenshotted.** A janky transition or wrong easing passes a still-image parity check and still betrays the app — for screens with motion, verify with a short recording (iOS `xcrun simctl io booted recordVideo feel.mov`; Android `adb shell screenrecord`; or a device-agent flow), not just a screenshot.

package/dist/global-skills/web-to-native/references/run-as-goal.md

@@ -0,0 +1,48 @@
+# Run the migration as a goal loop
+
+Disclosed reference for [`web-to-native`](../SKILL.md) — the recommended way to drive the whole migration. The migration is a repeat-until-done loop (assess → nativize each screen → verify → check off), which is exactly the shape of a **goal loop**: a single objective re-injected every turn until the worklist is empty. This file carries a ready-shaped, migration-specific objective — and, crucially, the objective **re-reads this skill every iteration**, so the loop keeps following the playbook (and self-bootstraps the assess step if no worklist exists yet).
+
+Use it in one of two modes depending on the agent you're running.
+
+## Mode A — the agent can run a goal loop
+
+Harnesses with a goal/loop command (Claude Code `/goal`, Codex CLI, or any harness of the same shape) can drive this themselves. Fill the template below and hand it to that command — the loop re-runs it until `migration-progress.md` has no unchecked nativize-now items.
+
+## Mode B — the agent can't loop itself
+
+Write the filled-in objective to `migration-goal.md` in the project, then give the user the one-line instruction to launch it (e.g. *"run your agent's goal loop with the objective in `migration-goal.md`"*). The objective is plain text and portable, so the user runs it in whatever harness they have.
+
+## The objective (template)
+
+Fill the two `<…>` slots, then run or hand off verbatim. It is written to survive re-injection — it restates its own worklist, direction, and stop condition every turn.
+
+```
+Goal: migrate <APP NAME> from web to a native Expo app by following the web-to-native skill, one screen per iteration, until done.
+
+Each iteration, FIRST re-read the playbook — plugins/expo/skills/web-to-native/SKILL.md (and its references) — then:
+1. If migration-progress.md doesn't exist yet, do the skill's step 1 (Assess) to
+   create the worklist, then stop. Otherwise open it and take the top unchecked
+   item under "nativize-now"; if none are left unresolved (every nativize-now is
+   done or blocked), STOP and summarize what shipped + what's blocked and why.
+2. Redesign that screen native per the skill's step 4 — reach for @expo/ui FIRST
+   (real SwiftUI/Compose), then building-native-ui (NativeTabs, large titles);
+   RN primitives only for custom layouts. NEVER a webview port.
+   Use references/native-patterns.md (UX patterns) and references/false-friends.md
+   (idioms). Match the web screen's content and behavior.
+3. Verify per references/verify-on-device.md: compare the running web original
+   (browser agent) against the native screen (simulator / argent) — content and
+   behavior parity, NOT pixels (it should look more native). If it's off for reasons
+   IN the code, fix it this iteration. If it's blocked by something OUTSIDE the code
+   (missing backend/auth/data, or a secret you can't supply), don't loop — mark it
+   blocked in step 4 and move on.
+4. Check the item off in migration-progress.md, appending one line:
+   "<screen> — done", or "<screen> — blocked: <reason> — needs <what would unlock>".
+   Either way the item is resolved; never revisit a blocked one.
+
+Rules: one screen per pass; the app builds green each iteration; @expo/ui before RN primitives; never touch "nativize-later" items.
+Base API URL for native (no relative paths): <EXPO_PUBLIC_API_URL>
+```
+
+## Why a pre-shaped objective
+
+The objective is filled in for this migration — worklist, redesign rules, and self-verification path already wired to the skill's references — so you can launch the loop without authoring one from scratch. Tailor the `<…>` slots and direction when a specific migration needs more than the template covers.

package/dist/global-skills/web-to-native/references/verify-on-device.md

@@ -0,0 +1,45 @@
+# Verify a migrated screen against the running web app
+
+Disclosed reference for [`web-to-native`](../SKILL.md), steps 3–4. Verification means **running both apps and comparing the same screen** — the native port beside the web original. A clean compile or a green `expo export` proves nothing — a screen can build and still render blank or mis-render. This parity check is the gate the strangle loop runs each iteration.
+
+Two agents drive it, and this skill is **opinionated**: it requires both and installs them rather than falling back to manual screenshots.
+
+- **Web side — `agent-browser`** (vercel-labs, a Rust browser CLI): `open <url>`, `snapshot --json` (accessibility tree with refs), `screenshot <path>`, `read` (rendered DOM/text).
+- **Native side — `argent`** (`@swmansion/argent`): drives the simulator — `describe` (a11y tree), `debugger-component-tree` (RN tree), `gesture-tap`/`keyboard`, `flow` to record a check and replay it each pass. Invoke as `argent run <tool> --udid <udid>` (get the udid from `argent run list-devices`).
+
+## Setup — install if missing (don't skip, don't fall back to manual)
+
+Check both are on PATH; if either is absent, ask the user, then install before proceeding:
+
+```bash
+which agent-browser || (npm i -g agent-browser && agent-browser install)   # web agent (+ its Chrome)
+which argent        || npm i -g @swmansion/argent                          # device agent
+```
+
+## The workflow
+
+**A. Capture the web original** with agent-browser — the source of truth for parity. Run the web app (its `pnpm dev` server, or the **deployed URL** if local setup needs DB/auth env), then:
+
+```bash
+agent-browser open "<web-url>/<route>?<params>"
+agent-browser snapshot --json      # structure to diff
+agent-browser screenshot web.png   # visual reference
+```
+
+**Tip:** capture web baselines for every screen once, up front, then diff against them instead of re-opening the web app each iteration.
+
+**B. Capture the native screen** (iOS shown via `simctl`; Android note below):
+1. Run the app: `npx expo start --ios` (Expo Go). On **SDK 56+ both `@expo/ui` and DOM components run in Expo Go** — no dev build, no `react-native-webview` to install; reach for a dev build (the `expo-dev-client` skill) only for *custom* native modules. Stale-bundle trap: a CI-mode Metro + cached Expo Go can show an old build — terminate Expo Go and add `--clear` if a change doesn't appear.
+2. Boot a sim: `xcrun simctl boot <udid>` (`xcrun simctl list devices available`); `open -a Simulator`.
+3. Open the route: deep-link `xcrun simctl openurl booted "exp://<lan-ip>:8081/--/<route>?<params>"`, or argent `launch-app` + `gesture-tap`.
+4. Capture: `xcrun simctl io booted screenshot native.png`, or `argent run describe --udid <udid>` for structure.
+
+> **Android:** `simctl` / `expo run:ios` are iOS-only. Use an Android emulator + `adb` — `adb exec-out screencap -p > native.png`, `adb shell am start -a android.intent.action.VIEW -d "<deep-link>"`, `adb shell screenrecord` for motion — or `npx expo run:android` for a dev build.
+
+**C. Compare** the two for the same route — layout, content, behavior. Diff the structures (agent-browser `snapshot` against argent `describe` / `debugger-component-tree`), not just pixels. Pass only on parity: same data, and params passed into a DOM webview must produce the same result.
+
+**Feel needs motion, not a still.** For a nativized screen with transitions, gestures, or haptics, a screenshot can't catch a janky push or wrong easing — capture a short recording (iOS `xcrun simctl io booted recordVideo feel.mov`; Android `adb shell screenrecord`; or an argent flow) and confirm it moves like a native app (see `native-patterns.md` → Feel).
+
+## What "pass" looks like
+- **DOM-shelled screen (step 3):** the web UI renders inside the native header/shell; params from the native route drive it the same as on web.
+- **Nativized screen (step 4):** native primitives only, no webview; matches the web original screen.

package/dist/global-skills/wire-auth/SKILL.md

@@ -0,0 +1,28 @@
+---
+name: wire-auth
+description: people can sign in through this API (mobile/extension clients call these routes). Use when the builder says something like: sign in; log in; create accounts; add users; wire auth.
+metadata:
+  vybekiit-generated: buyer-skill-stub
+---
+
+<!-- vybekiit:generated:buyer-skill-stub -->
+
+# Skill: wire-auth
+
+**Goal:** people can sign in through this API (mobile/extension clients call these routes).
+
+
+**Contract:** one action at a time · verify-before-advance · plain language (`language.md`) · translate every error · celebrate. Decide all technical choices yourself.
+
+## Steps
+
+1. Run `vybekiit plan-readiness sign-in backend` and follow any orchestration steps.
+2. Wire `@vybekiit/auth` via `resolveAuthProvider()` — routes live in `src/routes/auth.routes.ts`.
+3. **Verify:** POST `/api/auth/signin` returns a user and sets a session cookie.
+4. Tell the builder to point their app at `APP_URL` (e.g. `http://localhost:4000`).
+
+## After completing this skill
+
+Append one entry to `checklist.md` Decision log using `formatChecklistEntry({ from, to, because })`.
+
+If MCP or first debug fails once, run `vybekiit doc-fallback <tech-id>` and tell the builder only: *"I'm double-checking the official setup guide for this — hang tight, I'll have the next step in a moment."*

package/dist/global-skills/wire-database/SKILL.md

@@ -0,0 +1,28 @@
+---
+name: wire-database
+description: the server remembers things persistently. Use when the builder says something like: save my data; remember this; store info; add a database; wire database.
+metadata:
+  vybekiit-generated: buyer-skill-stub
+---
+
+<!-- vybekiit:generated:buyer-skill-stub -->
+
+# Skill: wire-database
+
+**Goal:** the server remembers things persistently.
+
+
+**Contract:** one action at a time · verify-before-advance · plain language (`language.md`) · translate every error · celebrate. Decide all technical choices yourself.
+
+## Steps
+
+1. Run `vybekiit plan-setup database` for the checklist.
+2. Run `vybekiit plan-data-model entities.json` (not eval from node_modules).
+3. Wire `@vybekiit/db` via `resolveDataProvider()`.
+4. **Verify:** save and read back a record.
+
+## After completing this skill
+
+Append one entry to `checklist.md` Decision log using `formatChecklistEntry({ from, to, because })`.
+
+If MCP or first debug fails once, run `vybekiit doc-fallback <tech-id>` and tell the builder only: *"I'm double-checking the official setup guide for this — hang tight, I'll have the next step in a moment."*

package/dist/global-skills/wire-email/SKILL.md

@@ -0,0 +1,27 @@
+---
+name: wire-email
+description: send emails from the API. Use when the builder says something like: send emails; email my users; set up email; wire email.
+metadata:
+  vybekiit-generated: buyer-skill-stub
+---
+
+<!-- vybekiit:generated:buyer-skill-stub -->
+
+# Skill: wire-email
+
+**Goal:** send emails from the API.
+
+
+**Contract:** one action at a time · verify-before-advance · plain language (`language.md`) · translate every error · celebrate. Decide all technical choices yourself.
+
+## Steps
+
+1. Run `vybekiit plan-setup email`.
+2. Wire `@vybekiit/email` when available.
+3. **Verify:** test email sends.
+
+## After completing this skill
+
+Append one entry to `checklist.md` Decision log using `formatChecklistEntry({ from, to, because })`.
+
+If MCP or first debug fails once, run `vybekiit doc-fallback <tech-id>` and tell the builder only: *"I'm double-checking the official setup guide for this — hang tight, I'll have the next step in a moment."*

package/dist/global-skills/wire-payments/SKILL.md

@@ -0,0 +1,27 @@
+---
+name: wire-payments
+description: the API can process payments for mobile/extension clients. Use when the builder says something like: add payments; take money; sell something; charge people; wire payments.
+metadata:
+  vybekiit-generated: buyer-skill-stub
+---
+
+<!-- vybekiit:generated:buyer-skill-stub -->
+
+# Skill: wire-payments
+
+**Goal:** the API can process payments for mobile/extension clients.
+
+
+**Contract:** one action at a time · verify-before-advance · plain language (`language.md`) · translate every error · celebrate. Decide all technical choices yourself.
+
+## Steps
+
+1. Run `vybekiit plan-setup payments`.
+2. Wire `@vybekiit/payments` checkout routes.
+3. **Verify:** practice checkout completes.
+
+## After completing this skill
+
+Append one entry to `checklist.md` Decision log using `formatChecklistEntry({ from, to, because })`.
+
+If MCP or first debug fails once, run `vybekiit doc-fallback <tech-id>` and tell the builder only: *"I'm double-checking the official setup guide for this — hang tight, I'll have the next step in a moment."*

package/dist/global-skills/workers-best-practices/SKILL.md

@@ -0,0 +1,127 @@
+---
+name: workers-best-practices
+description: Reviews and authors Cloudflare Workers code against production best practices. Load when writing new Workers, reviewing Worker code, configuring wrangler.jsonc, or checking for common Workers anti-patterns (streaming, floating promises, global state, secrets, bindings, observability). Biases towards retrieval from Cloudflare docs over pre-trained knowledge.
+---
+
+Your knowledge of Cloudflare Workers APIs, types, and configuration may be outdated. **Prefer retrieval over pre-training** for any Workers code task — writing or reviewing.
+
+## Retrieval Sources
+
+Fetch the **latest** versions before writing or reviewing Workers code. Do not rely on baked-in knowledge for API signatures, config fields, or binding shapes.
+
+| Source | How to retrieve | Use for |
+|--------|----------------|---------|
+| Workers best practices | Fetch `https://developers.cloudflare.com/workers/best-practices/workers-best-practices/` | Canonical rules, patterns, anti-patterns |
+| Workers types | See `references/review.md` for retrieval steps | API signatures, handler types, binding types |
+| Wrangler config schema | `node_modules/wrangler/config-schema.json` | Config fields, binding shapes, allowed values |
+| Cloudflare docs | Search tool or `https://developers.cloudflare.com/workers/` | API reference, compatibility dates/flags |
+
+## FIRST: Fetch Latest References
+
+Before reviewing or writing Workers code, retrieve the current best practices page and relevant type definitions. If the project's `node_modules` has an older version, **prefer the latest published version**.
+
+```bash
+# Fetch latest workers types
+mkdir -p /tmp/workers-types-latest && \
+  npm pack @cloudflare/workers-types --pack-destination /tmp/workers-types-latest && \
+  tar -xzf /tmp/workers-types-latest/cloudflare-workers-types-*.tgz -C /tmp/workers-types-latest
+# Types at /tmp/workers-types-latest/package/index.d.ts
+```
+
+## Reference Documentation
+
+- `references/rules.md` — all best practice rules with code examples and anti-patterns
+- `references/review.md` — type validation, config validation, binding access patterns, review process
+
+## Rules Quick Reference
+
+### Configuration
+
+| Rule | Summary |
+|------|---------|
+| Compatibility date | Set `compatibility_date` to today on new projects; update periodically on existing ones |
+| nodejs_compat | Enable the `nodejs_compat` flag — many libraries depend on Node.js built-ins |
+| wrangler types | Run `wrangler types` to generate `Env` — never hand-write binding interfaces |
+| Secrets | Use `wrangler secret put`, never hardcode secrets in config or source |
+| wrangler.jsonc | Use JSONC config for non-secret settings — newer features are JSON-only |
+
+### Request & Response Handling
+
+| Rule | Summary |
+|------|---------|
+| Streaming | Stream large/unknown payloads — never `await response.text()` on unbounded data |
+| waitUntil | Use `ctx.waitUntil()` for post-response work; do not destructure `ctx` |
+
+### Architecture
+
+| Rule | Summary |
+|------|---------|
+| Bindings over REST | Use in-process bindings (KV, R2, D1, Queues) — not the Cloudflare REST API |
+| Queues & Workflows | Move async/background work off the critical path |
+| Service bindings | Use service bindings for Worker-to-Worker calls — not public HTTP |
+| Hyperdrive | Always use Hyperdrive for external PostgreSQL/MySQL connections |
+
+### Observability
+
+| Rule | Summary |
+|------|---------|
+| Logs & Traces | Enable `observability` in config with `head_sampling_rate`; use structured JSON logging |
+
+### Code Patterns
+
+| Rule | Summary |
+|------|---------|
+| No global request state | Never store request-scoped data in module-level variables |
+| Floating promises | Every Promise must be `await`ed, `return`ed, `void`ed, or passed to `ctx.waitUntil()` |
+
+### Security
+
+| Rule | Summary |
+|------|---------|
+| Web Crypto | Use `crypto.randomUUID()` / `crypto.getRandomValues()` — never `Math.random()` for security |
+| No passThroughOnException | Use explicit try/catch with structured error responses |
+
+## Anti-Patterns to Flag
+
+| Anti-pattern | Why it matters |
+|-------------|----------------|
+| `await response.text()` on unbounded data | Memory exhaustion — 128 MB limit |
+| Hardcoded secrets in source or config | Credential leak via version control |
+| `Math.random()` for tokens/IDs | Predictable, not cryptographically secure |
+| Bare `fetch()` without `await` or `waitUntil` | Floating promise — dropped result, swallowed error |
+| Module-level mutable variables for request state | Cross-request data leaks, stale state, I/O errors |
+| Cloudflare REST API from inside a Worker | Unnecessary network hop, auth overhead, added latency |
+| `ctx.passThroughOnException()` as error handling | Hides bugs, makes debugging impossible |
+| Hand-written `Env` interface | Drifts from actual wrangler config bindings |
+| Direct string comparison for secret values | Timing side-channel — use `crypto.subtle.timingSafeEqual` |
+| Destructuring `ctx` (`const { waitUntil } = ctx`) | Loses `this` binding — throws "Illegal invocation" at runtime |
+| `any` on `Env` or handler params | Defeats type safety for all binding access |
+| `as unknown as T` double-cast | Hides real type incompatibilities — fix the design |
+| `implements` on platform base classes (instead of `extends`) | Legacy — loses `this.ctx`, `this.env`. Applies to DurableObject, WorkerEntrypoint, Workflow |
+| `env.X` inside platform base class | Should be `this.env.X` in classes extending DurableObject, WorkerEntrypoint, etc. |
+
+## Review Workflow
+
+1. **Retrieve** — fetch latest best practices page, workers types, and wrangler schema
+2. **Read full files** — not just diffs; context matters for binding access patterns
+3. **Check types** — binding access, handler signatures, no `any`, no unsafe casts (see `references/review.md`)
+4. **Check config** — compatibility_date, nodejs_compat, observability, secrets, binding-code consistency
+5. **Check patterns** — streaming, floating promises, global state, serialization boundaries
+6. **Check security** — crypto usage, secret handling, timing-safe comparisons, error handling
+7. **Validate with tools** — `npx tsc --noEmit`, lint for `no-floating-promises`
+8. **Reference rules** — see `references/rules.md` for each rule's correct pattern
+
+## Scope
+
+This skill covers Workers-specific best practices and code review. For related topics:
+
+- **Durable Objects**: load the `durable-objects` skill
+- **Workflows**: see [Rules of Workflows](https://developers.cloudflare.com/workflows/build/rules-of-workflows/)
+- **Wrangler CLI commands**: load the `wrangler` skill
+
+## Principles
+
+- **Be certain.** Retrieve before flagging. If unsure about an API, config field, or pattern, fetch the docs first.
+- **Provide evidence.** Reference line numbers, tool output, or docs links.
+- **Focus on what developers will copy.** Workers code in examples and docs gets pasted into production.
+- **Correctness over completeness.** A concise example that works beats a comprehensive one with errors.

package/dist/global-skills/workers-best-practices/references/review.md

@@ -0,0 +1,174 @@
+# Code Review — Workers
+
+How to review Workers code for type correctness, API usage, config validity, and best practices. This is self-contained — do not assume access to other skills.
+
+## Retrieval
+
+Prefer retrieval over pre-training. Types, config schemas, and APIs change with compatibility dates and new bindings.
+
+### Workers types
+
+Fetch the latest `@cloudflare/workers-types` before reviewing. The project may have an older version installed.
+
+```bash
+mkdir -p /tmp/workers-types-latest && \
+  npm pack @cloudflare/workers-types --pack-destination /tmp/workers-types-latest && \
+  tar -xzf /tmp/workers-types-latest/cloudflare-workers-types-*.tgz -C /tmp/workers-types-latest
+# Types are at /tmp/workers-types-latest/package/index.d.ts
+```
+
+Search this file for the specific type, class, or interface under review. Do not guess type names.
+
+Alternative: `npx wrangler types` generates a typed `Env` interface from the local wrangler config.
+
+Fallback: read `node_modules/@cloudflare/workers-types/index.d.ts`. Note the installed version.
+
+### Wrangler config schema
+
+The authoritative schema is bundled with wrangler as `config-schema.json` (JSON Schema draft-07).
+
+```bash
+# Read from local node_modules
+cat node_modules/wrangler/config-schema.json
+```
+
+Do not guess field names or structures — look them up.
+
+### Cloudflare docs
+
+Use the Cloudflare docs search tool if available, or fetch from `https://developers.cloudflare.com/workers/`. The best practices page lives at `/workers/best-practices/workers-best-practices/`.
+
+---
+
+## Type Validation
+
+### Env interface
+
+- Every binding must have a specific type. Flag `any`, `unknown`, `object`, or `Record<string, unknown>` on bindings.
+- Binding types that accept generic parameters (Durable Object namespaces, Queues, Service bindings for RPC) must include them. Read the type definition to confirm which types are generic.
+- Binding names must match the wrangler config exactly.
+- Prefer generated types from `wrangler types` over hand-written interfaces.
+
+### Handler and class signatures
+
+Verify against current type definitions — do not assume signatures are stable.
+
+- Correct import path (most Workers platform classes import from `"cloudflare:workers"`)
+- Generic type parameter on base classes (e.g., `DurableObject<Env>`)
+- Binding access pattern: `env.X` in module export handlers, `this.env.X` in classes extending platform base classes
+- `ExecutionContext` as the third param in module export handlers (needed for `ctx.waitUntil()`)
+- `fetch()` handlers must return `Promise<Response>`
+
+### Binding access — the most common error
+
+- **Module export handlers** (`fetch`, `scheduled`, `queue`, `email`): bindings via `env.X` parameter
+- **Platform base classes** (`WorkerEntrypoint`, `DurableObject`, `Workflow`, `Agent`): bindings via `this.env.X`
+
+Flag `env.X` inside a class extending a platform base class. Flag `this.env.X` inside a module export handler.
+
+### Type integrity rules
+
+| Rule | Detail |
+|------|--------|
+| No `any` | Never on binding types, handler params, or API responses |
+| No double-casting | `as unknown as T` hides real incompatibilities — fix the underlying design |
+| Justify suppressions | `@ts-ignore`/`@ts-expect-error` must include a comment explaining why |
+| Prefer `satisfies` | Use `satisfies ExportedHandler<Env>` over `as` — validates without widening |
+| Validate, do not assert | Schema or type guard for untyped data (JSON, parsed bodies), not `as` |
+
+### Stale class patterns
+
+Old patterns survive in codebases long after APIs change.
+
+- **`extends` vs `implements`**: platform classes use `extends`, not `implements`. The `implements` pattern is legacy and loses `this.ctx`, `this.env`.
+- **Import paths**: verify module specifiers match what types actually export. Common mistake: wrong path for `"cloudflare:workers"` vs `"cloudflare:workflows"`.
+- **Renamed properties**: e.g., `this.state` to `this.ctx` in Durable Objects. Search types to confirm.
+- **Constructor signatures**: base class constructors change. Verify expected parameters.
+
+---
+
+## Config Validation
+
+### Required fields
+
+For executable examples, verify: `name`, `compatibility_date`, `main`. Check the schema for current required fields.
+
+### Config format
+
+- **JSONC** (`wrangler.jsonc`) — preferred for new projects
+- **JSON** (`wrangler.json`) — valid but no comments
+- **TOML** (`wrangler.toml`) — legacy; acceptable in existing content, flag in new projects
+
+### Binding-code consistency
+
+1. Every `env.X` reference in code has a corresponding binding declaration in config
+2. Every binding in config is referenced in code (warn on unused)
+3. Names match exactly (case-sensitive)
+4. For Durable Objects: `class_name` matches the exported class name
+
+### Common config mistakes
+
+| Check | What to look for |
+|-------|-----------------|
+| Stale `compatibility_date` | Should be recent; use `$today` placeholder in docs |
+| Missing DO migrations | Every new DO class needs a migration entry |
+| Binding name mismatch | Config `binding`/`name` must match `env.X` in code |
+| Secrets in config | Never in `vars` — use `wrangler secret put` |
+| Wrong binding key | Verify top-level key name against the schema |
+| Missing entrypoint | `main` required for executable Workers |
+
+---
+
+## Anti-Patterns to Flag
+
+See the full anti-patterns table in `SKILL.md`. The type-specific ones to watch for during review:
+
+- **`any` on `Env` or handler params** — defeats type safety for all downstream binding access
+- **`as unknown as T`** — hides real type incompatibilities; fix the underlying design
+- **`@ts-ignore`/`@ts-expect-error` without explanation** — masks errors silently; require a justifying comment
+- **`implements` instead of `extends` on platform base classes** — legacy pattern; loses `this.ctx`, `this.env`
+- **`env.X` inside class body** — should be `this.env.X` in platform base classes
+- **`this.env.X` in module export handler** — should be `env.X` parameter
+- **Non-serializable values across boundaries** — `Response`, `Error` in step/queue compiles but fails at runtime
+
+---
+
+## Serialization Boundaries
+
+Data crossing these boundaries must be structured-clone serializable:
+
+- **Queue messages**: body passed to `.send()` or `.sendBatch()`
+- **Workflow step return values**: persisted to durable storage
+- **DO storage**: values in `storage.put()` or SQL
+- **`postMessage()`**: WebSocket messages
+
+Non-serializable types to flag: `Response`, `Request`, `Error`, functions, class instances with methods, `Map`/`Set`, `Symbol`.
+
+Valid: plain objects, arrays, strings, numbers, booleans, null, `ArrayBuffer`, `Date`.
+
+---
+
+## Review Process
+
+1. **Retrieve** — fetch latest workers types, wrangler schema, and best practices page
+2. **Read full files** — not just diffs; context matters for binding access patterns
+3. **Categorize code** — determines what to check:
+   - **Illustrative** (concept demo, comments for most logic): verify correct API names and realistic signatures
+   - **Demonstrative** (functional snippet, would work in context): verify syntax, correct APIs, correct binding access
+   - **Executable** (standalone, runs without modification): verify compiles, runs, includes imports and config
+4. **Check types** — binding access pattern, handler signatures, no `any`, no unsafe casts
+5. **Check config** — compatibility_date, nodejs_compat, observability, secrets, binding-code consistency
+6. **Check patterns** — streaming, floating promises, global state, serialization boundaries
+7. **Check security** — crypto usage, secret handling, timing-safe comparisons, error handling
+8. **Validate with tools** — `npx tsc --noEmit`, lint for `no-floating-promises`
+9. **Assess risk** — HIGH (auth, crypto, bindings), MEDIUM (business logic, config), LOW (style, comments)
+
+### Output format
+
+```
+**[SEVERITY]** Brief description
+`file.ts:42` — explanation with evidence
+Suggested fix: `code`
+```
+
+Severity: **CRITICAL** (security, data loss, crash) | **HIGH** (type error, wrong API, broken config) | **MEDIUM** (missing validation, edge case) | **LOW** (style, minor improvement)