diff --git a/README.md b/README.md index f8df786b6..af2c5bafb 100644 --- a/README.md +++ b/README.md @@ -70,7 +70,7 @@ capabilities, three outputs, one shared library, one build. | **One app nests every map** — and each stays embeddable on its own | [capability 5](#capability-5--app-shell-the-research-gallery) · `bun run check:composite-reg` | | **5 capabilities, every one shippable in every output** | `bun run verify:5-caps` | | **Shared library, private plugins** — reuse without breaking each other | `bun run check:library-index` | -| **One owner per plugin, a second reader for every change, one landing at a time** | [agent swarm](#build-it-with-an-agent-swarm) | +| **One owner per plugin, a second reader for every change, one merge at a time** | [agent swarm](#build-it-with-an-agent-swarm) | ## For vibe coders: build, open the Studio, embed a map @@ -698,7 +698,7 @@ your own page, set `"locale"` in its `profile-config`. Arabic reads right to lef has one agent that owns it, and the work moves through three kinds of branch: - **The pilot branch (`development`)** is the shared working version. A development server with hot - reload follows it, so each change that lands can be seen there within seconds. + reload follows it, so each change that lands can be seen there within about 15 seconds. - **The landing branch (`main`)** is production. It moves only when you publish, and the production server rebuilds from it. - **PR branches** hold one feature each. They start from the landing branch and land on the pilot @@ -706,10 +706,10 @@ has one agent that owns it, and the work moves through three kinds of branch: **Bring your own harness.** dx-maps works with whatever AI coding agent or agent harness you already use. The repo gives you the branch strategy below, the checks (`bun run gates:pre`) and the Plugin -Studio; it does not ship a harness. Roles such as a coordinator that puts the landings in order, or a +Studio; it does not ship a harness. Roles such as a coordinator that puts the merges onto the pilot in order, or a gate-keeper that reads each change before it lands, are jobs your harness gives to its agents. -![The delegation model: the pilot branch (development) at the centre behind a landing lock, the landing branch (main) below it, inside the Plugin Studio; eight plugins around it, each owned by one agent; a coordinator and a gate-keeper over the agents; below, how a change lands in four steps, and the three outputs](documentation/readme-images/delegation-model.png) +![The delegation model: the pilot branch (development) at the centre behind the pilot lock; publishing to the landing branch (main) and its outputs below it; inside the Plugin Studio; eight plugins around it, each owned by one agent; a coordinator and a gate-keeper over the agents; below, how a change lands in four steps, and the three outputs](documentation/readme-images/delegation-model.png) [Open the diagram full size](documentation/readme-images/delegation-model.png): on a phone its small text needs it. @@ -767,8 +767,8 @@ gate-keeper that reads each change before it lands, are jobs your harness gives Keep the repository on a forge you host yourself: a swarm pushes often, and on a public host one wrong push publishes work you did not mean to share. Give each app two servers: a **pilot server** that follows the pilot branch with hot reload, and a **landing server** that rebuilds from the landing -branch. The cloud container in `deployment/cloud/` runs both today (set its `BRANCH` to `development` -for the pilot server; the default is `main`). One pilot server per app, rather +branch. The cloud container in `deployment/cloud/` runs both today (`BRANCH=development` for the pilot server, +`PRODUCTION_BRANCH=main` for the landing server; `BRANCH` defaults to `main`). One pilot server per app, rather than one per pull request, keeps the memory the same however many pull requests are open. Each developer can still build on their own machine with the Plugin Studio and push their branch. @@ -793,10 +793,10 @@ So the project works like a busy kitchen: 1. **Each agent works in its own branch and copy of the project** — its own counter, so nobody bumps anybody. One owner per plugin, and one per shared file. -2. **Only one change lands at a time.** Whoever holds the *landing lock* first catches up with +2. **Only one change lands at a time.** Whoever holds the *pilot lock* first catches up with everyone else's latest work, fixes any clash itself and runs every check; the change goes into the pilot branch only if nothing fails. The pilot branch always works. -3. **Someone keeps order.** A coordinator can put the landings in order, and a gate-keeper can read +3. **Someone keeps order.** A coordinator can put the merges onto the pilot in order, and a gate-keeper can read each change by its content before it lands. Your harness gives these jobs to its agents. 4. **The landing branch moves only when you publish**, after the checks pass on that exact version. The pilot server follows the pilot branch; the production server rebuilds from the landing branch. @@ -811,12 +811,12 @@ That's how many plugins get built at the same time, in one project, without the | Word | In plain terms | |---|---| | **repo** | the project folder, with its full history | -| **development** | the shared working version: every agent's change is added here, one at a time | -| **main** | the production version: it moves only when `development` is published | +| **development** (the pilot) | the shared working version: every agent's change is added here, one at a time | +| **main** (the landing) | the production version: it moves only when `development` is published | | **worktree** | a private copy of the project for one agent to work in | | **merge conflict** | two changes touched the same lines; someone has to decide how to combine them | -| **rebase** | catching your work up with everyone else's latest before adding it | -| **landing lock** | only one change lands on `development` at a time; its holder catches up and runs every check first | +| **merge** | combining your branch with everyone else's latest work; here it happens inside the pilot lock, in a throwaway copy of the pilot | +| **pilot lock** | only one change merges onto `development` at a time; its holder catches up and runs every check first | | **tag** | a fixed name for one release commit, such as `v1.0.0`, so you can always deploy exactly it | diff --git a/documentation/readme-images/delegation-model.png b/documentation/readme-images/delegation-model.png index 55f5cfd6b..ad16d0da6 100644 Binary files a/documentation/readme-images/delegation-model.png and b/documentation/readme-images/delegation-model.png differ diff --git a/documentation/readme-images/src/delegation-model.svg b/documentation/readme-images/src/delegation-model.svg index 80e24c835..a773495cc 100644 --- a/documentation/readme-images/src/delegation-model.svg +++ b/documentation/readme-images/src/delegation-model.svg @@ -10,7 +10,7 @@ -How dx-maps is built: one owner per plugin, one landing at a time +How dx-maps is built: one owner per plugin, one merge at a time @@ -29,8 +29,8 @@ -LANDING LOCK -ONE LANDING AT A TIME +PILOT LOCK +ONE MERGE AT A TIME @@ -122,14 +122,14 @@ coordinator gate-keeper -a coordinator puts the landings in order; +a coordinator puts the merges in order; a gate-keeper checks each one by its content one owner per plugin, in its own branch · a second reader for every change pilot branch (development) -landing lock — one at a time +pilot lock — one at a time Plugin Studio — the one repo @@ -139,9 +139,9 @@ agent — owns one plugin -coordinator — orders landings +coordinator — orders merges -gate-keeper — checks landings +gate-keeper — checks each merge How a change lands — one at a time, so many plugins can be built at once