jschoubben
bc271d4de0
What the SDK contains, answered by exclusion as much as by inclusion. It is the protocol and nothing else — no configuration loader, because configuration arrives as files the mesh wrote; no API clients, because a Plex client changes when Plex changes and that has nothing to do with any other module; no storage, HTTP or logging, because the language has those. The test for anything proposed is ADR 0039's: does editing it recompile unrelated modules, and does it change often. Both, and it stays out. Then the worked module: events in TypeScript, tools in Go, a provisioner in Rust, a scheduled job in Python. Four artifacts, four toolchains, four processes, one module — and each part is an ordinary project in its language depending on the mesh SDK the ordinary way, so a laptop resolves what a build resolves. And publishing a package as a module capability, which makes the SDK unspecial: it is simply the first module that published a library. A Plex client belongs to the Plex module because that is the only thing that knows when Plex changed. Three things left open rather than papered over: which registry (the catalogue holds verdaccio and a forge usually serves one too, and nothing says which is ours), who may publish (a credential that does not exist), and what a range means in a mesh where everything else is pinned by digest — a mesh that can rebuild a commit and get a different library is a real change, and should be decided rather than arrived at. Claude-Session: https://claude.ai/code/session_01D6qtiYU3P9jk3pnAXyAFyx
03-DESIGN
The authoritative specification. Implementation is built against what is written here.
Two layers
| Folder | What it is |
|---|---|
00-as-is/ |
The mesh that exists today. Shipped behaviour, described as it is — including behaviour nobody would choose again. |
01-to-be/ |
The mesh being built toward. Every statement traceable to a record in 02-DECISIONS/. |
They are never mixed. A statement about the future does not belong in an as-is document, and an as-is document is never edited to describe an intention.
When a to-be design ships, it does not move. Its as-is counterpart is written or updated,
the to-be document's status becomes 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.
Frontmatter
Every design document (not the READMEs) carries:
---
layer: as-is | to-be
status: designed | in-progress | implemented | abandoned
code: [] # owning code repo(s), from 00-META/repos.md
updated: YYYY-MM-DD # date of the last status change, not of text edits
decisions: [] # 02-DECISIONS/ records this document rests on
---
For an as-is document, status: implemented is the normal state — it describes something that
runs — and code: names where that implementation lives.
Status changes when implementation state changes, never because design text was edited. An
implemented claim must be defensible from the owning repository's main branch, not from
intent. If it cannot be checked, it is in-progress.
Cross-cutting views are generated from this frontmatter by the hq-status skill and never
written to disk.
What belongs here
Functional analysis, architectural description, and specification — prose and diagrams
only, no code. A manifest field may be named; a manifest may not be pasted. A document
enters the to-be layer only after the decision behind it is recorded in 02-DECISIONS/
and the research that produced it is closed.
Subfolders are encouraged where a layer grows enough to need them.