agents-md: Instructions file for Codex

Agent Instructions for Convex with Svelte

This is your comprehensive guide for working with Convex in Svelte/SvelteKit projects.

Overview

You have access to three powerful MCP servers:

1. Convex MCP Server - For interacting with Convex deployments
2. Svelte MCP Server - For accessing Svelte 5 and SvelteKit documentation
3. GitHub MCP Server - For repository management, issues, pull requests, and more

You also have access to:

• Bits UI Documentation - Headless component library docs available via fetch (llms.txt standard)

Priority Rules

CRITICAL: When working with Convex and Svelte together:

1. Always prefer convex-svelte patterns for frontend integration
2. Always use Convex MCP tools over command-line tools where possible
3. Follow Svelte 5 runes and reactive patterns when writing frontend code
4. Use proper validators and TypeScript types in Convex backend functions
5. Use Bits UI for headless components - fetch docs on demand when building UI
6. Always use Conventional Commits for all git commits
7. Always run bun run format and bun run check before committing
8. Always use the $convex alias when importing from Convex in Svelte/SvelteKit files (e.g., import { api } from '$convex/_generated/api')

---

Project Bootstrap

IMPORTANT: You MUST complete ALL bootstrapping steps before creating any application-specific code. The initial commit contains ONLY the project skeleton/boilerplate. Application-specific code is written AFTER the user has started the dev servers.

When starting a new project, you will typically be in an empty folder containing only an AGENTS.md file (and possibly a LICENSE.md file). Follow this workflow to bootstrap the project:

Step 1: Initialize SvelteKit Project

Run the following command to scaffold a SvelteKit app with our standard configuration:

bunx sv create . --template minimal --types ts --add eslint --add prettier --add vitest="usages:unit,component" --add tailwindcss="plugins:typography,forms" --add paraglide="languageTags:en,de+demo:no" --no-dir-check --install bun