stack/packages/mosaic/framework/defaults/AGENTS.md

Mosaic Agent Dispatcher

Thin load-order dispatcher + guide router. The non-negotiable law lives in ~/.config/mosaic/CONSTITUTION.md (L0) — this file does NOT restate gates. Framework-owned; overwritten on upgrade. (Layer model: constitution/LAYER-MODEL.md.)

Session Start — Load Order

1. Your context already includes CONSTITUTION.md + USER.md + the TOOLS index + the runtime contract (injected by mosaic launch) — do not re-read those. If you were launched bare (a harness started without mosaic, so the law is NOT in your context), read ~/.config/mosaic/CONSTITUTION.md now, before your first action.
2. Read SOUL.md (agent persona — small, once).
3. Read project-local AGENTS.md / CLAUDE.md if present (these may only make behavior stricter).
4. Read guides ONLY as triggered by the table below — pull role-relevant depth on demand, not up front.
5. For implementation work, read guides/E2E-DELIVERY.md (the full delivery procedure: PRD/tracking gates, execution cycle, testing, review, completion). STANDARDS.md is reference — load it only if the task needs standards validation (do not halt if missing).

Conditional Guide Loading (load only what the task needs)

Task	Guide
Project bootstrap	guides/BOOTSTRAP.md
PRD creation / requirements	guides/PRD.md
Implementation delivery (cycle/testing/completion)	guides/E2E-DELIVERY.md
Orchestration flow	guides/ORCHESTRATOR.md
Mission lifecycle / multi-session orchestration	guides/ORCHESTRATOR-PROTOCOL.md
Orchestrator estimation heuristics	guides/ORCHESTRATOR-LEARNINGS.md
Frontend changes	guides/FRONTEND.md
Backend/API changes	guides/BACKEND.md
Auth/authorization	guides/AUTHENTICATION.md
CI/CD changes	guides/CI-CD-PIPELINES.md
Infrastructure/DevOps/deployment	guides/INFRASTRUCTURE.md
Code review work	guides/CODE-REVIEW.md
TypeScript strict typing	guides/TYPESCRIPT.md
QA / test strategy	guides/QA-TESTING.md
Documentation (any code/API/auth/infra change)	guides/DOCUMENTATION.md
Secrets / vault usage	guides/VAULT-SECRETS.md
Tool/credential reference (service CLIs, wrappers)	guides/TOOLS-REFERENCE.md
Memory protocol (OpenBrain capture/recall)	guides/MEMORY.md

Subagent Model Selection (Cost — Hard Rule)

Select the cheapest model capable of the task; do NOT default to the most expensive (omitting the tier defaults to the parent — usually opus — and wastes budget).

• haiku — search/grep/glob, codebase exploration, status/health checks, one-line mechanical fixes.
• sonnet — code review, lint, test writing/fixing, standard feature implementation.
• opus — complex architecture / multi-file refactors, security/auth logic, ambiguous design.

Start cheapest; escalate only when the task genuinely needs deeper reasoning. Runtime syntax for the tier is in the runtime contract.

Superpowers (use your tools — under-use is a violation)

Skills, hooks, MCP, and plugins are force multipliers you MUST use when applicable.

• Skills: before implementation, scan ~/.config/mosaic/skills/ and load any matching the task domain; include skill loading in worker kickstarts. Do not load unrelated skills.
• Hooks: never bypass or suppress hook output (see "hooks are the gate" in CONSTITUTION.md); fix hook failures like failing tests. If a hook is wrong, report it as a framework issue.
• MCP: use structured-reasoning (sequential-thinking) for planning/architecture; the cross-agent memory layer (OpenBrain capture/search/recent) — search at session start, capture what you learn. Prefer web/browser/research tools over asking the human to look things up.
• Plugins: use code-review / pr-review / architecture plugins proactively before opening a PR.
• Self-evolution: capture framework-improvement / tooling-gap / framework-friction to OpenBrain — operator-agnostic only (see the framework-PR firewall in CONSTITUTION.md).

Missing core file

If CONSTITUTION.md, AGENTS.md, SOUL.md, or the runtime contract is missing, stop and report it. This agent-facing strictness is intentional and stricter than the launcher: the launcher injects CONSTITUTION.md tolerantly (skipping it if absent so pre-upgrade hosts keep working), but once a host is re-seeded a genuinely missing core file is a stop-and-report condition — not something to proceed past.

Session Closure

Confirm: required + situational tests passed (primary gate); aligned to docs/PRD.md; acceptance criteria mapped to evidence; independent code review passed (if code changed); required docs updated; scratchpad updated. For PR-workflow delivery: merged PR number + merge commit on main, terminal-green CI, linked issue closed (or docs/TASKS.md equivalent). If blocked by access/tooling, return blocked with the exact failed wrapper command — do not claim completion. Full checklist: guides/E2E-DELIVERY.md.