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

1. Gateway is the single API surface; all clients connect through it.
2. Pi SDK is ESM-only; gateway and CLI code must remain ESM.
3. Use "type": "module", NodeNext module resolution, and .js extensions in imports.
4. Keep typed Socket.IO events in @mosaicstack/types to enforce client/server contracts.
5. Import OTEL tracing before NestJS bootstrap (import './tracing.js').
6. Use explicit @Inject() decorators in NestJS because tsx/esbuild does not emit decorator metadata.
7. Keep DTOs in *.dto.ts files at module boundaries.
8. BetterAuth owns authentication tables; their schema is defined in @mosaicstack/db.
9. 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

Branch Model and Merge Process — main and next (CANONICAL)

Every contribution targets next first. No exceptions. Features, fixes, tests, docs, and policy changes all take the same route; urgency changes queue priority, never the route. Agents never commit to or merge into main.

Branch	Role	Who merges into it
next	Integration trunk — the only PR target for contributions	The designated merge-gate agent, after all gates pass. Never the PR author.
main	Stable/release line — receives promotion merges from next only	Jason only (or an agent he explicitly delegates for a named promotion).

Contribution sequencing (in order, no skipping)

1. Issue first. Work is tracked in a Gitea issue before a branch exists. The issue number appears in the branch name and the PR body.
2. Branch from the current origin/next head. Name it feat/…, fix/…, docs/…, or test/… with the issue number (e.g. docs/1214-branch-process). Record the base SHA in the PR body.
3. Develop with evidence. Applicable tests accompany the change. Hooks are never bypassed (--no-verify is prohibited). Stage explicit paths — never git add -A.
4. Open the PR against next. The body states: scope, base SHA, verification commands with results, and any known pre-existing failures on the base — documented, not retried to green and not absorbed silently.
5. CI must be terminal-green on the exact head. All bounded Woodpecker steps succeed (verify-terminal-green contract). Pipelines for fork PRs start blocked; a maintainer approves the run — approving CI is not approving the PR.
6. Independent review. Self-merge is prohibited — for every agent, on every PR, including trivial ones. Where the change touches protected or contract-bearing content, the reviewer verifies the exact head (exact-byte/exact-blob comparison), not a description of it. An AMEND verdict returns the PR to its author; the reviewer's gate stays held until a fresh exact head passes.
7. Merge into next happens only after CI green + review pass, pinned to the reviewed head SHA (a post-review push voids the review).
8. Promotion next → main is a deliberate, Jason-owned reconciliation merge — not part of any contribution's lifecycle. Contributors are done at step 7.

Responsibilities

• Contributor — base pinning, green CI, evidence in the PR body, responding to AMEND verdicts, never merging own work.
• Reviewer / merge gate — independent verification on the exact head; holds and lifts gates; executes the merge into next.
• Orchestrator / adjudicator — cross-PR sequencing, disposition when PRs collide, conflict adjudication.
• Jason — next → main promotions, merge-authority grants, collaborator and token provisioning. Agents cannot grant themselves or each other any of these.

Hotfixes and divergence

• A hotfix follows the same path: branch from next, PR to next, gates, merge, then an expedited Jason-owned promotion if main needs it urgently. Committing the fix to main directly is prohibited even under pressure.
• Never land work on main that is not on next. This has happened (issue #1152's goal controller reached main without reaching next) and every later PR paid for it. If it happens anyway: transplant the work onto a next-based branch with provenance-preserving commits (git cherry-pick -x or explicit SHA references in the messages), PR it through the normal gates, and let promotion re-align main. Do not hand-patch main to compensate.
• Force-pushing a branch you do not own is prohibited; rebasing your own PR branch is fine before review, and voids any review already given.

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