diff --git a/README.md b/README.md index 053cb4f8a..f18bf1db4 100644 --- a/README.md +++ b/README.md @@ -689,13 +689,61 @@ your own page, set `"locale"` in its `profile-config`. Arabic reads right to lef ## Build it with an agent swarm **Many AI agents can build many plugins at once without breaking each other's work.** Every plugin -has one agent that owns it, a second agent reads every change before it lands, a coordinator puts the -landings in order, and a gate-keeper checks each one. All the plugins live in one project with one shared -library, and changes are added to `development`, the shared working version, one at a time. `main` is the -production version: it moves only by a promotion the owner approves, after a full check run on that exact version. +has one agent that owns it, and changes are added to `development`, the shared working version, one +at a time. `main` is the production version: it moves only when you publish a release. + +**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 +gate-keeper that reads each change before it lands, are jobs your harness gives to its agents. ![The delegation model: development at the centre behind a landing lock, 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) +### Set up the branch strategy + +1. **`main` is production.** It moves only when you publish a release (step 7). +2. **`development` is the shared working branch.** Create it once, from `main`: + ```bash + git fetch origin && git switch -c development origin/main && git push -u origin development + ``` +3. **One branch and worktree per plugin agent**, from `origin/development`, then install once in each: + ```bash + git worktree add -b regions/work ../dx-maps-regions origin/development + git worktree add -b upg100/work ../dx-maps-upg100 origin/development + cd ../dx-maps-regions && bun install --frozen-lockfile + ``` +4. **One preview server per agent, each on its own port:** + ```bash + bun x vite --port 5301 --strictPort # the next agent uses 5302, and so on + ``` +5. **Land one at a time, through a lock.** Catch up with `development`, run the checks, and push only + if nothing fails (`gates:pre` exits non-zero when a check fails, so the push never runs then): + ```bash + flock /tmp/dx-maps-development.lock sh -c ' + git fetch origin && git rebase origin/development && + bun run gates:pre && git push origin HEAD:development' + ``` + `flock` guards one machine. Agents on several machines need a shared lock, such as one your + harness provides. +6. **One agent owns the full build**; the others build only their own plugin: + ```bash + BUILD_ALLOW=1 bun run build # the build owner: every plugin + BUNDLE= bun x vite build && bun run tree && bun run fix:sri # everyone else: one plugin + ``` +7. **Release:** fast-forward `main` to a `development` commit that passed the checks, tag it, and + deploy from the tag: + ```bash + git fetch origin && git switch main && git merge --ff-only origin/main + git merge --ff-only # a commit that passed the checks + bun run gates:pre # the checks must pass on exactly this commit + git tag -a v1.0.0 -m "Release v1.0.0" && git push origin main v1.0.0 + ``` + The tag's `public/dx-maps/` folder is the built site: deploy that + ([how to deploy](./documentation/DEPLOY.md)). + +How to contribute, and the bar for shared code: [documentation/CONTRIBUTING.md](./documentation/CONTRIBUTING.md). +Diagram source: [`delegation-model.svg`](./documentation/readme-images/src/delegation-model.svg). +
What problem does this solve? (in plain words) @@ -709,13 +757,13 @@ 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. **A second agent reads every change** by its content before it may land. -3. **Only one change lands at a time.** Whoever holds the *landing lock* merges in everyone else's - latest work and fixes any clash itself, rebuilds the maps from the merged source and runs every - check; the change goes into `development` only if nothing fails. `development` always works. -4. **A coordinator puts the landings in order, and a gate-keeper checks each one** by its content. -5. **`main` moves only by a promotion** the owner approves, after a full check run on that exact - version. The dev preview follows `development`; the published site follows `main`. +2. **Only one change lands at a time.** Whoever holds the *landing lock* first catches up with + everyone else's latest work, fixes any clash itself and runs every check; the change goes into + `development` only if nothing fails. `development` always works. +3. **Someone keeps order.** A coordinator can put the landings 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. **`main` moves only when you publish a release**, after the checks pass on that exact version. + A preview can follow `development`; the published site follows `main`. That's how many plugins get built at the same time, in one project, without the maps breaking. @@ -732,31 +780,8 @@ That's how many plugins get built at the same time, in one project, without the | **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 merges, rebuilds and runs every check first | - -
- -
-The commands (for the curious) - -```bash -# one private copy (worktree) + one agent per plugin -git worktree add -b regions/work ../dx-maps-regions origin/development -git worktree add -b upg100/work ../dx-maps-upg100 origin/development - -# one preview server per agent, each on its own port -bun x vite --port 5301 --strictPort - -# add work through the line: one at a time, caught up first, checks must pass -flock /tmp/dx-maps-development.lock sh -c ' - git fetch origin && git rebase origin/development && - bun run gates:pre && git push origin HEAD:development' -``` - -One agent owns the full build (it rebuilds everyone's output); the others check just their own -plugin with `BUNDLE= bun x vite build`. How to contribute, and the bar for shared code: -[documentation/CONTRIBUTING.md](./documentation/CONTRIBUTING.md). Diagram source: -[`delegation-model.svg`](./documentation/readme-images/src/delegation-model.svg). +| **landing lock** | only one change lands on `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 |