React Rules

Components

• Use named exports, not default exports: export function AgentCard() {}
• One component per file for route-level components
• Co-locate small helper components in the same file
• Use className with Tailwind — no CSS modules or styled-components

Data Fetching

• Use TanStack Query (useQuery, useSuspenseQuery) for all data fetching
• Server Functions for mutations via useMutation
• Never use useEffect for data fetching
• Prefetch on the server with queryClient.prefetchQuery in route loaders

State

• URL state first (search params via TanStack Router)
• Server state via TanStack Query (no Redux, no Zustand)
• Local UI state only with useState — keep it minimal
• Form state with controlled components or useForm

Patterns

• Suspense boundaries at route level, not per-component
• Error boundaries for slice-level error handling
• Compose with props, not render props or HOCs
• Use shadcn/ui components — don't build custom UI primitives

File Naming

• Route files: route.tsx (TanStack Router file-based routing)
• UI components: PascalCase.tsx or grouped in ui.tsx within a slice
• Hooks: use-kebab-case.ts (must start with use prefix — enforced by architecture tests)

Slice Boundaries (enforced by automated tests)

• Never import a component from another feature's ui/ directory directly
• Shared UI primitives go in src/components/ui/ (shadcn convention)
• Cross-slice data: import hooks/types from the other slice's model.ts facade, not from internal files
• Route files must be thin — compose from slice hooks and components, don't import from domain/ or infra/ directly
• Example: import { useAgents } from '@/features/registry/model' (correct) vs import { useAgents } from '@/features/registry/hooks/useAgents' (wrong from outside registry)