stack/AGENTS.md

Mosaic Stack — Agent Guidelines

Load Order

1. SOUL.md (repo identity + behavior invariants)
2. ~/.config/mosaic/STANDARDS.md (machine-wide standards rails)
3. AGENTS.md (repo-specific overlay)
4. .mosaic/repo-hooks.sh (repo lifecycle hooks)

Runtime Contract

• This file is authoritative for repo-local operations.
• CLAUDE.md is a compatibility pointer to AGENTS.md.
• Follow universal rails from ~/.config/mosaic/guides/ and ~/.config/mosaic/rails/.

Session Lifecycle

bash scripts/agent/session-start.sh
bash scripts/agent/critical.sh
bash scripts/agent/session-end.sh

Optional:

bash scripts/agent/log-limitation.sh "Short Name"
bash scripts/agent/orchestrator-daemon.sh status
bash scripts/agent/orchestrator-events.sh recent --limit 50

Repo Context

• Platform: multi-tenant personal assistant stack
• Monorepo: pnpm workspaces + Turborepo
• Core apps: apps/api (NestJS), apps/web (Next.js), orchestrator/coordinator services
• Infrastructure: Docker Compose + PostgreSQL + Valkey + Authentik

Quick Command Set

pnpm install
pnpm dev
pnpm test
pnpm lint
pnpm build

Standards and Quality

• Enforce strict typing and no unsafe shortcuts.
• Keep lint/typecheck/tests green before completion.
• Prefer small, focused commits and clear change descriptions.

App-Specific Overlays

• apps/api/AGENTS.md
• apps/web/AGENTS.md
• apps/coordinator/AGENTS.md
• apps/orchestrator/AGENTS.md

Additional Guidance

• Orchestrator guidance: docs/claude/orchestrator.md
• Security remediation context: docs/reports/codebase-review-2026-02-05/01-security-review.md
• Code quality context: docs/reports/codebase-review-2026-02-05/02-code-quality-review.md
• QA context: docs/reports/codebase-review-2026-02-05/03-qa-test-coverage.md