> For the complete documentation index, see [llms.txt](https://www.turbostarter.dev/llms.txt). Prefer markdown by appending `.md` to documentation URLs or sending `Accept: text/markdown`. --- url: /edge/docs/installation/ai-development title: AI-assisted development description: Use Cursor, Claude Code, ChatGPT Codex, or Antigravity with Edge Kit. Rules, skills, and workflows for TanStack Start on Cloudflare Workers. --- Edge Kit includes pre-configured rules, skills, a subagent, and a command for AI coding assistants. They teach the model the stack that actually ships: TanStack Start, Kumo, Oxlint, and Cloudflare bindings. Most models still default to Next.js, ESLint, and barrel imports, and these files correct that before the first edit. Everything works out of the box with [Cursor](https://cursor.com), [Claude Code](https://claude.ai/code), [ChatGPT Codex](https://openai.com/codex), [Antigravity](https://antigravity.dev), and other tools that read [AGENTS.md](https://agents.md). Open the project and start coding. ## Structure AI configuration lives in a shared directory, with tool-specific folders pointing at it where a tool requires its own path: The `.agents/` directory holds the shared skills, commands, and agents. `.claude/agents` and `.claude/commands` are [symlinks](https://en.wikipedia.org/wiki/Symbolic_link) to those folders, so a new agent or command shows up in Claude as soon as you add the file. Each skill under `.claude/skills/` is its own symlink. Cursor and other tools that follow the Agent Skills layout read `.agents/skills/` and `AGENTS.md` from the repo root, so they do not need a second copy. `.cursor/environment.json` configures [Cursor Cloud agents](https://cursor.com/docs/cloud-agent). When `.env.local` is missing, `install.sh` writes it from your Cursor secrets: auth, email, Turnstile, and the web analytics token. Add Stripe keys yourself if you need billing. The install does not require Wrangler or a Cloudflare login unless the task deploys. Prefer the existing `dev` terminal (`pnpm dev` on port 3000). ## Rules Rules are persistent instructions the model reads when it needs project-specific guidance: conventions, layout, and workflows it cannot infer from the file tree. ### AGENTS.md `AGENTS.md` at the project root is the primary rules file. It uses the format recognized by [most](https://agents.md) AI coding tools. In Edge Kit it opens with the stack (TanStack Start, React 19, Kumo, Cloudflare Workers, a single package, Node 24 or newer) and then the things that break a build or a lint gate: ```md title="AGENTS.md" ## Gotchas **`@/*` is the only path alias.** `tsconfig.json` maps `@/*` to `./src/*`. There is no `#/*` alias. **`env.config.ts` sits outside `src/`.** Import it by relative path, with the `.ts` extension. **Two different things are called `env`.** Typed secrets come from `env.config.ts`. Cloudflare bindings come from `import { env } from "cloudflare:workers"`. **`pnpm lint` is also the type check.** Oxlint is type-aware. There is no `typecheck` script. **No literal strings in JSX.** `react/jsx-no-literals` is an error. User-facing copy goes through Paraglide. ``` The rest of the file covers: * **Commands** and the verify-before-you-finish sequence: `pnpm format:fix && pnpm lint && pnpm test`. Run `pnpm build` as well after route, SSR, or content-collection changes. * **Layout.** Infrastructure adapters live in `src/lib/`, one product capability lives in `src/modules//`, and `src/routes/` only composes URLs. The billing module is the reference: `*.server.ts` for D1, `*.functions.ts` for `createServerFn`, `*.queries.ts` for TanStack Query. * **Bindings.** D1, KV, R2, Queue, Flagship, Workers AI, email, and rate limiting are declared in `wrangler.jsonc`. Run `pnpm cf-typegen` after you change them. Binding IDs never go in `env.config.ts`. * **Don'ts.** No `#/` imports, no Node-only APIs, no KV as durable state or as a flag store, no Sentry or other APM (use `src/lib/log.ts`), no business logic in `src/routes/`, no hand-edited generated files (`src/routeTree.gen.ts`, `worker-configuration.d.ts`, `src/lib/i18n/`, `.content-collections/`, `src/db/schema/auth.ts`). It also points models at version-pinned guidance inside `node_modules`: TanStack Start's skill, and Kumo's component registry plus `USAGE.md`. Kumo's own docs show a barrel import from `@cloudflare/kumo`. This repo imports by subpath (`@cloudflare/kumo/components/button`) so the Worker bundle stays small. The rules say to ignore the barrel example. Rules should stay concise. Include only what the model **cannot infer from code alone**: * Bash commands and the verify sequence * Style rules that differ from defaults (Oxlint and Oxfmt, Paraglide, subpath imports) * Layout decisions (modules vs `src/lib` vs routes) * Gotchas such as the two `env` objects Keep rules short. Overly long files cause the model to ignore important instructions. If a rule is not being followed, the file might be too verbose. ### CLAUDE.md `CLAUDE.md` exists so Claude-specific tools load the same rules. It only references the main file: ```md title="CLAUDE.md" @AGENTS.md ``` That keeps one source of truth across tools. You can nest `AGENTS.md` files in subdirectories when one area needs tighter rules. For example, `src/modules/billing/` can document plan checks, and `src/lib/auth/` can document session middleware. The closer file generally wins for the code under it. Use nested files for domain rules, and keep shared conventions in the root file. Most tools also accept their own rules. Cursor rules go in `.cursor/rules/`. Claude rules go in `.claude/`. If you primarily use one tool, add rules there when they should not apply to every assistant. Keep stack conventions in `AGENTS.md` so every tool sees them. ## Skills Skills are modular capabilities that extend the assistant with domain-specific knowledge. They package instructions and reference material that loads only when the task matches. ### Skill structure Each skill is a directory with a `SKILL.md` file, and optionally a `references/` directory: YAML frontmatter tells the tool when to apply the skill: ```md title=".agents/skills/tanstack-start/SKILL.md" --- name: tanstack-start description: Full-stack React framework built on TanStack Router. Use when building with SSR, server functions, middleware, or Cloudflare Workers deployment. --- # TanStack Start ... ``` The model reads `description` to decide when to load the skill. When it triggers, the full `SKILL.md` enters context. `skills-lock.json` records the source repository and content hash for each installed skill, so you can update them later with the Skills CLI. ### Included skills | Skill | Use it for | | ----------------------------- | --------------------------------------------------- | | `tanstack-start` | Server functions, SSR, middleware, deployment | | `tanstack-router` | File routes, loaders, search params, navigation | | `tanstack` | Cross-cutting TanStack patterns (Query, Form, etc.) | | `kumo-design` | Picking and styling Kumo components | | `create-auth` | Better Auth setup and extending auth flows | | `vercel-react-best-practices` | React performance patterns | | `web-design-guidelines` | Accessibility and UI review | Framework APIs also ship inside installed packages. Before writing TanStack Start or Kumo code, the rules tell the model to read: | Topic | Read this | | -------------------- | ---------------------------------------------------------------- | | TanStack Start | `node_modules/@tanstack/react-start/skills/react-start/SKILL.md` | | Kumo components | `node_modules/@cloudflare/kumo/ai/component-registry.md` | | Kumo setup / theming | `node_modules/@cloudflare/kumo/ai/USAGE.md` | | Binding types | `worker-configuration.d.ts` (generated from `wrangler.jsonc`) | Those files match the installed version. Recalled APIs and generic web results often do not. ### Skill installation To add skills, use the [Skills CLI](https://skills.sh): ```bash npx skills add ``` Browse the catalog at [skills.sh](https://skills.sh). After installing, confirm the skill landed in `.agents/skills/` and that `skills-lock.json` lists it. If you use Claude Code, add a symlink next to the shipped ones: ```bash ln -s ../../.agents/skills/my-custom-skill .claude/skills/my-custom-skill ``` Agents and commands do not need that extra link. `.claude/agents` and `.claude/commands` already point at the shared folders. ### Creating custom skills For a workflow that is specific to your product: Create a directory in `.agents/skills/`: ```bash mkdir -p .agents/skills/my-custom-skill ``` Add a `SKILL.md` file. The `description` is what triggers the skill, so name the task and the files involved: ```md title=".agents/skills/my-custom-skill/SKILL.md" --- name: my-custom-skill description: Handles the notes feature workflow. Use when adding a module under src/modules or when the user asks for a new server function. --- # My Custom Skill ## Instructions 1. Read `AGENTS.md`, especially Gotchas. 2. Copy the file layout from `src/modules/billing/`. 3. Keep D1 access in `*.server.ts` and UI copy in `messages/en.json` and `messages/es.json`. ``` If you use Claude Code, symlink the directory into `.claude/skills/` as shown above. Then ask about the topic in the `description` and confirm the skill loads. ## Subagents Subagents are specialized assistants that handle one kind of task in their own context window. A long review stays out of the conversation you are using to implement. ### Included subagent Edge Kit ships a read-only code reviewer: ```md title=".agents/agents/code-reviewer.md" --- name: code-reviewer description: Reviews code for quality, conventions, and potential issues. Use when reviewing PRs, validating implementations, or checking code before commit. model: inherit readonly: true --- You are a senior code reviewer for TurboStarter Edge... ``` It checks the diff against `AGENTS.md` and against the configs that enforce the rules (`oxlint.config.ts`, `oxfmt.config.ts`, `tsconfig.json`, `wrangler.jsonc`). Read-only means it reports issues and does not edit files. The checklist covers: * TypeScript: no `any`, no unsafe casts, `interface` for object shapes, no enums * Imports: `@/` only, `env.config.ts` by relative path, bindings from `cloudflare:workers`, Kumo by subpath * Architecture: features in `src/modules//`, thin routes, D1 and secrets only in `*.server.ts` * Workers: no Node-only APIs, KV only for short-lived helpers, flags through `src/lib/flags.ts`, no extra APM * UI: no literal JSX strings, both message catalogs updated, links from `src/config/paths.ts` * Security: Zod on the server, `enforceAuth` on protected server functions, no hardcoded secrets ### Subagent usage Invoke one explicitly: ```txt Use the code-reviewer to review the changes in src/modules/billing/ ``` Or let the assistant delegate when the task matches the subagent `description`. ### Custom subagents Add a markdown file under `.agents/agents/`. Claude picks it up through the existing symlink. ```md title=".agents/agents/security-auditor.md" --- name: security-auditor description: Security specialist. Use when implementing auth, payments, storage keys, or webhooks. model: inherit readonly: true --- You are a security expert auditing TurboStarter Edge. When invoked: 1. Identify server functions and `src/routes/api/` handlers 2. Confirm protected handlers use `enforceAuth` and check resource ownership 3. Confirm Zod validation runs on the server 4. Confirm secrets stay in `env.config.ts` or Wrangler secrets, never in source 5. Check storage keys for path traversal Report findings by severity: Critical, High, Medium, Low. ``` ## Commands Commands are reusable prompts triggered with a `/` prefix. They encode a workflow so every feature starts from the same layout. ### Included command `/setup-new-feature` scaffolds a capability under `src/modules//`, using billing as the reference: ```md title=".agents/commands/setup-new-feature.md" # Setup New Feature Scaffold a new product capability in TurboStarter Edge following project conventions. Read `AGENTS.md` first. The `@/*` alias, the i18n import shape, and the no-literal-strings lint rule all bite on the first file you write. ``` The workflow is: 1. Put shared infra in `src/lib/` and product capabilities in `src/modules//`. Check `src/lib/` and `src/modules/common/` before adding a helper. 2. Add Zod schemas, D1 access in `*.server.ts`, `createServerFn` wrappers in `*.functions.ts` (guarded with `enforceAuth`), and TanStack Query options in `*.queries.ts`. 3. Import Kumo by subpath. Put every user-facing string in `messages/en.json` and `messages/es.json`. 4. Add a thin file route and a path in `src/config/paths.ts`. 5. If you add a binding, update `wrangler.jsonc` and run `pnpm cf-typegen`. 6. Finish with `pnpm format:fix && pnpm lint && pnpm test`. The same layout is written up for people in the [add a feature](/edge/docs/recipes/add-a-feature) recipe. ### Command usage Type `/` in chat and choose the command: ```txt /setup-new-feature ``` ### Custom commands Add a markdown file under `.agents/commands/`: ```md title=".agents/commands/fix-issue.md" # Fix GitHub Issue Fix a GitHub issue following Edge Kit conventions. ## Steps 1. Use `gh issue view ` to get the issue 2. Search `src/modules/` and `src/lib/` for the relevant files 3. Implement the fix using the billing module as the pattern 4. Add a `*.test.ts` or `*.worker.test.ts` next to the change 5. Run `pnpm format:fix && pnpm lint && pnpm test` 6. Commit only when asked ``` ## Model Context Protocol (MCP) MCP lets the assistant call external services: issues, databases, designs, and this documentation. That is separate from generating code in the repo. ### Common MCP integrations | Service | Use case | | ---------------------------------------------------------------------------------------------- | -------------------------------------- | | [GitHub](https://github.com/github/github-mcp-server) | Create issues, open PRs, read comments | | [Database](https://github.com/crystaldba/postgres-mcp) | Query schemas, inspect data | | [Figma](https://help.figma.com/hc/en-us/articles/32132100833559-Guide-to-the-Figma-MCP-server) | Import designs for implementation | | [Linear](https://linear.app/docs/mcp) / [Jira](https://github.com/sooperset/mcp-atlassian) | Read tickets, update status | | [Browser](https://browsermcp.io/) | Test UI, take screenshots | For local D1, prefer the Cloudflare local explorer and `pnpm db:migrate --local` over a Postgres MCP. D1 is SQLite. A Postgres server will not match `src/db/`. More servers are listed in the [Cursor MCP directory](https://cursor.com/docs/context/mcp/directory) and the [MCP server directory](https://www.pulsemcp.com/servers/). A typical local server entry looks like this. The filename and the `mcpServers` key depend on the tool (see the docs server setup below for the exact files Edge Kit expects you to edit): ```json title="mcp.json" { "mcpServers": { "github": { "command": "npx", "args": ["-y", "@modelcontextprotocol/server-github"], "env": { "GITHUB_TOKEN": "${env:GITHUB_TOKEN}" } } } } ``` ## Documentation Edge Kit docs are published with the rest of the TurboStarter docs, in a form assistants can read without copy-paste. ### Docs MCP server A hosted MCP server searches and reads the official docs, including every Edge page: ```txt https://www.turbostarter.dev/mcp ``` You do not run it locally. Point your client at that URL. It exposes two tools: `search_docs` (short queries, 2 to 5 words) and `read_doc` (a docs URL or a `.mdx` URL). Create or update `.cursor/mcp.json`: ```json title=".cursor/mcp.json" { "mcpServers": { "turbostarter": { "url": "https://www.turbostarter.dev/mcp" } } } ``` Enable the server in Cursor settings. After it connects, ask it to search the Edge docs before changing Workers code. Create or update `.mcp.json` in the project: ```json title=".mcp.json" { "mcpServers": { "turbostarter": { "type": "http", "url": "https://www.turbostarter.dev/mcp" } } } ``` Restart Claude Code and run `/mcp` to confirm the server is connected. Create or update `.vscode/mcp.json`: ```json title=".vscode/mcp.json" { "servers": { "turbostarter": { "type": "http", "url": "https://www.turbostarter.dev/mcp" } } } ``` Start the server from the MCP controls in VS Code. Add the server to `~/.codex/config.toml`: ```toml title="~/.codex/config.toml" [mcp_servers.turbostarter] type = "http" url = "https://www.turbostarter.dev/mcp" ``` Restart ChatGPT Codex so it loads the server. Try a prompt that has to use the docs: ```txt Use the TurboStarter docs MCP server to search for Edge Kit D1 migrations, then read that page and summarize the local vs remote commands. ``` If the client cannot connect, the URL must be exactly `https://www.turbostarter.dev/mcp`, and the client must support Streamable HTTP. Restart after editing the config, and enable the server in the tool's settings if tools do not appear. ### `llms.txt` The full documentation index is at [/llms.txt](/llms.txt), with an Edge Kit section. A single snapshot of every page is at [/llms-full.txt](/llms-full.txt). Paste either file into a model with a large enough context window when that model has no MCP client: ```txt Documentation: {paste documentation here} --- Based on the above documentation, answer the following: {your question} ``` ### Markdown for one page Each page is available as raw Markdown. Use the **Copy Markdown** button in the page header, or append `.mdx` to the URL. This page is [/edge/docs/installation/ai-development.mdx](/edge/docs/installation/ai-development.mdx). `read_doc` accepts that same URL: ```json { "url": "/edge/docs/installation/ai-development.mdx" } ``` ### Assistant shortcuts The **Open in...** control in the page header starts a chat in ChatGPT, Claude, or another assistant with that page attached. Use it when you want one guide in context and you are not inside the repo. ## Best practices These habits matter more on Edge Kit than on a familiar Next.js app, because a wrong default (a barrel import, a Node API, a literal string) fails lint or the Worker bundle. ### Development workflow For anything larger than a one-file change: 1. **Explore.** Have the model read `AGENTS.md`, `src/modules/billing/`, and the files it will touch. 2. **Plan.** Ask for a file list: schema, `*.server.ts`, `*.functions.ts`, `*.queries.ts`, messages, route. 3. **Implement.** One step at a time. 4. **Verify.** `pnpm format:fix && pnpm lint && pnpm test`. Small, familiar edits can skip the written plan. ### Verification criteria The model does better when it can check its own work: ```txt Add a createNote server function in src/modules/notes/. Guard it with enforceAuth. Validate the body with Zod. Add a worker test that inserts a row and reads it back. Run pnpm format:fix && pnpm lint && pnpm test when you finish. ``` A passing lint run is not optional here. `pnpm lint` is the type check. ### Prompts | Strategy | Vague | Specific | | ---------------------- | ----------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Scope the task** | "add tests for billing" | "add a worker test for `getBillingSummary` in `src/modules/billing/`, following the existing `*.worker.test.ts` files, using the D1 binding" | | **Reference patterns** | "add a settings form" | "copy the form structure from `src/modules/billing/`. Import Button from `@cloudflare/kumo/components/button`. Put new strings in both message catalogs" | | **Describe symptoms** | "fix login" | "sign-in returns 500 after session expiry. Start in `src/lib/auth/`. Write a failing test, then fix it. Do not add a new API route under `src/routes/api/`" | ### Explicit rules When you extend `AGENTS.md`, write requirements, not suggestions. "Always call `enforceAuth` before a D1 write" is followed. "Consider checking auth" is skipped. ```md ## MUST DO - Verify the session with `enforceAuth` before protected server work - Run `pnpm format:fix && pnpm lint && pnpm test` before you finish - Import Kumo by subpath, for example `@cloudflare/kumo/components/button` - Put user-facing strings in `messages/en.json` and `messages/es.json` ## MUST NOT DO - Never use `any`. Fix the types. - Never put binding IDs in `env.config.ts` - Never import from `@cloudflare/kumo` (the package root) - Never edit `src/routeTree.gen.ts`, `worker-configuration.d.ts`, or `src/db/schema/auth.ts` by hand ``` ### Project navigation Point at real paths so the model does not invent a `packages/` folder. Edge Kit is one package. ```md ## Where to find things - Database schema: `src/db/schema/` (`auth.ts` is generated), migrations in `drizzle/` - Server functions: `src/modules//*.functions.ts` - Shared adapters: `src/lib/` - Reference feature: `src/modules/billing/` - UI: Kumo registry in `node_modules/@cloudflare/kumo/ai/component-registry.md`, shared pieces in `src/modules/common/` - Bindings: `wrangler.jsonc` - Copy: `messages/en.json`, `messages/es.json` ``` ### Early corrections Stop the model when it reaches for Next.js, Prisma, ESLint, or a new top-level `src/api/` folder. Most tools interrupt with `Esc`. After two corrections on the same mistake, start a new conversation and put the constraint in the first message. The failed attempts are still in context otherwise. ### Context management Start a new conversation when you switch features, when the model repeats a mistake, or when a unit of work is done. Continue when you are still iterating on the same module. ### Research Send exploration and review to a subagent so the implementation thread stays small. That includes reading unfamiliar modules, the `code-reviewer` pass, and a security pass on auth, billing, or storage. ### Diff review Generated code can typecheck and still call a Node API, write a barrel import, or skip `messages/es.json`. Read the diff. For a new module, run the reviewer subagent in a fresh context after implementation. ### Product context Generic rules produce a generic app. Add the nouns and invariants of your product to `AGENTS.md`: ```md ## Business domain This application is a [one-sentence description]. ### Entities - **Account**: the signed-in user from Better Auth - **Subscription**: Stripe customer, plan id, and status in `src/modules/billing/` ### Rules - A user can only read rows they own. Check ownership in `*.server.ts`. - Plan limits are enforced on the server, not only in the UI. ``` Share setups that worked on the [Discord](https://discord.com/invite/KjpK2uk3JP). Questions about bindings, D1, and whether a library runs on Workers belong there too. ## Troubleshooting 1. Confirm `AGENTS.md` is at the repository root 2. Confirm the file is valid Markdown 3. Reopen the project so the tool reloads rules 4. Shorten the file if important lines are buried 5. Mark critical lines with "MUST" or "IMPORTANT" The training default is still Next.js. Point at the shipped rules in the prompt: "Read AGENTS.md and follow the Gotchas section. This is TanStack Start on Workers, Kumo by subpath, Oxlint." If it already edited the wrong files, revert and start a new conversation with that sentence first. Long sessions push `AGENTS.md` out of the window, and failed attempts stay in context. 1. Start a fresh session for the next feature 2. Restate the gotcha when you see drift (`@/` only, no JSX literals, `pnpm lint` for types) 3. After two failed corrections, clear context and write a tighter first prompt 1. Check that `description` names the task in plain language 2. Invoke the skill by name 3. Confirm `SKILL.md` has valid YAML frontmatter 4. For Claude Code, confirm `.claude/skills/` symlinks to `.agents/skills/` 5. Skills with side effects sometimes need an explicit invocation 1. Put the file in `.agents/agents/` 2. Check the frontmatter for syntax errors 3. Confirm `name` and `description` are set 4. Some tools hide subagents until you enable them in settings Common causes: a Node built-in, a package-root Kumo import, a literal string in JSX, a `#/` import, or a binding read from `env.config.ts`. 1. Ask for a check against the Gotchas section before the edit 2. Point at `src/modules/billing/` instead of describing the API from memory 3. Run `pnpm format:fix && pnpm lint && pnpm test` 4. Run `pnpm build` if routes or SSR changed 5. Revert and retry with a narrower prompt if follow-ups keep patching the same mistake A nested `AGENTS.md` overrides the root file for the directory it sits in. If they disagree, the model may follow the nearer file. 1. Ask which `AGENTS.md` it is using 2. Keep stack-wide rules in the root file 3. Use a nested file only for that folder's domain rules 1. Scope the search: "JWT checks in `src/lib/auth/`" rather than "find auth" 2. Use a subagent for exploration 3. Name the directory and the suffix (`*.functions.ts`, `*.server.ts`) 1. Use `https://www.turbostarter.dev/mcp` exactly 2. Confirm the client supports Streamable HTTP 3. Restart the client after changing its MCP config 4. Enable the server in the tool's settings if no tools are listed 5. Ask explicitly: "Use the TurboStarter docs MCP server to search for …" 1. Summarize or compact the session between tasks 2. Close the chat when a feature is done 3. Keep `node_modules`, `.output`, `.wrangler`, and `dist` out of search. They are already in `.gitignore` ## Resources