jeffryandClaude Opus 5
5bfec6a48a
Routes by question rather than by repository — what is this .loom directory, how do I set it up, how do I depend on somebody's document, how do we work something out, how do I mark up your file. A newcomer has a question, not a repository name, and a list of moves can be used before it is understood where an inventory must be read first. Points at jeffry/homelab-cluster for anyone who would rather see one than read about it. Says what each repository is for and does not list what is in the organisation: the platform already answers that, and a hand-written list is a claim of completeness that goes wrong the first time somebody adds a repository. A repository with no line here is unannotated rather than excluded. Names registry as not built and settled as private, so neither reads as a dangling reference. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
loom
Making things legible between a person and an agent, across repositories and across time.
Most of what an agent needs to know is not in the code it is looking at. It is in another repository, or in a cluster, or in how the two of you have agreed to work. These are the conventions for writing that down where it can be found, and for finding out when it changes.
Start with the question, not the repository
| if you are asking | go to |
|---|---|
"what is this .loom directory?" |
bedrock |
| "how do I set this up in a repository?" | bedrock → starting |
| "how do I depend on somebody's document and know when it changes?" | externals |
| "how do we work something out before one of us changes it?" | cart |
| "how do I mark up your file without editing it?" | annotating |
| "why is it like this?" | settled — private, and every repository's own .loom/event-log.md |
And if you want an example rather than a description:
jeffry/homelab-cluster
— six documents and one gap, written for somebody who has to decide something.
What each one is
bedrock — the primitives.
What a .loom directory is, how a facet sits beside a file, what an entry says,
what publishing means. Most repositories never need to read it; its audience
is people building conventions rather than using them.
externals — how a repository records what it depends on. Pull a copy, keep your usages and gaps beside it, reconcile when it changes.
cart — a bounded round between two parties, which starts, runs, converts, and is gone. For when neither of you knows yet.
annotating — how two parties mark up each other's files without either of them diffing anything. Everything else here rests on it.
registry — not built. A service that would aggregate gaps across
repositories and explain itself to somebody arriving cold. Everything else
works without it, deliberately.
settled — private. Decisions about the shape of all this.
This index says what each thing is for. It does not list what is in this organisation — the platform already answers that, and a hand-written list would be a claim of completeness that goes wrong the first time somebody adds a repository. A repository with no line here is unannotated, not excluded.