jarvisandClaude Fable 5
6cc093afdb
Adds the agent output standard to the framework SOT so it injects at launch and is selectable per user (closes the gap: it lived only as a jarvis-brain lab doc + issue #960). - guides/WRITING-STYLE.md: MOS-STE (adapted ASD-STE100) for docs, Google Style for code, verification-artifact emphasis, absolute user-voice carve-out. Written in MOS-STE. - defaults/STANDARDS.md: Output-standards block (always injected via the prompting contract). - defaults/AGENTS.md: routing row so writing/doc/comms work reaches the guide. - defaults/USER.md: per-user 'Comms style' option (technical|prose|brief), default technical. Refs mosaicstack/stack#960. Owner directive (Jason, 2026-07-30): docs->adapted ASD-STE100, code->Google style, resumes/personal carved out, comms style a per-user choice. Written-by: jarvis (dragon-lin) Co-Authored-By: Claude Fable 5 <[email protected]>
79 lines
4.7 KiB
Markdown
79 lines
4.7 KiB
Markdown
# 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.
|
|
|
|
### 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 style in `USER.md` "Communication Preferences"; the default is technical. 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)
|