jschoubben
464833d0ef
mesh/merge-gate head 464833d0ef3f merged into trunk 99a9da095010 — pass: the change touches no module of the mesh's graph
mesh/repo-check head 464833d0ef3f merged into trunk 99a9da095010 — pass: its merge-check.sh passed
mesh/delivery superseded: a newer head of the same pull request
A feature waited a day for its last issue, each small issue paid for its context again, and waits nobody saw cost the most time. The operator set the flow on 2026-10-15: prepared context per repository, one to two hours of local development on unit tests, one review of at most three rounds back to the same agents, one push for the integration checks, then the delivery plan; steps for a larger feature; a separate playbook for small fixes; models per step; a wait list with bounds; a prepared clear at each phase end.
88 lines
5.1 KiB
Markdown
88 lines
5.1 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 worth investigating before committing to design |
|
|
| [02](02-graduation.md) | Graduation & design change | Research concludes, or a design must change |
|
|
| [03](03-issues.md) | Issues | Something is wrong — often with the owner unknown |
|
|
| [04](04-build-handoff.md) | Build handoff | A design is ready to be built |
|
|
| [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.
|