7206b9411d
The @mosaicstack/cli package was consolidated into @mosaicstack/mosaic in a prior refactor, and was already excluded from pnpm-workspace.yaml. This commit deletes the now-dead packages/cli directory and updates the last remaining docs references that still pointed at it. - Delete packages/cli/ (48 files, ~6.6K lines of dead code) - pnpm-workspace.yaml: drop the !packages/cli exclusion - tools/install.sh: update install step label - AGENTS.md, CLAUDE.md: update package map - README.md, docs/guides/user-guide.md, packages/mosaic/framework/defaults/README.md: update install docs Verified clean: typecheck, lint, format:check, test (38/38 tasks). Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
4.1 KiB
4.1 KiB
Agent Guidelines — Mosaic Stack
Required Load Order
~/.config/mosaic/SOUL.md~/.config/mosaic/STANDARDS.md~/.config/mosaic/AGENTS.md~/.config/mosaic/guides/E2E-DELIVERY.mdAGENTS.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. 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, @mosaicstack/db |
packages/brain |
Data layer (PG-backed) | @mosaicstack/db |
packages/queue |
Valkey task queue + MCP | ioredis |
packages/coord |
Mission coordination | @mosaicstack/queue |
packages/mosaic |
Unified mosaic CLI + TUI |
Ink, Pi SDK, commander |
plugins/discord |
Discord channel plugin | discord.js |
plugins/telegram |
Telegram channel plugin | Telegraf |
Architecture Rules
- Gateway is the single API surface — all clients connect through it
- Pi SDK is ESM-only — gateway and CLI must use ESM
- Socket.IO typed events defined in
@mosaicstack/typesenforce compile-time contracts - OTEL auto-instrumentation loads before NestJS bootstrap
- BetterAuth manages auth tables; schema defined in
@mosaicstack/db - Docker Compose provides PG (5433), Valkey (6380), OTEL Collector (4317/4318), Jaeger (16686)
- 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.tsfiles at module boundaries - ESM everywhere (
"type": "module",.jsextensions in imports) - NodeNext module resolution in all tsconfigs
- Scratchpads are mandatory for non-trivial tasks
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 |
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-qaagent: model value from table above (set before spawning)estimate: token budget e.g.8K,25K