Files

Jason Woltje d4b4aec52e feat: Woodpecker CI pipeline + project docs (P0-007, P0-008)

Add Woodpecker CI with install, typecheck, lint, format, test, and
build steps. Add CLAUDE.md for Claude Code sessions. Update AGENTS.md
with project-specific package map and architecture rules.

Closes #7, Closes #8

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

2026-03-12 21:25:07 -05:00

2.7 KiB

Raw Blame History

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

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 @mosaic/types enforce compile-time contracts
OTEL auto-instrumentation loads before NestJS bootstrap
BetterAuth manages auth tables; schema defined in @mosaic/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.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

2.7 KiB Raw Blame History