hq/00-META/process/00-overview.md

Process — overview

How work moves through HQ, and who may do what. In industry terms this is spec-driven development, with provenance: the decision is the why, the design doc is the spec, code: names the implementation, and the lab beds are the conformance tests — and unlike the common form, the chain itself is checked (ADR 0080, ADR 0081). 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 ──► research ──► decision ──► 03-DESIGN/01-to-be ──► built (code repo)
 │            │                            │
 │            │                            └─► 03-DESIGN/00-as-is once shipped
 │            └────► abandoned (recorded, kept)
 └─(small/obvious, still a decision record)──────────► 03-DESIGN directly

research and decisions: in the knowledge base (knowledge-base.reserve, propose, ask, get, holds)

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 decision record in the knowledge base.	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.

A design is built as it is written

Research, decisions and the review by architectural domain are where the mesh's choices are made; building makes none (the operator, 2026-11-10). A design is written to be built without a choice of the builder's own, in a main file and one part per milestone that an agent reads whole (playbook 02, The shape of a design). The prepare, develop and the code review of playbook 07 read only that design: the prepare says where each design line lands in code and lists what the design does not answer, the operator answers each such design question and the answer is written into the design, and only then does develop start. Every commit cites the design lines it builds, and the review judges each change against its line. How it is checked: playbook 07's How it is checked (the build maps, the commits' Builds: lines, the design questions' answering hq commits).

The playbooks

A drawn overview of them, the cycle, a feature's steps, the review loop and an issue's life, is playbooks.html: a picture of these playbooks, never their authority.

#	Playbook	Trigger
01	Research	An idea from the operator, or one worth investigating before committing to design: setup questions, findings, a direction the operator confirms
02	Graduation & design change	Research concludes (its direction confirmed), or a design must change: decision records, the to-be design
03	Issues	Something is wrong — often with the owner unknown
04	Work breakdown and handoff	A design is ready to be built: milestones usable on their own, issues per repository, each milestone one feature step
05	Constitution sync	how-we-build.md changed a rule the mesh enforces
06	Writing a module	Something that runs today must run on the mesh
07	Features	Work that changes code across issues or repositories: a build map from the milestone's part of its design, the design complete before any code, local development, one review against the design lines, one check, one delivery
08	Small fixes	One issue in one repository, about an hour of work: one review, one check, one delivery
09	Cleanup	Merged branches, stale pull requests, finished worktrees and folders: read first, delete only what the operator approves, report the rest
10	Visual design	A page the operator will use is about to be designed or rebuilt: mockups with fixed data, the operator picks, the pick is the reference

The cycle is checked

The flow above is a rule, and a rule states how it is checked: the cycle test in 00-META/checks/ refuses a to-be design that names no decision, an in-progress/implemented design that names no owning code, two issue folders sharing a number or an issue report carrying a status key; a graduated research effort that does not say what it became is refused by the knowledge base's propose (ADR 0290). Run it with the records, index and words tests before any HQ merge: go test ./... at the root runs all four, and the checker runs the same as mesh/check (ADR 0527). The issue rules the check once held — located with an owner, resolved with a fix, a core issue with its replay — are refused at the write by the issue tracker's move (ADR 0275). What the checks cannot see — that code work actually started from a handoff — is held by playbooks 04 and 07: a feature branch exists because a design or an issue sent it.

Status lives in frontmatter, an issue's in the tracker

Design docs carry their status as YAML frontmatter (schema in playbook 02). Research efforts and decision records carry theirs in the knowledge base, which refuses a wrong one at propose (ADR 0290). An issue's status lives in the issue tracker, which refuses a wrong status at the write, and its report here carries only the day it was opened (playbook 03). There are no central status files and no decision ledger. Every decision is a record in the knowledge base — 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 are generated on demand by the hq-status skill and never written to disk (ADR 0248); the decisions of a topic are knowledge-base.holds with that topic.