How sub-agents run this project: ownership, collisions, gates · agents/ORCHESTRATION.md
ORCHESTRATION.md — the orchestrator's doctrine (v2, 2026-09-12: TWO TRACKS)
0. The split (founder directive 2026-09-12)
- Track W — WEBSITE (
website/+ content/ + wiki build + deploy): crew = website agents (site-builder, theme-master, site-reviewer). Codex is BENCHED for this track (see INVESTIGATIONS); GLM 5.3 + the style auditor do UI QA. - Track S — SYSTEM (chain + services + fleet + security): crew = system agents (service-builder, security-fixer, ops, fleet). Paths at repo root are LOAD-BEARING (systemd/testkit/ceremony) — organize via system/MANIFEST.md, never move.
- Cross-track changes (e.g. a service API feeding a dashboard) get TWO agents in sequence, never one touching both.
Who this is for: the GLM 5.3 orchestrator session (me) + any future session running this project. Distills ~25 sub-agent campaigns (incl. 2 file-collision incidents and 3 crash-recoveries) into standing rules.
1. The section-ownership map (ONE agent per section at a time)
| Section | Owner role | Files (exclusive) | Current state |
|---|---|---|---|
| Chain & Move | builder-move | qalnet/qal/, scripts/onchain, gen_devnet | qal_data+qal_credit live; qal_reserve in-flight (compile errors) |
| Money rails | builder-money | loopd/ | stable (escrow semantics v2) — ORCH-ONLY edits now (it's load-bearing for everything) |
| Comms | builder-comms | qalchat/, seedkit/, qalid/ | stable |
| Social/public | builder-social | qalpub/ (+ coordination rule, see §3) | roles agent in-flight |
| Markets | builder-markets | qmarket/, qalbazaar/, qalkeys/ | stable (qk.py has an unbound-import lint) |
| Payments/claims | builder-pay | qalpay/, qalclaim/, qalredeem/ | stable |
| Wallet | builder-wallet | wallet-app/ui/ only | v6 stable |
| Bridge/phone | builder-bridge | qalbridge/ | stable |
| Public site & codex UI | codex (UI-only!) + deployer | site/, ui-codex/ | Loom/Vault/Qalx live |
| Docs/wiki | scribe | content/, scripts/build_docs.py | 56 pages |
| Fleet/ops | deployer | scripts/, deploy/, systemd units | all-green under systemd |
2. Dispatch rules
- Default type:
yolo-glm-flash(budget). Escalate toyoloonly for multi-system synthesis a Flash agent has failed at. - Codex for public-facing UI ONLY — never give it system/protocol context (user rule: UI-related tasks only).
- Every prompt carries: date, working dir, exclusive file list, READ-FIRST list, running-services contract, acceptance gates (which suites must stay green), the house rules (archive-before-replace, creation-code preservation, no deletions, reversible-only for anything touching live state).
- State-check-first: before ANY edit task on a shared file, the agent runs its suites green to establish a baseline (prevents inheriting/creating half-states — this rule came from the roles-agent crash).
- Me (orchestrator) never build in parallel with agents in their owned files. My own edits go in: docs, wiki registration, deploys, cross-cutting fixes in files nobody owns right now, or AFTER the agent lands.
3. Collision protocol (the qalpub lesson)
When two features must touch one file (e.g. pay-to-post + roles both extend qalpub.py): - Sequence, never parallel on the same file — or if parallel is unavoidable, the later agent's prompt names the former's NEW endpoints as no-touch regions AND both work additively-only. - Prefer extracting to new files when possible (qalpub roles could have been a module).
4. Verification gates (never trust, always verify)
- Agent reports suite green → I re-run the suite myself (caught: qalpub self-heal miscounts, relay flap variance).
- Anything money-touching → I run a manual exact-math probe (the redeem 2000→1990 pattern).
- Anything UI → audit.sh/link-check must pass; I curl the deployed 200s.
- Security-sensitive changes → red-team style negative test before deploy (C3 pattern: attack it, prove the refusal).
5. The wave cadence
- Update the todo board (sections in-flight / pending / done) — it IS the coordination state.
- Dispatch wave (2-4 agents max parallel, different sections).
- While agents run: my lane = docs, wiki, deploys, spot-verification, or un-owned fixes.
- Land: verify → register wiki pages → rebuild → deploy (me only) → commit baseline → Signal.
- Incidents (agent death, suite regression): state-check → respawn with state notes → log finding in the audit folder (every incident becomes a rule).
6. Budget discipline
Unlimited-token mode = run waves until told to stop, but: no redundant agent spawns for things I can do in <5 minutes myself; poll with sleep batches, not tight loops; stop an agent the moment its mission is moot (task_control stop).
7. Standing queues (prioritized)
P1: qal_reserve compile+publish (Move) · roles/moderation landing · wallet passkeys P2: qk.py lint fix · chain RPC localhost-bind at next regenesis · third relay · relay pubkey proof-of-registration P3: native Rust chat crypto · marketplace offer signing · gmux integration build · bb-mini deploy when online