# Mosaic Universal Agent Standards

This file is the canonical standards contract for agent sessions on this machine.

Master/slave model:

- Master: `~/.config/mosaic` (this framework)
- Slave: each repo bootstrapped via `mosaic-bootstrap-repo`

## Execution Model

1. Load this file first.
2. Load project-local `AGENTS.md` next.
3. Respect repository-specific tooling and workflows.
4. Use lifecycle scripts when available (`scripts/agent/*.sh`).
5. Use shared tools/guides from `~/.config/mosaic` as canonical references.

## Non-Negotiables

- Data files are authoritative; generated views are derived artifacts.
- Pull before edits when collaborating in shared repos.
- Run validation checks before claiming completion.
- Apply quality tools from `~/.config/mosaic/tools/` when relevant (review, QA, git workflow).
- For project-level mechanical enforcement templates, use `~/.config/mosaic/tools/quality/` via `~/.config/mosaic/bin/mosaic-quality-apply`.
- For runtime-agnostic delegation/orchestration, use `~/.config/mosaic/tools/orchestrator-matrix/` with repo-local `.mosaic/orchestrator/` state.
- Avoid hardcoded secrets and token leakage in remotes/commits.
- Do not perform destructive git/file actions without explicit instruction.
- Browser automation (Playwright, Cypress, Puppeteer) MUST run in headless mode. Never launch a visible browser — it collides with the user's display and active session.

## Session Lifecycle Contract

- Start: `scripts/agent/session-start.sh`
- Priority scan: `scripts/agent/critical.sh`
- End: `scripts/agent/session-end.sh`
- Limitation logging helper: `scripts/agent/log-limitation.sh "Title"`

If a repo does not expose these scripts, run equivalent local workflow commands and document deviations.

## Multi-Agent Safety

- Coordinate through git pull/rebase discipline.
- Do not auto-resolve data conflicts in shared state files.
- Keep commits scoped to a single logical change set.

## Prompting Contract

All runtime adapters should inject:

- `~/.config/mosaic/STANDARDS.md`
- project `AGENTS.md`

before task execution.

Runtime-compatible guides and tools are hosted at:

- `~/.config/mosaic/guides/`
- `~/.config/mosaic/tools/`
- `~/.config/mosaic/profiles/` (runtime-neutral domain/workflow/stack presets)
- `~/.config/mosaic/runtime/` (runtime-specific overlays)
- `~/.config/mosaic/skills-local/` (local private skills shared across runtimes)
