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.
88 lines
5.3 KiB
Markdown
88 lines
5.3 KiB
Markdown
# 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](01-research.md) | Research | An idea from the operator, or one worth investigating before committing to design: setup questions, findings, a direction the operator confirms |
|
|
| [02](02-graduation.md) | Graduation & design change | Research concludes (its direction confirmed), or a design must change: decision records, the to-be design |
|
|
| [03](03-issues.md) | Issues | Something is wrong — often with the owner unknown |
|
|
| [04](04-build-handoff.md) | 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](05-constitution-sync.md) | Constitution sync | `how-we-build.md` changed a rule the mesh enforces |
|
|
| [06](06-writing-a-module.md) | Writing a module | Something that runs today must run on the mesh |
|
|
| [07](07-feature-branches.md) | Features | Work that changes code across issues or repositories: prepared context, local development, one review, one check, one delivery |
|
|
| [08](08-small-fixes.md) | 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`](../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](04-build-handoff.md) and [07](07-feature-branches.md):
|
|
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](02-graduation.md)).
|
|
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](03-issues.md)). 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.
|