# AI tool integration

> How OTF works with Claude Code, Cursor, Antigravity, and Lovable.

OTF is **AI-native by design**. Every kit ships with config files for the major AI coding
assistants so that "ask Claude to add a screen" or "tell Cursor to wire a route" produces
code that follows the kit's conventions — not Claude's training data's conventions.

## What "AI-native" means here

Three claims that aren't quite the same:

1. **The kits include AI configs out of the box.** Every kit has a `CLAUDE.md`, `.cursorrules`,
   `AGENTS.md`, and (where applicable) `lovable.md`. Open the kit in any of these tools and
   you don't need to explain anything — the tool already knows the stack, the file map, the
   conventions, the deploy flow.

2. **The configs are kept in sync.** A single source of truth (the upcoming `@otfdashkit/ai`
   CLI) generates each tool's file, so they don't drift. Manual edits live inside `// @otf-keep`
   blocks that the regenerator never overwrites.

3. **Components are designed to be modified.** Every component sits in a single file. Names
   are explicit. There's no clever inheritance. AI tools edit them cleanly because a human
   would too.

## The four supported tools

| Tool                | Config file shipped                | How it reads context                          |
| ------------------- | ---------------------------------- | --------------------------------------------- |
| **Claude Code**     | `CLAUDE.md`, `AGENTS.md`           | Auto-loaded into every prompt                 |
| **Cursor**          | `.cursorrules`                     | Auto-loaded into chat                          |
| **Antigravity**     | `AGENTS.md`                        | Read by the agent on session start            |
| **Lovable**         | `lovable.md` (or pinned in chat)   | Reads the file or relies on pinned context    |

If you use a different tool (Aider, Continue, GitHub Copilot Workspace), point it at
`AGENTS.md` — it's the most universally-readable of the configs.

## What's in a kit's CLAUDE.md

Take the [SaaS Dashboard kit](/docs/templates/saas-dashboard) as a reference. Its `CLAUDE.md`
contains:

- **Stack table** — Vite + React 19 + TanStack Router + TanStack Query + Hono + Drizzle + Better Auth
- **Project structure** — top-down map of `src/`, `server/`, where each entity lives
- **Patterns** — the canonical optimistic-update hook shape, Hono route shape, screen-add procedure
- **Theming** — token classes only, CSS load order, default theme bootstrap
- **Conventions** — no comments unless explaining a non-obvious *why*; strict TypeScript; functional components; Tailwind tokens only
- **Deploy** — exact command to ship; what env vars are required

That's enough for an AI to add a new screen, wire a Hono route, or refactor a component
without diverging from the rest of the codebase.

## What's coming: `@otfdashkit/ai` CLI

Currently each kit's `CLAUDE.md` / `.cursorrules` / `AGENTS.md` are hand-maintained. Phase 6
of the OTF roadmap ships **`@otfdashkit/ai`** — a CLI that:

- Reads a single `otf.config.ts` per project
- Generates `CLAUDE.md`, `.cursorrules`, `AGENTS.md`, `lovable.md` from one source
- Preserves manual customizations inside `// @otf-keep` blocks
- Re-runs cleanly on every kit update so the configs stay in sync with the codebase

```bash
# (coming soon)
npx @otfdashkit/ai generate --tools=claude,cursor,antigravity,lovable
```

Until that ships, the per-tool guides below describe the file structures by hand.

## Per-tool guides

<Cards>
  <Card title="Claude Code" href="/docs/ai-tools/claude-code" description="CLAUDE.md conventions, /commands surface, and how the kit's planner sub-agent reads the file map." />
  <Card title="Cursor" href="/docs/ai-tools/cursor" description=".cursorrules file structure, MCP configs, and per-folder cursor.json overrides." />
  <Card title="Antigravity" href="/docs/ai-tools/antigravity" description="AGENTS.md format Antigravity expects, and how its planner reads the kit's roadmap." />
  <Card title="Lovable" href="/docs/ai-tools/lovable" description="lovable.md project bible and how Lovable's URL fetcher reads our docs." />
</Cards>

## FAQ

<Accordions type="single">
  <Accordion title="Do I need every tool's config, or pick one?">
    Pick whichever you actually use day-to-day. Every kit ships all four out of the box,
    but they're independent — deleting `.cursorrules` doesn't affect Claude Code, etc.
    Keep the ones that match your workflow.
  </Accordion>
  <Accordion title="What stays editable when @otfdashkit/ai regenerates the configs?">
    Anything wrapped in `// @otf-keep` (or `<!-- @otf-keep -->` for Markdown) blocks. The
    regenerator preserves those regions verbatim so your team-specific overrides don't get
    flattened on the next kit update.
  </Accordion>
  <Accordion title="Can I use OTF kits with an AI tool that isn't on this list?">
    Yes — the conventions in `CLAUDE.md` / `AGENTS.md` are plain Markdown. Any tool that
    reads context files (Aider, Continue, etc.) will pick them up. We only ship configs for
    the four because those are the tools we actively test with.
  </Accordion>
  <Accordion title="How do the kits handle conflicting AI suggestions across tools?">
    They don't — each tool reads its own config. The trick is keeping the configs in sync,
    which is exactly what `@otfdashkit/ai` solves: one source of truth (`otf.config.ts`)
    that emits all four files in step.
  </Accordion>
</Accordions>