jochen
a28da1734b
ADR 0244 sorts the mesh's concepts into ten domains (ADR 0006's contexts carry over as domains), keeps machine and node as distinct words, and makes the glossary the authority with every retired word on its replacement's Not: line. To-be 49 draws the domains; the glossary is reorganised by them, its two contradictions removed and the missing words added. words.py now fails on a retired word in running prose and on a word defined twice, so the rule is enforced rather than believed; the 63 documents it failed on are reworded here, and research 034 is kept as the record of the words it studied.
93 lines
6.1 KiB
Markdown
93 lines
6.1 KiB
Markdown
# 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 0019](02-DECISIONS/0019-how-this-repository-works.md)). Implementation lives in the code repositories (see
|
|
[`00-META/repos.md`](00-META/repos.md)).
|
|
|
|
Before changing anything here, read the playbooks in
|
|
[`00-META/process/`](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](00-META/process/01-research.md)) or a
|
|
**symptom** (playbook [03 — issues](00-META/process/03-issues.md)), becomes a **decision**
|
|
([02-DECISIONS](02-DECISIONS/), via playbook [02](00-META/process/02-graduation.md)), lands in a
|
|
**to-be design** naming that decision, is handed to a code repository (playbook
|
|
[04](00-META/process/04-build-handoff.md), on a feature branch per playbook
|
|
[07](00-META/process/07-feature-branches.md)) — 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`](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`](00-META/glossary.md) |
|
|
| How do I do X in this repo? | [`00-META/process/`](00-META/process/) — the playbook index is in `00-overview.md` |
|
|
| What was decided, and why? | [`02-DECISIONS/README.md`](02-DECISIONS/README.md) (reading order), then the record |
|
|
| What is being built / already runs? | [`03-DESIGN/01-to-be/`](03-DESIGN/01-to-be/) / [`03-DESIGN/00-as-is/`](03-DESIGN/00-as-is/) — each doc's frontmatter says its status, decisions and owning code |
|
|
| What is broken or was? | [`04-ISSUES/`](04-ISSUES/) — frontmatter carries status/owner/fix |
|
|
| Which repo owns what code? | [`00-META/repos.md`](00-META/repos.md) |
|
|
| Cross-cutting status view? | the `hq-status` skill (generated, never stored) |
|
|
|
|
Statuses live **only** in frontmatter; follow the pointers there (`decisions:`, `code:`,
|
|
`became:`, `fixed-by:`) instead of reconstructing history from memory.
|
|
|
|
## Words
|
|
|
|
One name per thing. [`00-META/glossary.md`](00-META/glossary.md) is the authority on
|
|
vocabulary, organised by the mesh's domains ([ADR 0244](02-DECISIONS/0244-the-mesh-is-described-in-domains-and-one-word-names-one-thing.md)):
|
|
*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/` and `merge-check.sh` at the root, which
|
|
runs them on every pull request as its `mesh/repo-check` ([ADR 0238](02-DECISIONS/0238-a-commit-is-the-build-at-hand-one-commit-one-change-plan-checked-off-the-trunk-and-published-only-on-it.md)).
|
|
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 hold their meaning.** Supersede with a new record rather than rewriting
|
|
what was decided, the options weighed, or a consequence another record relies on. Fixing a broken
|
|
link or path is allowed, and so is a **progressive insight** — a correction of *fact* that leaves
|
|
the decision standing, made in place, marked and dated in the record's own words
|
|
([`02-DECISIONS/README.md`](02-DECISIONS/README.md)). 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/`](03-DESIGN/00-as-is/) describes the mesh
|
|
that exists; [`03-DESIGN/01-to-be/`](03-DESIGN/01-to-be/) describes the one being built
|
|
toward. Every design doc says which it is in `layer:`. 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.md` is the source of the mesh constitution.** The knowledge-base
|
|
constitution page is derived from it — see playbook
|
|
[`05-constitution-sync.md`](00-META/process/05-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`](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.
|