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