multica/AGENTS.md

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 all client state (current workspace selection, view filters, drafts, modals)
• All Zustand stores live in packages/core/ - never in packages/views/ or app directories
• WS events invalidate React Query - never write directly to stores

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

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.