Herbarium
A specimen is pressed once, labelled, and shelved where it can be found.
The same plant is not pressed twice. A document is a specimen: one house,
one label, and every other document that needs it points at the shelf.
This file owns the pattern. The houses a project keeps, the levers for
writing a document an agent will run, and the CLI are in
references/houses.md.
The rule
One house per fact; pointers, not copies. Before writing a sentence,
ask where that fact already lives. If it lives somewhere, link there. If
it lives nowhere, put it in the house the reference names for its kind
and link from where you are. A fact restated in a second file is a fact
that will be wrong the next time its home changes; check counts those.
Write
- Name the kind. The reference lists the eleven kinds and the house
each one has. A document that is two kinds is two documents.
- Front-load the leading word and the one defining constraint. A
reader, human or agent, decides in the first line whether to keep
reading; the pointer to this document, wherever it sits, uses the same
word.
- Keep steps and reference apart. Steps in order, each ending on a
criterion a reader can check: done or not done, with a number where
one exists. Reference consulted on demand goes below the steps or
behind a pointer; what only some readers need goes behind a pointer.
- Let the environment speak. A command's
--help, a config file, a
directory listing are sources of truth. Write down the convention that
is not in them and the reason behind a choice; leave the lookups where
they cannot go stale.
- Say the positive. State the behaviour wanted; a prohibition earns a
line only as a hard guardrail, paired with the positive it protects.
- Prune. Every line either changes what the reader does or leaves.
Layers that settled because adding felt safe are sediment; core through
them.
Check
de-novo skills herbarium check # links n/n · copies n · language n · pages n/n · archive n
Run it before a document lands, and let CI run it on every change. A
broken link or anchor, a copied sentence, a public surface whose prose is
in another script, a page over its cap, or a generated snapshot that
names no source and revision is a non-zero exit. Similar paragraphs and
links from active documents into the archive are shown, not judged: a
person decides whether they are a paraphrase, a citation, or a
leftover. The check also says how many bytes an agent loads across the
public surfaces, with a token estimate that names itself one.
Retire
A design that is no longer operating authority moves to the archive with
its date and a link to what replaced it. Active instructions do not lean
on it. It is not deleted: a reader who finds an old decision should be
able to read why it was made.
Invariants — not weakenable
- One house per fact. A second copy is a defect the check counts. A
summary in your own words that points at its source, and a generated
snapshot that names what made it and when, are not copies: the source
stays the one place to edit, and the reader can tell how old they are.
- The CLI never edits. It counts; a person or an agent moves the text.
- Public surfaces are one language, the one the values file names.
- A human page is short. Its prose stays under the cap; a diagram in a
fence or a table is looked at, not read, and does not count.
- Retired documents are kept, dated, and pointed at what replaced them.
Not this skill
- Deciding what is true. Mycelium holds facts; this holds the documents
that point at them.
- Writing the record of a sprint. Understory does that, under this rule.
- A documentation site, a publishing pipeline, a translation workflow.
1---2name: herbarium3description: de-novo Herbarium — every document a project keeps has one house, and the rest point at it. Use whenever you are about to write, move, rename, or review a document that someone else will read: a README, a skill, a design note, an evidence record, a reference, working rules for agents. Use when a fact seems to live in two files, when a document is getting long, when a link may have gone stale, or when the user runs /herbarium. Values live in .agents/herbarium.yml (the houses, the language, the page cap). The CLI counts drift; it never edits a document.4---56# Herbarium78A specimen is pressed once, labelled, and shelved where it can be found.9The same plant is not pressed twice. A document is a specimen: one house,10one label, and every other document that needs it points at the shelf.1112This file owns the pattern. The houses a project keeps, the levers for13writing a document an agent will run, and the CLI are in14[references/houses.md](references/houses.md).1516## The rule1718**One house per fact; pointers, not copies.** Before writing a sentence,19ask where that fact already lives. If it lives somewhere, link there. If20it lives nowhere, put it in the house the reference names for its kind21and link from where you are. A fact restated in a second file is a fact22that will be wrong the next time its home changes; `check` counts those.2324## Write25261. **Name the kind.** The reference lists the eleven kinds and the house27 each one has. A document that is two kinds is two documents.282. **Front-load the leading word** and the one defining constraint. A29 reader, human or agent, decides in the first line whether to keep30 reading; the pointer to this document, wherever it sits, uses the same31 word.323. **Keep steps and reference apart.** Steps in order, each ending on a33 criterion a reader can check: done or not done, with a number where34 one exists. Reference consulted on demand goes below the steps or35 behind a pointer; what only some readers need goes behind a pointer.364. **Let the environment speak.** A command's `--help`, a config file, a37 directory listing are sources of truth. Write down the convention that38 is not in them and the reason behind a choice; leave the lookups where39 they cannot go stale.405. **Say the positive.** State the behaviour wanted; a prohibition earns a41 line only as a hard guardrail, paired with the positive it protects.426. **Prune.** Every line either changes what the reader does or leaves.43 Layers that settled because adding felt safe are sediment; core through44 them.4546## Check4748```bash49de-novo skills herbarium check # links n/n · copies n · language n · pages n/n · archive n50```5152Run it before a document lands, and let CI run it on every change. A53broken link or anchor, a copied sentence, a public surface whose prose is54in another script, a page over its cap, or a generated snapshot that55names no source and revision is a non-zero exit. Similar paragraphs and56links from active documents into the archive are shown, not judged: a57person decides whether they are a paraphrase, a citation, or a58leftover. The check also says how many bytes an agent loads across the59public surfaces, with a token estimate that names itself one.6061## Retire6263A design that is no longer operating authority moves to the archive with64its date and a link to what replaced it. Active instructions do not lean65on it. It is not deleted: a reader who finds an old decision should be66able to read why it was made.6768## Invariants — not weakenable6970- **One house per fact.** A second copy is a defect the check counts. A71 summary in your own words that points at its source, and a generated72 snapshot that names what made it and when, are not copies: the source73 stays the one place to edit, and the reader can tell how old they are.74- **The CLI never edits.** It counts; a person or an agent moves the text.75- **Public surfaces are one language**, the one the values file names.76- **A human page is short.** Its prose stays under the cap; a diagram in a77 fence or a table is looked at, not read, and does not count.78- **Retired documents are kept**, dated, and pointed at what replaced them.7980## Not this skill8182- Deciding what is true. Mycelium holds facts; this holds the documents83 that point at them.84- Writing the record of a sprint. Understory does that, under this rule.85- A documentation site, a publishing pipeline, a translation workflow.
de-novo