doxa-life/doxa-maps
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

README, agent section: bring your own harness, and the branch strategy as steps to copy

Browse source 
Only "## Build it with an agent swarm" changes.
- Bring your own harness: dx-maps works with whatever agent or harness you already use. The
  repo gives the branch strategy, the checks (bun run gates:pre) and the Plugin Studio; it
  ships no harness. A coordinator or a gate-keeper is a job your harness gives its agents.
- "Set up the branch strategy", seven steps: main is production; create development once;
  a branch and worktree per agent (with bun install); a preview port per agent; land one at
  a time through a lock (rebase, gates:pre, push only if nothing fails, since gates:pre
  exits non-zero on a failure); one full-build owner and BUNDLE=<name> for the rest; release
  by fast-forwarding main to a checked commit, then tag it and deploy from the tag.
- The plain-words kitchen list and the glossary stay, in line with the steps (the glossary
  gains "tag"). Every command block parses, and every script it names exists.
This commit is contained in:
Doxa Maps 2026-09-30 22:51:30 +00:00
parent 6e766104ac
commit 1ea9cfc280
1 changed files with 61 additions and 36 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

97
README.md
View file

@ -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=<name> 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 <development-commit> # 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).
<details>
<summary><b>What problem does this solve? (in plain words)</b></summary>
@ -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 |
</details>
<details>
<summary><b>The commands (for the curious)</b></summary>
```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=<name> 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 |
</details>