stack/AGENTS.md

Agent Guidelines — Mosaic Stack

Required Load Order

1. ~/.config/mosaic/SOUL.md
2. ~/.config/mosaic/STANDARDS.md
3. ~/.config/mosaic/AGENTS.md
4. ~/.config/mosaic/guides/E2E-DELIVERY.md
5. AGENTS.md (this file)
6. Runtime-specific guide: ~/.config/mosaic/runtime/<runtime>/RUNTIME.md

Project Context

Mosaic Stack is a self-hosted, multi-user AI agent platform. TypeScript monorepo with NestJS gateway, Next.js web dashboard, Pi SDK agent runtime, and plugin architecture for Discord/Telegram.

Package Map

Package	Purpose	Key Dependencies
apps/gateway	NestJS API + WebSocket hub	Fastify, Socket.IO, Pi SDK, OTEL
apps/web	Next.js dashboard	React 19, Tailwind
packages/types	Shared TypeScript contracts	class-validator
packages/db	Drizzle ORM schema + migrations	drizzle-orm, postgres
packages/auth	BetterAuth configuration	better-auth, @mosaic/db
packages/brain	Data layer (PG-backed)	@mosaic/db
packages/queue	Valkey task queue + MCP	ioredis
packages/coord	Mission coordination	@mosaic/queue
packages/cli	Unified CLI + Pi TUI	Ink, Pi SDK
plugins/discord	Discord channel plugin	discord.js
plugins/telegram	Telegram channel plugin	Telegraf

Architecture Rules

1. Gateway is the single API surface — all clients connect through it
2. Pi SDK is ESM-only — gateway and CLI must use ESM
3. Socket.IO typed events defined in @mosaic/types enforce compile-time contracts
4. OTEL auto-instrumentation loads before NestJS bootstrap
5. BetterAuth manages auth tables; schema defined in @mosaic/db
6. Docker Compose provides PG (5433), Valkey (6380), OTEL Collector (4317/4318), Jaeger (16686)
7. Explicit @Inject() decorators required in NestJS (tsx/esbuild doesn't emit decorator metadata)

Development Workflow

docker compose up -d          # Infrastructure
pnpm install                  # Dependencies
pnpm typecheck && pnpm lint && pnpm format:check  # Quality gates

Repo-Specific Notes

• DTOs in *.dto.ts files at module boundaries
• ESM everywhere ("type": "module", .js extensions in imports)
• NodeNext module resolution in all tsconfigs
• Scratchpads are mandatory for non-trivial tasks