diff --git a/README.md b/README.md index f66904ad5..6790fe48d 100644 --- a/README.md +++ b/README.md @@ -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: diff --git a/documentation/readme-images/delegation-model.png b/documentation/readme-images/delegation-model.png new file mode 100644 index 000000000..a82b5ef25 Binary files /dev/null and b/documentation/readme-images/delegation-model.png differ