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.1 KiB
Process — overview
How work moves through HQ, and who may do what. Every other document in this folder is a playbook: trigger, who runs it, steps, outputs. Engineers and agents follow the same playbooks; agents must not act outside them.
The audiences
| Audience | Contract |
|---|---|
| Engineers | Read and write everything. HQ is the single source of truth for mission, research, design, decisions and issue diagnosis. |
| Agents | The same rights as engineers, exercised through these playbooks. |
| Anyone else | This repository is public and written for them, but it is not a support channel. Nothing here identifies the mesh it describes. |
The knowledge flow
idea ──► 01-RESEARCH ──► decision (02-DECISIONS/) ──► 03-DESIGN/01-to-be ──► built (code repo)
│ │ │
│ │ └─► 03-DESIGN/00-as-is once shipped
│ └────► abandoned (recorded, kept)
└─(small/obvious, still recorded in 02-DECISIONS)──────────► 03-DESIGN directly
symptom ──► 04-ISSUES ──► diagnosis ──► code-repo fix and/or design amendment
how-we-build.md ──► constitution sync ──► knowledge base ──► injected into design meetings
The two design layers
03-DESIGN holds two layers that are never mixed:
| Layer | What it is | Changes when |
|---|---|---|
00-as-is/ |
The mesh that exists today. Describes shipped behaviour, including behaviour nobody would choose again. | Something ships, or an as-is claim is found to be wrong. |
01-to-be/ |
The mesh being built toward. Every statement traceable to a record in 02-DECISIONS/. |
A decision is taken or amended. |
A to-be document that ships does not move. Its as-is counterpart is written or updated, the
to-be document's frontmatter goes to implemented, and both stand — one describing what runs,
the other recording what was intended. Deleting the intention loses the reasoning, which is
the expensive half.
The playbooks
| # | Playbook | Trigger |
|---|---|---|
| 01 | Research | An idea worth investigating before committing to design |
| 02 | Graduation & design change | Research concludes, or a design must change |
| 03 | Issues | Something is wrong — often with the owner unknown |
| 04 | Build handoff | A design is ready to be built |
| 05 | Constitution sync | how-we-build.md changed a rule the mesh enforces |
Status lives in frontmatter
Research overviews, design docs, issue reports and decision records each carry their status as
YAML frontmatter (schemas in the section READMEs and playbooks). There are no central status
files and no decision ledger. Every decision is a record in
02-DECISIONS — if it is worth recording it is worth a record, and if
it is not worth a record it is not recorded. Cross-cutting views, the decision index included,
are generated on demand by the hq-status skill and never written to disk.