9. The writing and output layer

9.1 Two files: judgment and spec

voice.md is the part that a script cannot check. A skill loads it when it writes prose, and it governs a routed chat reply on its own. It asks for clear, direct language at the user’s level. familiar has no fixed industry, profession or formal register. The main points are:

• Lead with the outcome.
• Use concrete nouns and active verbs.
• Keep confirmed fact, interpretation from a source, open question and recommendation apart.
• Keep uncertainty where the evidence is uncertain.

Its avoid-list bans generic scene-setting, inflated claims, fake quotations, rhetorical questions as decoration, and claims that work is done before the checks ran.

Its Audience section decides who a deliverable’s body text speaks to. The writer confirms the reader before writing (document.md/deck.md step 1). For an outside reader, the text may not:

• name the project files or the retrieval system as the evidence
• credit a finding to generic “sources” instead of the study or guideline
• report the document’s own drafting or confirmation status in the text
• explain an editing choice to the reader
• cite the project’s own unfinished draft

The test is who the sentence speaks to, not a list of banned phrases. An internal working draft is exempt.

Its Uncertainty marker section defines two bracket markers:

• [verify] for a claim that has no source yet or is not confirmed
• [action: ...] for an instruction to the drafter, a task rather than a claim in question

Both counts must reach zero before an outside delivery. In a .docx or .pptx built with document-tools, each marker gets its own colored, italic run (docx-rules.md/deck-rules.md → Editor notes). It does not stay as plain bracket text in the body font.

plain-language.md is the part that can be counted. A skill loads it only when it writes something longer than a chat reply. It first picks the shape from the type of content, not from the audience:

Shape	Rules
Operational	Commands, one instruction per sentence, 20 words
Full-prose deliverable	Paragraphs, structure rules only, 25 words
Deck	Fragments, length and word rules only
Chat reply	voice.md only
Persuasive text	Exempt

The shape decides which sentence rules apply. Then come the rules: verb tenses, modal verbs, one word per meaning, filler to delete, a self-check, and a section that states the rules’ own limits.

Why the split is where it is. You apply voice.md by thinking, and plain-language.md by searching the draft. Only the second can be checked, so only the second is worth its load cost at the moment of writing. The shape choice lives in plain-language.md, beside the rules it selects.

Why an aerospace standard. “Write clearly” is an opinion, and models do not act on opinions. “No sentence over 20 words” is a spec, and models do act on specs. ASD-STE100 was written so that a tired reader who is not a native English speaker cannot misread an instruction. The same rules remove the signs of AI-written prose: long sentences, rotating synonyms, hedging, decorative clauses. The spec and voice.md’s banned list therefore support each other without repeating each other.

9.2 The pre-delivery check

Before output governed by voice.md goes out, the agent checks six things:

1. The requested outcome is present and easy to find.
2. Claims have the grounding that the task needs.
3. Unknowns and assumptions are visible.
4. No dates, names, amounts, citations or paths were invented.
5. The shape matches the project configuration, the project’s user-preferences.md, and the audience.
6. The remaining [verify] and [action: ...] tags are counted and reported. Output that leaves the project needs zero.

Paths, versions and provenance are covered by file-handling.md (§9.3), not by this check. What a skill must not read is in each skill’s Excluded context field.

9.2.1 How the rules reach each write

Every skill that declares file-write requires file-handling.md. Source protection, naming, versions and provenance therefore apply to every write. Skills that write a deliverable, knowledge page, review, brief or other prose also declare voice.md and plain-language.md. They declare them as required context, or behind the exact branch that writes prose. Skills that only maintain state load the state rule that applies instead, such as status-format.md, state-schema.md or check-in.md.

This keeps a tracker or metadata edit from loading the full prose spec, and file safety and state formats stay required. The release checks confirm that every skill that writes files loads file-handling.md, plus either the writing rules or a state format. The six-field contract stays the one statement of what a route can load.

The project’s user-preferences.md is read at startup (§4.1). It is read again through voice.md just before written output, where its content can change the result.

9.3 File handling, naming, provenance

• New output for you to review is named YYYY-MM-DD_<short-description>_<status>_vN.<ext>, with status DRAFT, REVIEW or FINAL. Each revision adds one to the version. final-final, new and overwriting the source file name are not version control.
• State files keep stable names and use revisions instead. Activity logs are append-only.
• An output based on project sources cites the source path and a useful locator. An output based on outside sources carries the original URL, the date it was read, and the narrowest locator available. A gap in retrieval is recorded as a gap.
• Generated knowledge and review outputs record the skill that made them, the date, and the installed component version. For an extension, that is its full namespaced ID.
• Office documents are ZIP packages. Before the agent reads or delivers a .docx, .pptx or .xlsx, it checks for a readable central directory and [Content_Types].xml. A renamed or cut-off archive is not a valid Office document.
• Nothing is published, sent or moved outside the workspace without your approval.

9.4 The optional companion voice

familiar-voice.md is flavor only. familiar works the same with it off, and no rule or guard depends on it. It acts only on something the agent notices without being asked: a date that moved, a logged decision about to be contradicted, a track gone quiet, or a relevant memory nobody asked for. It shows as an italic line that starts with the signature key. It never applies to a guard message, a system message or anything inside a deliverable. It uses italics only when the agent reports that it can show Markdown formatting.

9.5 Document building, and its limits

deck and document ship real build scripts that work on any agent: skills/draft-document/scripts/build_pptx.py and skills/draft-document/scripts/build_docx.py. They use python-pptx and python-docx, which are ordinary open-source libraries. They are not a copy of any vendor’s document skill. Each script supports --health-check, --build, --validate and --render.

Two more scripts sit beside them in skills/draft-document/scripts/:

• xlsx_check.py (standard library only) lists what a workbook holds and compares two versions.
• office_render.ps1 (Windows PowerShell 5.1) opens a deck, document or workbook in the real Office application, read-only and with a time limit, for the final check. For a deck, it makes slide PNGs and a PDF. For a document, it opens the file and counts pages, tracked changes and comments. For a workbook, it recalculates and counts formula errors.

Where Office is installed, its render is the one that counts. A LibreOffice render is labeled as LibreOffice only.

Both build scripts look for LibreOffice’s soffice on PATH first. Then they look in the default install folders, which are not on PATH by default:

• the macOS app bundle (/Applications/LibreOffice.app/Contents/MacOS/soffice)
• Program Files on Windows
• the common Linux paths (/usr/lib/libreoffice, /opt/libreoffice*)

A default install is therefore found with no setup.

Preflight. .familiar/scripts/doctor.py is a preflight for this toolchain. It uses only the standard library and runs on Windows, macOS and Linux (with python3, python or py). It checks the Python version, the python-docx and python-pptx packages, LibreOffice (with the same search as the build scripts), pandoc, and the optional extraction tools. For each gap, it prints what is missing, what breaks without it, and the command that fixes it on that computer. Where the system Python blocks pip (PEP 668), that command uses a virtual environment at ~/.familiar/venv. The preflight exits 0 when every required check passes. It avoids newer syntax so that it can still run on an older Python and report it. It changes nothing.

Every other shipped script starts with a check that stops on a Python older than 3.10, with a plain message instead of a traceback. routes.md → Running familiar’s scripts tells the agent how to pick the interpreter. running-scripts.md tells it when to offer an install.

document-tools is recorded as available, never active, on every agent. Nothing checks the toolchain at install time, and the capability table is written by hand. Both procedure files therefore run the script’s own --health-check at the start of every build and report the real result. A visual check needs LibreOffice’s soffice (found as above). Without it, the build reports "visual_validation": false and does not skip the check without telling you. deck has no fallback without the visual check, and it must say so. document falls back to Markdown. On an agent with no Python, this is a real gap, and familiar does not hide it.

Citations and Word files that the team owns. A Word draft cites in two colored layers, back to back (docx-rules.md → Editor notes → Dual citation):

• teal reference for the compiled document that a statement came from
• purple primary-reference for the underlying study

Only the purple layer ever becomes a reference-manager field, and only through an installed citation extension. Core drafts the tags and never writes those fields. A draft with citations that leaves the project gets a Markdown _trace.md file beside it, with one row per cited statement. Before each handoff, the claims check grades each row primary verified, compiled source or unsupported. The project’s Referencing method (none | manual | extension) is in 5-System/user-preferences.md. The Document branch asks for it once. It changes only how the final version is made, and how a tracked review treats existing fields.

When a deliverable becomes a file that the team edits, the review branch takes over from document. build_docx.py --revise cannot write tracked changes, and it rebuilds the text it touches. scripts/tracked_edit.py is therefore the only editor for such a file. It only adds:

• Every edit is a w:ins/w:del or a comment by “AI Review”.
• Replies go under the parent comment.
• It leaves fields, hyperlinks and other authors’ tracked text untouched.
• It refuses to reply to comments addressed to the client (Note to ...).
• --apply applies all edits or none.

--check proves that a pass was safe. If you reject every AI change, you get the source back, and everything from the source is identical byte for byte. This has been tested on a hand-built test file, not yet on a file written in Word.

deck ships no brand or neutral presentation master, and there is no shared template library on the computer. deck-rules.md uses this order: the template that you choose, then a template for this project that you placed in 1-Inputs/Templates/. If neither exists, deck reports that it is unavailable. It does not invent a brand or a neutral master.

---