jschoubben
93a1231e00
Skills take the hq- prefix: they are HQ process workflows, not mesh workflows, and HQ is company-scoped now. hq-new-research, hq-graduate, hq-new-issue, hq-diagnose, hq-amend-design, hq-handoff, hq-sync-constitution, hq-status. Forward-looking prose becomes Novox Mesh or simply the mesh — the root README, AGENTS.md, the 00-META README, the mission's module example, and one to-be document that addressed 'someone working on HAL'. Three categories deliberately keep HAL, per ADR 0027: The monorepo is still called hal on the forge. repos.md, every code: field and every located-in: field name a repository that exists under that name, and renaming them in prose would make them false. The as-is layer and the research that measured it describe the system that runs, and that system is called HAL. 124 modules, 9 daemons, a dead containerised node — those are observations, not intentions. Records 0001-0026 are immutable. A record says what was decided when it was decided, and no record is edited for a name. Also repoints ADR 0022's link at the renamed skill — a path fix, which the immutability rule permits, not a change of meaning.
3.0 KiB
Agent instructions — Novox HQ
This repository is the source of truth for Novox's mission, research, design and decisions —
today almost entirely those of Novox Mesh, its first product (ADR 0028). 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.
Ground rules
- Markdown only. No new top-level folders without explicit confirmation.
- Status lives in YAML frontmatter — on research overviews (
status,became), design docs (layer,status,code,updated), issue reports (status,located-in,fixed-by,amended-design) and decision records (status,date,deciders). Never create a central status file; cross-cutting views are generated from frontmatter. 02-DECISIONS/records are immutable. Supersede with a new record; never edit meaning. Fixing a broken link or path is allowed.- 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.