Skip to content

AGENTS.md

Latest commit

 

History

History
54 lines (39 loc) · 2.53 KB

AGENTS.md

File metadata and controls

54 lines (39 loc) · 2.53 KB
Raw

Repository Guidelines

This file provides guidance to AI agents when working with code in this repository.

Single source of truth: This file is a concise pointer document. All authoritative architecture, coding rules, and conventions live in CLAUDE.md at the project root. Read that file first. Use Makefile, package.json, and pnpm-workspace.yaml as the source of truth for the full command list.

Quick Reference

Architecture

Go backend + monorepo frontend (pnpm workspaces + Turborepo) with shared packages.

  • server/ - Go backend (Chi router, sqlc, gorilla/websocket)
  • apps/web/ - Next.js frontend (App Router)
  • apps/desktop/ - Electron desktop app
  • packages/core/ - Headless business logic (Zustand stores, React Query hooks, API client)
  • packages/ui/ - Atomic UI components (shadcn/Base UI, zero business logic)
  • packages/views/ - Shared business pages/components
  • packages/tsconfig/ - Shared TypeScript config

State Management (critical)

  • React Query owns all server state (issues, members, agents, inbox, workspace list)
  • Zustand owns client/view state (view filters, drafts, modals, desktop tab state); current workspace identity is route-driven and only mirrored for platform plumbing
  • All Zustand stores live in packages/core/ - never in packages/views/ or app directories
  • WS events update React Query for server data; store writes are only for clearing client-owned pointers with a single responder/self-event guard

Package Boundaries (hard rules)

  • packages/core/ - zero react-dom, zero localStorage, zero process.env
  • packages/ui/ - zero @multica/core imports
  • packages/views/ - zero next/*, zero react-router-dom, use NavigationAdapter for routing
  • apps/web/platform/ - only place for Next.js APIs

Database Migrations (hard rules)

  • 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.
  • 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.

Commands

make dev              # Auto-setup + start everything
pnpm typecheck        # TypeScript check
pnpm test             # TS unit tests (Vitest)
make test             # Go tests
make check            # Full verification pipeline

See CLAUDE.md for the authoritative rules and common commands.