bootstrap/STANDARDS.md

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)