bootstrap repo to mosaic standards layer

AGENTS.md

@@ -1,37 +1,65 @@
 # Mosaic Stack — Agent Guidelines
 
-> **Any AI model, coding assistant, or framework working in this codebase MUST read and follow `CLAUDE.md` in the project root.**
+## Load Order
 
-`CLAUDE.md` is the authoritative source for:
+1. `SOUL.md` (repo identity + behavior invariants)
+2. `~/.mosaic/STANDARDS.md` (machine-wide standards rails)
+3. `AGENTS.md` (repo-specific overlay)
+4. `.mosaic/repo-hooks.sh` (repo lifecycle hooks)
 
-- Technology stack and versions
-- TypeScript strict mode requirements
-- ESLint Quality Rails (error-level enforcement)
-- Prettier formatting rules
-- Testing requirements (85% coverage, TDD)
-- API conventions and database patterns
-- Commit format and branch strategy
-- PDA-friendly design principles
+## Runtime Contract
 
-## Quick Rules (Read CLAUDE.md for Details)
+- This file is authoritative for repo-local operations.
+- `CLAUDE.md` is a compatibility pointer to `AGENTS.md`.
+- Follow universal rails from `~/.mosaic/guides/` and `~/.mosaic/rails/`.
 
-- **No `any` types** — use `unknown`, generics, or proper types
-- **Explicit return types** on all functions
-- **Type-only imports** — `import type { Foo }` for types
-- **Double quotes**, semicolons, 2-space indent, 100 char width
-- **`??` not `||`** for defaults, **`?.`** not `&&` chains
-- **All promises** must be awaited or returned
-- **85% test coverage** minimum, tests before implementation
+## Session Lifecycle
 
-## Updating Conventions
+```bash
+bash scripts/agent/session-start.sh
+bash scripts/agent/critical.sh
+bash scripts/agent/session-end.sh
+```
 
-If you discover new patterns, gotchas, or conventions while working in this codebase, **update `CLAUDE.md`** — not this file. This file exists solely to redirect agents that look for `AGENTS.md` to the canonical source.
+Optional:
 
-## Per-App Context
+```bash
+bash scripts/agent/log-limitation.sh "Short Name"
+```
 
-Each app directory has its own `AGENTS.md` for app-specific patterns:
+## 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
+
+```bash
+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`