Files

T

jarvisandClaude Fable 5 caf40afc01 fix(framework): ride the existing communicationStyle enum, drop the no-op USER.md edit (mos-dt review #960 )

F1: defaults/USER.md is never installed (generated from templates/USER.md.template
via buildCommunicationPrefs). Editing it was a no-op asserting a phantom setting —
exactly the false-green §2 warns against. Reverted.
F2: the framework already has communicationStyle (direct|friendly|formal). §5 now
maps THOSE values to output instead of inventing technical|prose|brief (rule 9).
Minor: §6 states no mechanical prose check exists today; rule 1 points at §3.4.

Written-by: jarvis (dragon-lin)
Co-Authored-By: Claude Fable 5 <[email protected]>

2026-07-30 15:24:17 -05:00

4.8 KiB

Raw Blame History

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

Load this file first.
Load project-local AGENTS.md next.
Respect repository-specific tooling and workflows.
Use lifecycle scripts when available (scripts/agent/*.sh).
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.

Output standards (writing + code)

Technical documentation follows MOS-STE (Mosaic Simplified Technical English — an adapted ASD-STE100 profile): short sentences, one instruction per sentence, active voice, one word per meaning, one term per concept. Full rules: ~/.config/mosaic/guides/WRITING-STYLE.md.
Apply MOS-STE hardest to verification artifacts (acceptance criteria, witness predicates, gate/alarm conditions). There an ambiguous term produces a false green, not just a confused reader.
Source code follows the Google Style Guide for the language.
User-facing comms follow the user's declared communicationStyle in USER.md "Communication Preferences" (direct | friendly | formal, default direct); guides/WRITING-STYLE.md §5 maps each value to output. The documentation standard does not change with user preference.
Carve-out: MOS-STE does NOT apply to content that must carry a specific human voice (letters, personal or marketing prose, voice-matched output). A declared voice profile wins.

Secrets handling (HARD RULE)

Vault is the canonical source-of-truth for every secret in every environment. No exceptions.
For k8s workloads, the default read path is External Secrets Operator → k8s Secret → env var (secretKeyRef). The app reads standard env vars; no Vault client in app code.
Direct-Vault clients in application code are opt-in only, justified per-app by a documented dynamic-secrets requirement (e.g., DB rotation, AWS STS). Default to ESO. Document the justification in the project's README under "Secrets architecture".
${VAR:-default} fallback syntax in any deployment configuration (compose, k8s manifests, Helm values, env files committed to git) is forbidden for required values. Use ${VAR:?VAR is required} to fast-fail. Defaults are allowed only for true conveniences (e.g. ${PORT:-3000}) and MUST be tagged # safe-default: <reason> so a reviewer can confirm the intent.
.env files in production deployment paths are forbidden. .env.example and .env in local-dev paths are fine.
App startup MUST validate required secrets against a schema (zod / pydantic / equivalent) and exit non-zero on missing required values. Never run with defaulted weak fallbacks.
New apps: bootstrap checklist (see ~/.config/mosaic/guides/BOOTSTRAP.md) MUST include Vault path provisioning + ExternalSecret manifest + README declaring the Vault path and required keys.

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)

4.8 KiB Raw Blame History