jschoubben
01a0a3a4d9
The registry move, seat definitions, declares, bus state and the knowledge base ship as one milestone (ADR 0612, 0613), ordered by the module graph's edges (ADR 0614), with the foundation parts' first view (ADR 0615) and the overview page (ADR 0616). The designs said four deliveries, a seat-definition source nobody serves, a checker naming mesh-config, and left the bus module's first view, caller and deletion paths open; they now say what the milestone builds. Adds the glossary words it uses, playbook 02's cites link for an abandoned effort, and the hq-design-writer agent definition. Claude-Session: https://claude.ai/code/session_01JG73KJNrH5EgFXMKKYSrig
117 lines
8.9 KiB
Markdown
117 lines
8.9 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`, `hq-cleanup`); each defers to its playbook as
|
|
authoritative and adds only the mechanical scaffolding. Four reviewer agents in `.claude/agents/` carry
|
|
playbook 01's *Review by architectural domain*, two architectural domains each:
|
|
`review-security-and-upgrade`, `review-seams-and-tools`, `review-running-and-testing` and
|
|
`review-health-and-events`; the lead starts all four side by side and rules on their findings. A fifth,
|
|
`research-reader`, carries one reading task of playbook 01's step 5: code on main, counts from the manifests, a
|
|
try in process. Four more carry playbook 07: `mesh-preparer` (the prepare step), `mesh-developer` (develop),
|
|
`mesh-code-reviewer` (the review) and `mesh-watcher` (every wait). A tenth, `hq-design-writer`, writes one set of design amendments
|
|
(playbook 02, *Amending an existing design*) from accepted decisions and a milestone's findings, in a worktree of its
|
|
own, ready for the review by architectural domain. Every agent starts from the knowledge base and maps
|
|
each interaction onto a mesh path; the lead writes only the handover, never an agent's way of working. A subagent runs in the session that started it, from hq: its way of working comes from its definition and hq's playbooks, its knowledge from the knowledge base; one given a coding task works in a worktree under hq's `.work/` and also reads the conventions of the repository it changes, and where those contradict hq, hq wins and the agent says so.
|
|
|
|
## 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 the cycle test in
|
|
[`00-META/checks/`](00-META/checks/) alongside the records, index and words tests — run `go test ./...` at the
|
|
root 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 the words test in `00-META/checks/` fails on it
|
|
in running prose; a quotation keeps its words.
|
|
|
|
## Ground rules
|
|
|
|
- **Markdown only** — but for the four checks, Go tests in the package `00-META/checks/` with `go.mod` at the
|
|
root and no other Go code (ADR 0527), which the checker runs on every pull request as `mesh/check`; and
|
|
`00-META/process/playbooks.html`, a drawn overview of the playbooks kept for a later docs site (the operator,
|
|
2026-10-19); a change to a playbook's steps updates it in the same pull request. Nothing checks that
|
|
yet: issue 1222 asks for the check.
|
|
A to-be design may also keep its reference mockup, the static HTML page the operator picked, in a
|
|
folder beside it (`NN-mockup/`, playbook [10](00-META/process/10-visual-design.md); the operator,
|
|
2026-10-22), its data invented: no real names, addresses, domains, providers or amounts.
|
|
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)); the records test 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.
|