firtoz

Fork and template gotchas (env import, routes, typegen, forms, D1, Turbo, HMR, new DO packages). Use when working on apps/web or durable-objects, or when behavior diverges from this stack’s conventions.

Repo-root commands, typegen and typecheck cadence, lint, deploy, adding packages with bun, and Alchemy app layout. Use at the start of a task, before PR, or when choosing turbo/typegen commands.

Turborepo task configuration patterns for monorepo management. Use when configuring turbo.json tasks, setting up task dependencies, managing cache inputs/outputs, or working with cross-package dependencies in the monorepo.

Alchemy + env files — repo-root `.env.local` (dev), `.env.staging` (staging / PR preview deploys), `.env.production` (prod / CI), optional per-package `.env.local`, and package-local Alchemy apps. Use when adding secrets or non-secret vars (must also update turbo.json globalEnv + deploy workflow env maps), or debugging missing env in local/CI/preview. Never use a plain `.env` file. `.env.example` is human documentation only — no script reads it for all keys.

React Router v8 routing patterns and environment variable configuration. Use whenever you touch React Router–related code (routes, links, params, loaders, actions, route config, middleware, or env in route context).

Auth worker setup for Better Auth, OAuth, admin bootstrap, and env/secrets. Use when configuring auth for a fork, setting redirect URIs, or debugging auth env.

Typed HTTP clients for Cloudflare service bindings — bindingHonoClient, WorkerBindingRegistry, Worker RPC with clientApp, HonoClientApp. Use when calling env.CHATROOM or any WorkerRef/BoundWorker over fetch with @firtoz/hono-fetcher, adding a worker Hono app RPC type, or fixing JsonResponse<any> / missing .delete on binding clients.

Component organization patterns for React applications. Use when creating components, organizing files, or structuring routes. ALWAYS keep 1 component per file and routes simple.

Add or change a Durable Object worker package under durable-objects/ (Alchemy, env.d.ts, Hono on the DO). Use when scaffolding with turbo gen durable-object, editing durable-objects/*/alchemy.run.ts, workers/app.ts, or env.d.ts for a DO. Not for web app bindings or cross-worker rpc—see cf-web-alchemy-bindings and cf-worker-rpc-turbo.

Socka + Durable Object WebSockets—defineSocka, SockaWebSocketDO, useSockaSession, SSR-safe ws URLs, web worker forwarding, live-draft vs commit, canvas/whiteboard acceptance, and pre-merge checks. Use for realtime features, /api/ws, or @firtoz/socka.

Wire @internal/web to durable-objects workers—workspace dep, alchemy.run.ts ReactRouter bindings, and env patterns. Use when adding `workspace:*` for a worker, editing apps/web/alchemy.run.ts, or debugging missing worker types after a new package.

workers/rpc.ts for WorkerRef or DO RPC types, package exports, cross-worker type imports without Turbo cycles, and root dev/destroy wiring. Use when adding WorkerRef, WorkerStub, workers/rpc.ts, turbo circular dependency warnings, or a new app missing from root bun run dev.

Alchemy + env files — repo-root `.env.local` (dev), `.env.staging` (staging / PR preview deploys), `.env.production` (prod / CI), optional per-package `.env.local`, and package-local Alchemy apps. Use when adding secrets or non-secret vars or debugging missing env in local dev. Never use a plain `.env` file. `.env.example` is human documentation only — no script reads it for all keys.

Component organization patterns for React applications. Use when creating components, organizing files, or structuring routes. ALWAYS keep 1 component per file and routes simple.

Guide for creating new Agent Skills when patterns emerge or improvements are needed. Use when encountering repeated patterns, making the same mistakes, discovering better approaches, or receiving user corrections. Covers keeping each skill small (one topic), when to split SKILL.md or add references/, and line-count heuristics.

Form submission patterns using useDynamicSubmitter, await submitJson, and formAction. Use when implementing forms, handling form submissions, or processing form data in React Router routes.

Standard Schema socka contracts (defineSocka), v1 wire envelopes, SockaSession/SockaWebSocketClient, React useSockaSession and SockaSessionProvider, SockaError.

SockaDoSession and SockaWebSocketDO on Cloudflare Durable Objects—contract, handlers, wireFormat, SockaError; extends websocket-do BaseSession.

Standard Schema v1 for socka contracts and wire validation—Zod, Valibot, or any compatible library; no Zod-only public surface.

Enforce strict TypeScript typing without escape hatches. Never use `any`, `as` casts to bypass the compiler, or similar workarounds—find the proper typed solution instead.

React Router v7 routing patterns and environment variable configuration. Use when adding routes, configuring routing, or setting up environment variables.

Read when implementing multi-phase work after a plan exists. Mandatory—mkdir+touch then Write/StrReplace (no heredocs), update the temp punch list at every phase boundary, one item at a time, per-phase tests. Complements punch-list-planning for authors.

Read when authoring implementation plans, phased roadmaps, or CreatePlan output for multi-step code work. Ensures the plan hands off a mandatory temp punch list and tells the executor which skill to follow.

Cloudflare Workers/Wrangler workflow for generating typed env bindings. NEVER manually edit worker configuration declaration files; always regenerate them via typegen.