Agent Guidelines — Mosaic Stack

Required Load Order

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

Project Context

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

Stack

API: NestJS with Fastify (apps/gateway)
Web: Next.js 16 with React 19 (apps/web)
ORM and database: Drizzle ORM, PostgreSQL 17, and pgvector (packages/db)
Authentication: BetterAuth (packages/auth)
Agent runtime: Pi SDK (apps/gateway, packages/mosaic)
Queue: Valkey 8 (packages/queue)
Build: pnpm workspaces and Turborepo
CI: Woodpecker CI
Observability: OpenTelemetry and Jaeger

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 schema and migrations	drizzle-orm, postgres
`packages/auth`	BetterAuth configuration	better-auth, @mosaicstack/db
`packages/brain`	Structured data layer	@mosaicstack/db
`packages/queue`	Valkey task queue and MCP	ioredis
`packages/coord`	Mission coordination	@mosaicstack/queue
`packages/mosaic`	Unified `mosaic` CLI and TUI	Ink, Pi SDK, commander
`plugins/discord`	Discord channel plugin	discord.js
`plugins/telegram`	Telegram channel plugin	Telegraf

Architecture and Code Conventions

Gateway is the single API surface; all clients connect through it.
Pi SDK is ESM-only; gateway and CLI code must remain ESM.
Use "type": "module", NodeNext module resolution, and .js extensions in imports.
Keep typed Socket.IO events in @mosaicstack/types to enforce client/server contracts.
Import OTEL tracing before NestJS bootstrap (import './tracing.js').
Use explicit @Inject() decorators in NestJS because tsx/esbuild does not emit decorator metadata.
Keep DTOs in *.dto.ts files at module boundaries.
BetterAuth owns authentication tables; their schema is defined in @mosaicstack/db.
Create a task-specific scratchpad for non-trivial work.

Development Workflow

Requirements: Node.js 20+, pnpm 10.6.2, and Docker Compose when optional local services are needed.

pnpm install --frozen-lockfile
pnpm preflight

# Optional local queue service only; do not start the full Compose stack.
docker compose up -d valkey

The pre-push hook requires:

pnpm preflight && pnpm typecheck && pnpm lint && pnpm format:check

Software delivery also requires the applicable tests. Common repository commands are:

pnpm typecheck     # TypeScript checks across the workspace
pnpm lint          # ESLint across the workspace
pnpm test          # Checkout tests and package Vitest suites
pnpm format:check  # Prettier check
pnpm build         # Build all packages and applications

Database and Local Runtime Safety

Current local data-layer work uses in-process PGlite; leave DATABASE_URL unset.
PostgreSQL execution is held until KBN-101-00, KBN-101-03, and KBN-101-05 land.
Do not invoke a migration runner, initialization SQL, or the Compose PostgreSQL service from this checkout.
Do not start Gateway/Web or run root pnpm dev as a local PGlite route. The current dotenv loader can inherit a daemon PostgreSQL DSN; KBN-101-02 must make that path fail closed first.
Migration artifact generation is offline and does not authorize PostgreSQL access:

pnpm --filter @mosaicstack/db db:generate

docs/TASKS.md — Schema (CANONICAL)

The agent column specifies the required model for each task. This is set at task creation by the orchestrator and must not be changed by workers.

Value	When to use	Budget
`codex`	All coding tasks (default for implementation)	OpenAI credits — preferred
`glm-5.1`	Cost-sensitive coding where Codex is unavailable	Z.ai credits
`haiku`	Review gates, verify tasks, status checks, docs-only	Cheapest Claude tier
`sonnet`	Complex planning, multi-file reasoning, architecture review	Claude quota
`opus`	Major cross-cutting architecture decisions ONLY	Most expensive — minimize
`—`	No preference / auto-select cheapest capable	Pipeline decides

Pipeline crons read this column and spawn accordingly. Workers never modify docs/TASKS.md — only the orchestrator writes it.

Full schema:

| id | status | description | issue | agent | repo | branch | depends_on | estimate | notes |

status: not-started | in-progress | done | failed | blocked | needs-qa
agent: model value from table above (set before spawning)
estimate: token budget e.g. 8K, 25K

5.7 KiB Raw Blame History