diff --git a/packages/mosaic/framework/defaults/AGENTS.md b/packages/mosaic/framework/defaults/AGENTS.md index eb488c38..ca3117a2 100755 --- a/packages/mosaic/framework/defaults/AGENTS.md +++ b/packages/mosaic/framework/defaults/AGENTS.md @@ -39,6 +39,7 @@ overwritten on upgrade. (Layer model: `constitution/LAYER-MODEL.md`.) | TypeScript strict typing | `guides/TYPESCRIPT.md` | | QA / test strategy | `guides/QA-TESTING.md` | | Documentation (any code/API/auth/infra change) | `guides/DOCUMENTATION.md` | +| Writing style (docs, comms, any prose) | `guides/WRITING-STYLE.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` | diff --git a/packages/mosaic/framework/defaults/STANDARDS.md b/packages/mosaic/framework/defaults/STANDARDS.md index d9ea7f40..b35ed86e 100644 --- a/packages/mosaic/framework/defaults/STANDARDS.md +++ b/packages/mosaic/framework/defaults/STANDARDS.md @@ -27,6 +27,14 @@ Master/slave model: - 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. diff --git a/packages/mosaic/framework/defaults/USER.md b/packages/mosaic/framework/defaults/USER.md index 2979a265..7c94526c 100644 --- a/packages/mosaic/framework/defaults/USER.md +++ b/packages/mosaic/framework/defaults/USER.md @@ -26,6 +26,18 @@ It is loaded globally and applies regardless of runtime or project. - No sycophancy - Executive summaries and tables for overview +### Comms style (agents read this to choose how they talk to you) + +Choose one. Agents match it for user-facing messages. The default is `technical`. +This setting governs comms only. It does not change the documentation standard +(`guides/WRITING-STYLE.md`), which is always MOS-STE. + +- **`technical`** (default) — MOS-STE structure: short, active, defined terms. +- **`prose`** — full sentences and paragraphs, warmer register, fewer tables. +- **`brief`** — status lines and bullet points, minimum words. + +> Comms style: technical + ## Personal Boundaries (Add any personal boundaries or preferences agents should respect.) diff --git a/packages/mosaic/framework/guides/WRITING-STYLE.md b/packages/mosaic/framework/guides/WRITING-STYLE.md new file mode 100644 index 00000000..c338f69e --- /dev/null +++ b/packages/mosaic/framework/guides/WRITING-STYLE.md @@ -0,0 +1,121 @@ +# Writing Style Standard — MOS-STE (MANDATORY) + +This guide defines how agents write. It sets one style standard per output type. +It is written in the standard it defines, as a worked example. + +**Adapted, not compliant.** MOS-STE (Mosaic Simplified Technical English) is an +adapted profile of ASD-STE100. Mosaic does not license or certify against +ASD-STE100. Mosaic uses the load-bearing rules and fits them to agent work. This +is the same stance Mosaic takes toward DO-178B/C: use the rigor, do not claim the +certification. + +## Scope — which standard governs which output + +| Output type | Standard | +|---|---| +| Technical documentation (READMEs, runbooks, PRDs, procedures, ADRs, guides, acceptance criteria, design docs) | **MOS-STE** (this guide) | +| Source code and code comments | **Google Style Guide** for the language (§4) | +| Inter-agent comms | MOS-STE by default (concise, technical) | +| User-facing comms | **Per-user style choice** — read `USER.md` "Communication Preferences" (§5) | +| End-user prose the user owns (marketing, letters, personal writing, voice-matched content) | The user's declared voice. MOS-STE does NOT apply. | + +**The user-voice carve-out is absolute.** Do not apply MOS-STE to content that +must carry a specific human voice (for example a cover letter, a personal +message, or marketing copy). That content needs the user's voice. MOS-STE would +damage it. When a project declares a voice profile, that profile wins. + +## 1. Why one standard + +Agent documentation drifts across projects. Different agents use different terms, +sentence styles, and structures for the same concept. Readers lose time. +Assumptions hide in ambiguous prose. One standard gives agents a clear target. It +gives reviewers a clear test. + +## 2. Where MOS-STE matters most — verification artifacts + +Apply MOS-STE hardest to acceptance criteria, witness predicates, gate +definitions, and alarm conditions. In prose, an ambiguous term produces a +confused reader. In a verification artifact, an ambiguous term produces a false +green — a check that passes without testing the claim. + +The one-term-one-concept rule (rule 9) is the guard. When one word names two +concepts in one predicate, the check can test the wrong concept and still pass. + +**Worked failure.** A rename used a witness predicate with three clauses: ref A +present, ref B absent, tip committed from this host. Every clause tested the git +*ref* (the channel). The claim under test was about a *field inside the payload*. +The word "beacon" named two concepts in one sentence. Deleting ref B was the next +scheduled step. That step flips the last clause green and certifies a state in +which the payload still names the wrong host. The predicate was one planned action +away from a false green on its normal path. The payload field was never tested. + +Rule: when N failure modes share one observable, the observable is not a +diagnostic. In a verification artifact, that ambiguity does not confuse a reader — +it certifies the defect. + +## 3. MOS-STE rules + +### 3.1 Sentence rules + +1. Keep sentences short. Use 20 words or fewer for a procedure. Use 25 words or + fewer for a description. +2. Write one instruction per sentence. In a procedure, give one command per step. +3. Use the active voice. Write "Run the script." Do not write "The script should + be run." +4. Use the imperative for instructions. Start the sentence with the verb. +5. Use simple verb tenses. Prefer the present tense. Avoid the perfect and + progressive tenses when a simple tense works. +6. Do not use an `-ing` form when it makes the meaning unclear. +7. Write positive statements. State what to do, not only what to avoid. + +### 3.2 Word rules + +8. Use one word for one meaning. Do not use the same word in two senses. +9. Use one term for one concept. Do not use synonyms for variety. Example: choose + `secret`, `credential`, or `key` for each concept, and keep it. +10. Use articles (`a`, `the`). Do not drop words to save space. +11. Keep an approved-terms glossary per project. Add each domain noun and each + chosen verb. Technical names (for example `Vault`, `cgroup`, `systemd`) are + always allowed. +12. Define an abbreviation at its first use. Then use it consistently. + +### 3.3 Structure rules + +13. Use a list for parallel items or sequential steps. Do not put them in one long + sentence. +14. Use a table for data with more than two dimensions. +15. Use parallel structure in headings and steps. +16. Repeat the noun. Do not use a pronoun when the reference is unclear. + +### 3.4 Adaptation notes (where MOS-STE deviates from ASD-STE100, and why) + +- **No licensed dictionary.** ASD-STE100 ships a controlled dictionary under + copyright. MOS-STE uses per-project glossaries instead (rule 11). +- **Domain terms are allowed.** MOS-STE keeps every term the work needs. +- **Reasoning prose gets structure, not amputation.** Apply the sentence and word + rules to design and doctrine writing. Allow the length a subtle argument needs. + Readable-first beats rule-strict when the two conflict. + +## 4. Code — Google Style Guide + +Write source code to the Google Style Guide for the language (Python, TypeScript, +Shell, Go, and so on). Match the existing file when a local convention already +exists. Keep code comments to the MOS-STE sentence and word rules. + +## 5. User-facing comms — a per-user choice + +Mosaic is multi-user. Different users want different comms styles. Read the +`USER.md` "Communication Preferences" section and match the declared style. + +- **Default (no preference declared):** technical — MOS-STE structure, + readable-first. +- **Declared style wins.** If the user declares prose, warmth, or a specific + register, match it. The user's preference outranks the MOS-STE default for + user-facing comms. It does not change the documentation standard (§3). + +## 6. Enforcement + +- **Now:** human review plus the pre-push gate. Reviewers check output against the + scope table and the MOS-STE rules. +- **Future:** an MOS-STE lint check and a Google-style linter in the pre-push + gate.