README: explain how many builders share one main

The repo is built by several people at once against a single branch,
and nothing in the README said so. The new section carries the
concentric-rings diagram and states the rule that makes it work: a
builder captures main before pushing, resolves every conflict while
holding it, then releases.

Placed before "Repository layout" — it answers the question a reader
has after seeing the studio and before reading a folder list.
This commit is contained in:
doxa-maps-88655c70 2026-09-24 17:46:42 +00:00
parent bea4a4ff2d
commit fdaeb7b44b
2 changed files with 24 additions and 0 deletions

View file

@ -366,6 +366,30 @@ sanity-check one bundle without touching anyone else's output, use
---
## The delegation model — one build, many agents, one main
This repo is designed for **many builders working in parallel without stepping on each
other**. The model is a set of concentric rings:
![The delegation model: concentric rings from main outward to the shepherd](documentation/readme-images/delegation-model.png)
- **`main`** — the one shared branch. Everything converges here.
- **Capture ring** — before pushing to `main`, a builder must *capture* it: **one builder at
a time, first-come-first-serve.** Whoever holds it **resolves all merge conflicts**, lands
their work, then releases. The next builder waits and retries. No two pushes race.
- **Plugin Studio** — one repo, every plugin visible in one place, so each builder can see
what already exists and reuse it.
- **Plugins** — each is built in the shared bundler, so its shared, parameterized components
become available to every other plugin (private components stay inside each plugin's own
folder).
- **Agents** — **one builder per plugin.** Each owns their plugin end to end. A cluster of
experimental plugins is owned by a single roaming builder.
- **Shepherd** — one builder keeps everyone honoring the model: plugins built in the studio,
shared components truly shared, and every push serialized through the capture ring.
The effect is cooperative: each builder races to land the most working features, but the only
way to score is to pass through the capture ring one at a time and **leave `main` green.**
## Repository layout
Two directories matter to a plugin author:

Binary file not shown.

After

Width:  |  Height:  |  Size: 228 KiB