jschoubben
418261213c
ADR 0290 rule 9: once the import is checked record by record, hq keeps no copy. The records and efforts are removed; every link or path to them reads "ADR NNNN" or "research NNN"; a design's decisions: lists "ADR NNNN". 02-DECISIONS keeps a pointer README with the reading order's six topics, which the knowledge base reads through the records module; 01-RESEARCH keeps a pointer README. The checks drop the rules that judged records (the knowledge base holds each at propose; checks/README.md says where) and refuse a record written here again. Playbooks 01 and 02 and the skills write and read records with the knowledge base's verbs.
7.0 KiB
Agent instructions — Novox HQ
This repository is the source of truth for Novox's mission and design —
today almost entirely those of Novox Mesh, its first product (ADR 0019). Its decision records and
research efforts live in the knowledge base, the seat knowledge-base (ADR 0290), and nowhere here.
Implementation lives in the code repositories (see 00-META/repos.md).
Before changing anything here, read the playbooks in
00-META/process/ — every workflow (research, graduation, design
amendment, issues, build handoff, constitution sync) is documented there, and agents operate
through them. Thin skills in .claude/skills/ wrap these playbooks for invocation
(hq-new-research, hq-graduate, hq-new-issue, hq-diagnose, hq-amend-design,
hq-handoff, hq-sync-constitution, hq-status); each defers to its playbook as
authoritative and adds only the mechanical scaffolding.
The development cycle
Work enters as an idea (playbook 01 — research) or a
symptom (playbook 03 — issues), becomes a decision
(in the knowledge base, via playbook 02), lands in a
to-be design naming that decision, is handed to a code repository (playbook
04, on a feature branch per playbook
07) — and on shipping the as-is is updated and the
design flips to implemented. No design without a decision; no development without a design
that names its owner. Enforced by 00-META/checks/cycle.py
alongside records.py, index.py and words.py — run all four before any merge here.
Where to look (before assuming anything)
| Question | Read |
|---|---|
| What does this word mean? | 00-META/glossary.md |
| How do I do X in this repo? | 00-META/process/ — the playbook index is in 00-overview.md |
| What was decided, and why? | the knowledge base, through the mesh MCP server: knowledge-base.ask with the question in plain words, knowledge-base.get with a record's number (reasoning: true for the why), knowledge-base.holds with a topic of the reading order (02-DECISIONS/README.md) |
| What was researched? | the knowledge base: knowledge-base.ask, or knowledge-base.get with kind: research and its number |
| What is being built / already runs? | 03-DESIGN/01-to-be/ / 03-DESIGN/00-as-is/ — each doc's frontmatter says its status, decisions and owning code |
| What is broken or was? | the issue tracker: issue-tracker.list and issue-tracker.get through the mesh MCP server; a design or governance issue's narrative is in 04-ISSUES/ under its number |
| Which repo owns what code? | 00-META/repos.md |
| Cross-cutting status view? | the hq-status skill (generated, never stored) |
A design's status lives only in its frontmatter; follow the pointers there (decisions:, code:)
instead of reconstructing history from memory. A decision record's and a research effort's status and links
live in the knowledge base (ADR 0290); knowledge-base.links gives a record's links both ways. An issue's
status, owner and fix live in the issue tracker (ADR 0275).
Words
One name per thing. 00-META/glossary.md is the authority on
vocabulary, organised by the mesh's domains (ADR 0244):
controller (not "control plane"), foundation (not "substrate"), node-engine (not "the host"), a
node is a machine the mesh has adopted, seat / bench / claim, package vs artifact. Use those
words. A retired word is named on its replacement's Not: line, and 00-META/checks/words.py fails on it
in running prose; a quotation keeps its words.
Ground rules
- Markdown only — but for the checks in
00-META/checks/andmerge-check.shat the root, which runs them on every pull request as itsmesh/repo-check(ADR 0238). No new top-level folders without explicit confirmation. - Status lives in YAML frontmatter — on design docs (
layer,status,code,updated, anddecisionsas "ADR NNNN"). A decision record's and a research effort's status live in the knowledge base, and an issue's status, owner and fix in the issue tracker, not here: an issue report carriesopenedand nothing of its status (playbook 03). Never create a central status file; cross-cutting views are generated when they are read. - No decision record or research effort is written here. They live whole in the knowledge base and
are written with
knowledge-base.reserveandknowledge-base.propose(playbooks 01 and 02);records.pyrefuses a new path under02-DECISIONS/or01-RESEARCH/. A record is cited as "ADR NNNN" or "research NNN". - Decision records hold their meaning. Supersede with a new record rather than rewriting what was decided, the options weighed, or a consequence another record relies on. A progressive insight — a correction of fact that leaves the decision standing — is a new version of the record, marked and dated (playbook 02). A fact going stale is not the decision going wrong, and superseding a sound record for one buries it.
- Design docs are prose and diagrams only — no code. A manifest field may be named; a manifest may not be pasted.
- Two layers, never mixed.
03-DESIGN/00-as-is/describes the mesh that exists;03-DESIGN/01-to-be/describes the one being built toward. Every design doc says which it is inlayer:. A statement about the future does not belong in an as-is document, and an as-is document is never edited to describe an intention. 00-META/how-we-build.mdis the source of the mesh constitution. The knowledge-base constitution page is derived from it — see playbook05-constitution-sync.md. Never edit the derived page directly.
This repository is public
Nothing here may contain routable addresses, real domain names, hosting providers, node
names, absolute paths, usernames, credentials, or operational detail useful only to an
attacker. Use documentation ranges (RFC 5737, RFC 1918) and role names — anchor,
home-server, workstation, laptop, the build node, the broker node.
The test: would this paragraph still teach a stranger running an entirely different mesh?
If yes, it belongs. If it only makes sense to someone who knows this installation, it is
either a note in the wrong place or a disclosure. The full rule is in
README.md.
A rule states how it is checked
If a document states a rule about the mesh, it says how that rule is verified. An unenforced rule is indistinguishable from a wrong one, and costs more, because people believe it.