AGENTS.md
Conventions for any AI coder working on this project. Read this before suggesting or writing code.
This file is the same content as CLAUDE.md and GEMINI.md. Different AI tools read different filenames; the rules are identical.
Vibecoder kit skill triggers (read first, always)
Before writing code for any of these tasks, open the matching vibecoder kit skill and follow it. The vibecoder kit skills encode conventions that keep output consistent across tools and sessions.
| User says something like... | Read this kit skill |
|---|---|
| "get this running" / "set up this project" / "install" | agent-skills/get-it-running.md |
| "back up to GitHub" / "set up Git" / "push to a private repo" | agent-skills/setup-github-backup.md |
| "change the font" / "use Inter" / "swap typography" | agent-skills/swap-font.md |
| "convert the blog to MDX" / "file-based blog" / "real blog files" | agent-skills/add-blog.md |
| "add SEO" / "meta tags" / "sitemap" / "og image" | agent-skills/add-seo.md |
| "add analytics" / "GA" / "GA4" / "Google Analytics" | agent-skills/add-analytics.md |
| "check accessibility" / "a11y audit" / "WCAG" | agent-skills/a11y-audit.md |
| "check performance" / "perf audit" / "Lighthouse" | agent-skills/perf-audit.md |
| "wire the contact form" / "make contact form send" | agent-skills/wire-contact-form.md |
"review this page" / "audit this component" / "is this on-brand" / "denetle" / /review / /review <path> | agent-skills/project-design-review.md |
For adding a new blog post (one entry, no migration), do not use a kit skill: just pattern-match the existing entries in app/routes/blog.$slug.tsx and app/routes/blog.index.tsx.
For adding a generic page or section, no kit skill is needed. Compose existing components (Hero, FeatureGrid, CTABlock, Card, Button, Container, Section) and follow the conventions below.
For third-party service setup (deploy, Git, domain, email provider, contact form backend), see docs/ instead; those are pointers, not bundled kit skills.
Stack
- TanStack Start 1.x on Vite, with the
app/directory (srcDirectory: 'app'invite.config.ts). - React 19, TypeScript 5.
- Tailwind v4 via
@tailwindcss/vite. Theme tokens live inapp/styles/app.cssunder@theme { }. - pnpm.
Routing
- File-based routes in
app/routes/. - Each route exports
Route = createFileRoute(...)({ component, head }). - Do not manually edit
app/routeTree.gen.ts. It regenerates. - Root wrapper is
app/routes/__root.tsx. Header and Footer live there.
Router export
app/router.tsx exports a function getRouter() (not a createRouter const). Follow that pattern.
Styling
- Use Tailwind utility classes on elements.
- When you need a color, reference tokens as
bg-[var(--color-background)],text-[var(--color-foreground)],border-[var(--color-border)], etc. Do NOT hard-code hex values inside components. - Tokens live in
app/styles/app.css. Add new tokens there when needed, not inline. - Dark mode is class-based:
.darkon<html>toggles alternate values.
Components
Reusable components live in app/components/. Section patterns in app/components/sections/.
When adding a new page, prefer composing existing components (Hero, FeatureGrid, CTABlock, SocialProof, Card, Button, Container, Section) over writing new primitives.
Imports
Use the ~ alias for app/. Example: import { Button } from '~/components/Button'.
Type safety
- Strict mode is on. No
anyunless explicitly justified in a comment. - Use
typefor data shapes,interfaceonly for extendable public APIs.
Commit style
Short, imperative subject line. Example: add services detail route. No trailing period.
Never do
- Never add a second UI framework (Chakra, MUI, etc.). Tailwind + native HTML is the rule.
- Never introduce a new font, color palette, or radius scale outside
DESIGN.md. If a design change is needed, updateDESIGN.mdfirst and syncapp/styles/app.css. - Never reach for a deployment provider, auth provider, database, or email service without a matching kit skill. See
docs/for third-party pointers.
Ask me this first
If a request is ambiguous, clarify before writing code. Prefer short questions over guesses.