jschoubben
cabe873503
Records the branching-and-merging workflow for code changes across the mesh repos, written against a failure it names: branches and MRs opened per unit of thought, treated as done when opened not merged, and named differently per repo, so they pile up unmerged — one session left sixteen to consolidate by hand. The rule is one feat/<slug> shared across every repo a feature touches, isolated in .work/<slug>/<repo> worktrees off main, pushed and opened as one MR per repo only when the whole feature is done, then merged promptly. Adds the ground-rule pointer in AGENTS.md and the row in the process overview. Claude-Session: https://claude.ai/code/session_01LrgweAeERJYBg88c5cKDzF
57 lines
3.5 KiB
Markdown
57 lines
3.5 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 0028](02-DECISIONS/0028-hq-is-company-scoped.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, feature branches) 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/`](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.
|
|
- **One feature, one branch, one MR per repo.** A code change spanning one or more repos uses a
|
|
single `feat/<slug>` shared across every repo it touches, isolated in `.work/<slug>/<repo>`
|
|
worktrees off `main`; push and open MRs only when the whole feature is done, then merge
|
|
promptly and delete the branch. Per-increment branches and MRs that pile up unmerged are the
|
|
failure this prevents — see playbook
|
|
[`06-feature-branches.md`](00-META/process/06-feature-branches.md).
|
|
|
|
## 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.
|