AI Agent Guidelines

This page documents the conventions that AI coding agents (Copilot, Cursor, Codex, etc.) should follow when working on the Leave Localhost codebase.

Before Editing

1. Read AGENTS.md at the repository root for the full rules.
2. Read packages/backend/AGENTS.md before editing Convex code.
3. Read packages/backend/convex/_generated/ai/guidelines.md for Convex-specific API patterns that override training data.
4. Check .agents/skills/ directories for relevant skills before starting.

Code Style

• Write concise, technical TypeScript.
• Use functional and declarative patterns; avoid classes.
• Prefer iteration and modularization over duplication.
• Use descriptive variable names with auxiliary verbs (isLoading, hasError).
• Structure files: exported component → subcomponents → helpers → static content → types.

Naming

• Directories: lowercase with dashes (e.g. components/auth-wizard).
• Exports: favor named exports for components.
• TypeScript: prefer interface over type. Avoid enum; use maps.

Workspace Ownership

Package Manager

Use Bun for all commands. Do not introduce npm, pnpm, yarn, or npx.

bun install           # Install dependencies
bun run <script>      # Run root script
bunx <cli>            # Run CLI tool

Verification After Changes

Do Not Edit

• packages/backend/convex/_generated/** — auto-generated.
• .env, .env.local — local configuration.
• .next, .turbo, .react-email, node_modules — build outputs.

Key Patterns

Error Handling

Use ConvexAppError factories (notFound, forbidden, invalidInput), not raw throw new Error().

Permissions

Start every public function with requireAppPermission() or canAppPermission().

Organization Scoping

All tenant data must be filtered by actor.organizationId from the permission check.

React Components

• Minimize "use client", useEffect, and setState.
• Favor React Server Components.
• Wrap client components in Suspense with fallback.
• Use next/dynamic for non-critical components.

Loading UX

• Use route-level loading.tsx files with small skeleton components.
• For initial authenticated page data, preload a page-level view model on the server with convexAuth.preloadAuthQuery, pass the Preloaded result to the client component, and read it with usePreloadedAuthQuery.
• Include ordinary permission and capability state in that view model when the route needs it. When a protected query would throw before it can be preloaded, make a preliminary server authorization decision instead; the billing page is the reference implementation.
• A client useQuery is appropriate only for live, paginated, or interaction-driven data that genuinely needs a subscription. Do not turn an initial route load into per-component permission subscriptions.
• Keep skeleton geometry aligned with the final layout.