jschoubben
c77378fa19
The record and the records module for symptom search, the constitution page by its own name.
101 lines
7.0 KiB
Markdown
101 lines
7.0 KiB
Markdown
# 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`](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**
|
|
(in the knowledge base, 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? | 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`](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/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? | 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/`](04-ISSUES/) under its number |
|
|
| Which repo owns what code? | [`00-META/repos.md`](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`](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/` and `merge-check.sh` at the root, which
|
|
runs them on every pull request as its `mesh/repo-check` (ADR 0238).
|
|
No new top-level folders without explicit confirmation.
|
|
- **Status lives in YAML frontmatter** — on design docs (`layer`, `status`, `code`, `updated`,
|
|
and `decisions` as "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 carries
|
|
`opened` and nothing of its status (playbook [03](00-META/process/03-issues.md)).
|
|
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.reserve` and `knowledge-base.propose` (playbooks
|
|
[01](00-META/process/01-research.md) and [02](00-META/process/02-graduation.md)); `records.py` refuses a
|
|
new path under `02-DECISIONS/` or `01-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](00-META/process/02-graduation.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 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.
|