AGENTS.md

1# Repository Guidelines
2 
3This file provides guidance to AI agents when working with code in this repository.
4 
5> **Single source of truth:** This file is a concise pointer document.
6> All authoritative architecture, coding rules, and conventions
7> live in **CLAUDE.md** at the project root. Read that file first.
8> Use `Makefile`, `package.json`, and `pnpm-workspace.yaml` as the
9> source of truth for the full command list.
10 
11## Quick Reference
12 
13### Architecture
14 
15Go backend + monorepo frontend (pnpm workspaces + Turborepo) with shared packages.
16 
17- `server/` - Go backend (Chi router, sqlc, gorilla/websocket)
18- `apps/web/` - Next.js frontend (App Router)
19- `apps/desktop/` - Electron desktop app
20- `packages/core/` - Headless business logic (Zustand stores, React Query hooks, API client)
21- `packages/ui/` - Atomic UI components (shadcn/Base UI, zero business logic)
22- `packages/views/` - Shared business pages/components
23- `packages/tsconfig/` - Shared TypeScript config
24 
25### State Management (critical)
26 
27- **React Query** owns all server state (issues, members, agents, inbox, workspace list)
28- **Zustand** owns client/view state (view filters, drafts, modals, desktop tab state); current workspace identity is route-driven and only mirrored for platform plumbing
29- All Zustand stores live in `packages/core/` - never in `packages/views/` or app directories
30- WS events update React Query for server data; store writes are only for clearing client-owned pointers with a single responder/self-event guard
31 
32### Package Boundaries (hard rules)
33 
34- `packages/core/` - zero react-dom, zero localStorage, zero process.env
35- `packages/ui/` - zero `@multica/core` imports
36- `packages/views/` - zero `next/*`, zero `react-router-dom`, use `NavigationAdapter` for routing
37- `apps/web/platform/` - only place for Next.js APIs
38 
39### Database Migrations (hard rules)
40 
41- Never add database foreign keys or cascading actions. Enforce relationships and perform dependent cleanup explicitly in the application layer, using transactions when the operation must be atomic.
42- Every index created by a migration, including unique indexes and indexes on new tables, must use `CREATE [UNIQUE] INDEX CONCURRENTLY`. Keep each concurrent index build in its own single-statement migration file.
43 
44### Commands
45 
46```bash
47make dev              # Auto-setup + start everything
48pnpm typecheck        # TypeScript check
49pnpm test             # TS unit tests (Vitest)
50make test             # Go tests
51make check            # Full verification pipeline
52```
53 
54See CLAUDE.md for the authoritative rules and common commands.
55