jschoubben
0d66edb24c
The operator found 04 odd on 2026-10-15: it went from a settled design straight to building, with no work breakdown, and contradicted playbook 07 on pull requests. 01 now starts from the operator's idea with setup questions, findings and a direction the operator confirms; 02 graduates that direction into one record per reversible choice and hands the design on; 04 breaks it into milestones usable on their own, one issue per repository part, each milestone one feature step of 07. 01 notes the knowledge base's insight-only rule for an active effort until issue 844 is delivered.
5.3 KiB
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.
The playbooks
| # | 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: prepared context, local development, one review, one check, one delivery |
| 08 | Small fixes | One issue in one repository, about an hour of work: one review, one push, one delivery |
The cycle is checked
The flow above is a rule, and a rule states how it is checked:
00-META/checks/cycle.py 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 records.py, index.py and
words.py before any HQ merge (sh merge-check.sh runs all four). 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.