Personal AGENTS.md for everyday use (global-scope).

AGENTS.md

AGENTS.md

1. Overview & Defaults

Assume: React + TS + Tailwind v4 + TanStack Start, via Vite+. Bun is the runtime/package manager for everything except inside Vite+ scaffolds, where vp proxies to pnpm internally — use vp commands there, not bun or pnpm directly. State assumptions in one line before coding. Keep dependencies minimal. Use vp over vite, and always use @latest tag when installing packages.

Banned Tools (DO NOT USE)

• Languages: Vanilla HTML/CSS/JS.
• Package Managers: npm, npx.
• Linters/Formatters: Prettier, ESLint, TSLint.

2. Tech Stack

• Runtime/Managers: Bun (default, all normal work), pnpm (Vite+ scaffolds only, via vp).
• App Types: TanStack Start + Nitro v3 (SSR/edge default), Astro (SSG), Vite+ SPA (client-only).
• Styling: Tailwind v4 (default), shadcn/ui (React).
• Icons: reicon-react, reicon-svelte.
• Routing: TanStack Router.
• Data Fetching: Fetch API (default), TanStack Query (React).
• State: @xstate/store (default), Svelte Runes.
• Forms/Schedule/Hooks: TanStack Form, TanStack Pacer, usehooks-ts (React), runed (Svelte).
• Backend (TS): Hono + Nitro v3, Mastra (AI).
• Database: Turso (default), CF KV / D1, Neon (+pgvector), Qdrant.
• ORM: Drizzle.
• Auth: better-auth.
• Hosting: Cloudflare (default), Netlify.
• Storage: CF R2 (default), AWS S3 (if not on Cloudflare).
• Jobs: CF Queues (default), Trigger.dev (if not on Cloudflare).
• Misc/Utilities: Zod (schemas), Motion/GSAP (animation), Resend (emails), Axiom (error tracking).

3. Documentation (Context7)

• Use: Fetch current library/framework/SDK/API docs. Prefer over web search or training data, even if you think you know the answer.
• Workflow:
  1. Resolve: bunx ctx7@latest library <name> "<question>" (use official names with punctuation, e.g., "TanStack Start").
  2. Pick match: Select ID (/org/project) with highest benchmark score & High/Medium reputation.
  3. Fetch: bunx ctx7@latest docs <libraryId> "<question>".
• Rules: Max 3 commands per query. Keep queries to a single concept. Version-specific format: /org/project/version. No sensitive data (API keys, passwords).
• Errors: If ctx7 fails/times out, inform user and use web search. On quota errors, prompt user to run bunx ctx7@latest login or set CONTEXT7_API_KEY. Do not silently fall back to training data for library APIs.

4. Scaffolding & QA (Vite+)

• Scaffolding Command: Use vp create [TEMPLATE] for greenfield projects. Always pass --package-manager pnpm to enforce Vite+ standard.
• Templates:
  • TanStack Start (default): vp create @tanstack/start -- --package-manager pnpm
  • Astro: vp create astro -- --package-manager pnpm
  • Svelte SPA (Minimal, only if the user asks for Svelte): vp create vite -- --template svelte-ts --package-manager pnpm
• Flags: Use --directory <dir>, --git (default on). Use --no-interactive for unattended/CI runs.
• Development Workflow: Use vp commands for all project tasks. It will proxy to pnpm under the hood:
  • Install/Manage: vp install, vp add <pkg>, vp remove <pkg>, vp dedupe
  • Run: vp dev, vp run <script>, vp exec <cmd>, vp dlx <pkg>
  • Build: vp build, vp preview
• Testing: vp test (bundles Vitest). Do not add a standalone vitest dependency. Playwright (E2E) installs normally via vp add -D playwright.
• Lint/Format: vp check (runs format, lint, and type checks). Use vp lint and vp fmt. Uses Oxlint/Oxfmt. Do not add ESLint/Prettier.
• Migrations: Greenfield only. Do not migrate existing projects unless asked. Treat vp migrate with caution (upstream flagged unreliable); review changes before trusting.
• Errors: If commands fail due to environment issues, report exact trace. Do not silently auto-fix.

5. Modularity

Check for nested AGENTS.md files in subdirectories. Nested rules override root rules for that directory only.