docs-contract · diff
git:20261010.b64ecd9 to git:20261011.0f77af2
53 added, 10 removed. Audit A to A.
---
name: docs-contract
- description: Contract of the documentation agents — the conduct shared by the planner and the writer (isolation, inputs from disk, what must never reach a page or the map), preloaded into docs-planner and docs-writer through the `skills` field of their front-matter. Not a command; nothing to invoke.
+ description: Contract of the documentation agents — the conduct shared by the planner and the writer (isolation, inputs from disk, what must never reach a page or the map, the voice and the sentence of a page), preloaded into docs-planner and docs-writer through the `skills` field of their front-matter. Not a command; nothing to invoke.
user-invocable: false
---
This skill is the one owner of what the two documentation agents
share (POS.1450, POS.0950, SOL.0460); it is preloaded into
`docs-planner` and `docs-writer` at launch. What each agent owns
beyond it is its own file: the planner the readers, the outline, what
it reads and the map; the writer the page and its shape.
## Conduct and isolation
You see nothing of the conversation that started you; your task is
your whole brief. Whatever your context carries about the people who
run this forge, their company, hosts, addresses or preferences is
not material and must not reach what you write or shape it. Every
input is read from disk in this run, with the Read tool: the copy of
`CLAUDE.md` in your context is the session's and may be older than
the file (POS.0950). You ask no question: where something is
unclear, you decide, say so in what you write, and move on.
## What must never reach a page or the map
No name of a person, no company, no host, no account, no e-mail, no
identifier of an instance: a placeholder slug replaces a real one in
every example. No address but the public home of the target where
the target's own documents name it as such. No document of any
- project but the owning one. Nothing of a skill or an agent copied as
- an instruction to Claude: a page says what a command does for the
- person, in the person's terms. No ID of the chain (`POS.`, `SOL.`,
- `THR.`) on a page: the reason is given, its ID is not. Where the
- operating layer (`CLAUDE.md`, the skills, the agents, the templates,
- the scripts) and the intent differ, take the operating layer's
- wording and the intent's reason. English, plain, in the spelling the
- inputs use. No long dash anywhere: a colon, a full stop or a spaced
- hyphen where one would stand.
+ project but the owning one: an example that shows the shape a
+ template or a convention defines, plainly generic and taken from no
+ project, is a mirror of that owner and is welcome; the content of a
+ real project, a position, a finding, a thread of the forge's own
+ project among them, is not (POS.1450). Nothing of a skill or an
+ agent copied as an instruction to Claude: a page says what a command
+ does for the person, in the person's terms. No ID of the chain
+ (`POS.`, `SOL.`, `THR.`) on a page: the reason is given, its ID is
+ not. No reason the inputs do not give: where a page would want one
+ and none is recorded, the page says "the reason is not recorded"
+ and the writer reports the place (POS.1450). No date of a decision,
+ no "was changed on", no history of how a rule came to be: a page
+ says what holds, the history is the owner's. No sentence of the
+ generator about itself, its inputs or its run, beyond the fixed
+ closing line the writer's shape gives. Where the operating layer
+ (`CLAUDE.md`, the skills, the agents, the templates, the scripts)
+ and the intent differ, take the operating layer's wording and the
+ intent's reason. English, plain, in the spelling the inputs use.
+
+ ## The voice
+
+ One voice on every page (POS.1450): Claude is "it"; the reader of a
+ how-to is "you"; the person whose thinking is forged is "the
+ principal", glossed at its first use on a page, never "the user" or
+ "the person" for the same role; the machine is "Claude", never "the
+ session", "the harness" or "the forge" where Claude is meant.
+ "Session" and "harness", where a page needs them, are glossed once
+ on that page. One word per thing, the owners' word: "definition"
+ for a state file, "template" for a skeleton, "instance" for one
+ installation; "map" always qualified (the documentation map, the
+ state map, the Map of a definition, the provenance map), "finding"
+ for a reviewer's result only.
+
+ ## The sentence
+
+ One rule per sentence; an enumeration is a list, not a sentence. An
+ enumeration whose members carry a gloss (a bracket, a clause after
+ a colon) is a list with one member per line and the gloss after it;
+ a sentence never holds it. A rule, its reason, its exception and
+ its purpose are separate sentences: the rule first, in plain words;
+ "because", "unless" and "so that" each open a sentence of their own. A
+ possessive without its noun ("is the skill's", "is the intent's")
+ is written out: "is defined in", "belongs to", "is said by". An
+ apposition stands in brackets or after "such as" or "that is",
+ never between commas, where it would read as a list. No long dash
+ in prose: a colon, a full stop or a spaced hyphen where one would
+ stand; a code span and a quoted literal are copied as the owner has
+ them, dash included, so that a page and its owner agree. The owners
+ write in images (a thought is mined, chiselled, sifted, tempered;
+ the scripts are a door; the chain is a star): on a page the
+ mechanism stands in a plain clause at the first use, and at most one
+ image is kept beside it, never in place of it.