jschoubben
becae7ba51
The flow the process overview draws — idea/symptom -> decision -> to-be design -> code -> as-is — was enforced by nothing. cycle.py now refuses a to-be design naming no decision, an in-progress/implemented design naming no owning code, a located/fixed issue with no owner, a fixed/resolved issue with no fix, and a graduated research overview that does not say what it became. AGENTS.md carries the cycle and a where-to-look table so a fresh session (or a cleared context) finds the chain in frontmatter instead of assuming it. Grounding the check surfaced two real gaps, fixed here: the work-ahead design named no owning code, and research 003 listed one became target twice. https://claude.ai/code/session_01D6qtiYU3P9jk3pnAXyAFyx
74 lines
4.0 KiB
Markdown
74 lines
4.0 KiB
Markdown
# 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](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) | Feature branches across repos | Work that changes code, in one repo or several at once |
|
|
|
|
## 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, an issue marked
|
|
`located`/`fixed` with no owner or `fixed`/`resolved` with no fix, and a `graduated`
|
|
research overview that does not say what it became. Run it with `records.py` and `index.py`
|
|
before any HQ merge. 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
|
|
|
|
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`](../../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.
|