From 47bec93bc525f93b95c6aedd982db0c89c64d1e3 Mon Sep 17 00:00:00 2001 From: m3ultra Date: Thu, 16 Jul 2026 00:08:54 +1000 Subject: [PATCH] Add coordination loop: run order (DIRECTIVES.md), per-agent status protocol Co-Authored-By: Claude Fable 5 --- plan/DIRECTIVES.md | 25 +++++++++++++++++++++++++ plan/README.md | 14 +++++++++++--- plan/status/TEMPLATE.md | 22 ++++++++++++++++++++++ 3 files changed, 58 insertions(+), 3 deletions(-) create mode 100644 plan/DIRECTIVES.md create mode 100644 plan/status/TEMPLATE.md diff --git a/plan/DIRECTIVES.md b/plan/DIRECTIVES.md new file mode 100644 index 0000000..91c592a --- /dev/null +++ b/plan/DIRECTIVES.md @@ -0,0 +1,25 @@ +# Coordinator Directives + +Written **only** by the coordinator (the human's planning session). Agents: read the latest round at session start and after every milestone via `git fetch origin && git show origin/main:plan/DIRECTIVES.md`. The newest round addressed to your lane overrides older rounds and, where in conflict, your lane brief. Never edit this file. + +--- + +## Round 0 — 2026-07-16 — Run order & protocol + +**Execution order:** + +1. **Now: `foundation` only.** Nothing else starts until foundation merges to `main`. Foundation agent: contracts correctness beats speed — lanes will hard-depend on your API shapes, schema, pose math, and synthetic fixtures. +2. **After foundation merges — start lanes in this priority order** (all four concurrently if capacity allows; if running fewer sessions, start in this order): + 1. **Lane C (viewer)** — longest lane and the earliest validation of the API contract; starts first. + 2. **Lane A (media)** — the core real-footage capability; small surface, should finish early. + 3. **Lane D (events)** — small and fully independent. + 4. **Lane B (recon)** — heaviest external dependency (COLMAP) and the most graceful-degradation slack; safe to start last. +3. **Merge policy:** merge to `main` as soon as your lane's acceptance passes — do not wait for other lanes. Expected finish order: A, D, then C, then B. +4. **After all four merge: `integration`.** + +**Standing protocol (all agents):** +- Maintain `plan/status/.md` per `plan/status/TEMPLATE.md` — session start, every milestone, every blocker, before merge. Push status commits to your branch immediately; the coordinator reviews between rounds by reading these files. +- If blocked > 30 minutes on an ambiguity, write the blocker to your status file, push, and move to another task in your lane rather than guessing on a frozen contract. +- Evidence discipline: a checked acceptance box must name the test or the exact command + output that proves it. + +*(Future rounds will be appended above this line as the coordinator reviews status files.)* diff --git a/plan/README.md b/plan/README.md index dd629c9..3eba394 100644 --- a/plan/README.md +++ b/plan/README.md @@ -33,6 +33,8 @@ Foundation scaffolds *every* file listed in the spec's repo layout, with lane-ow | Lane B | `backend/festival4d/frames.py`, `sfm.py`, `geometry.py`, `backend/tests/test_sfm.py`, `test_geometry.py` | | Lane C | everything under `frontend/` | | Lane D | `backend/festival4d/events_ai.py`, `backend/tests/test_events_ai.py` | +| Every agent | its own `plan/status/.md` (and only its own) | +| **Coordinator only** | `plan/DIRECTIVES.md` — agents read, never write | | **Frozen after foundation** | `db.py` (schema), `api.py` (routes + response shapes), `cli.py`, `config.py`, `synthetic.py`, `pyproject.toml` | If a lane believes a frozen file must change, it does **not** edit it — it writes the needed change into `plan/CHANGE_REQUESTS.md` (create if absent) with rationale, and works around it locally. The integration agent adjudicates. Adding a *new* file inside your ownership area is always fine; adding a dependency requires a change request. @@ -53,8 +55,14 @@ If a lane believes a frozen file must change, it does **not** edit it — it wri - No edits outside owned files; no new deps without a change request. - Merged to `main` with the synthetic end-to-end still working (`python -m festival4d synthetic && ... serve` + frontend loads). +## Coordination loop (status + directives) + +- **Run order lives in `plan/DIRECTIVES.md`** (coordinator-written, round-numbered). Every agent reads the latest round at session start and after each milestone: `git fetch origin && git show origin/main:plan/DIRECTIVES.md`. Newest round wins over older rounds and lane briefs. +- **Every agent maintains `plan/status/.md`** per `plan/status/TEMPLATE.md` — updated and pushed at session start, each milestone pass (with evidence), each blocker (immediately), and before merge. +- **Review cadence:** between rounds the coordinator fetches all branches, reads every status file, appends a new round to DIRECTIVES.md on `main`, and pushes. Agents obey the new round on their next read. + ## Suggested per-agent kickoff prompts -- Foundation: *"Read OPUS_BUILD_INSTRUCTIONS.md and plan/00-foundation.md. Execute on branch `foundation`, merge to main when acceptance passes."* -- Lane X: *"Read OPUS_BUILD_INSTRUCTIONS.md, plan/README.md, and plan/lane-X-*.md. Work only on branch `lane/x-...`, only in your owned files. Merge to main when acceptance passes."* -- Integration: *"Read OPUS_BUILD_INSTRUCTIONS.md and plan/10-integration.md. All lanes are merged; execute on branch `integration`."* +- Foundation: *"Clone ssh://git@100.71.119.27:222/monster/festifun.git. Read OPUS_BUILD_INSTRUCTIONS.md, plan/00-foundation.md, and the latest round of plan/DIRECTIVES.md. Execute on branch `foundation`; maintain plan/status/foundation.md per plan/status/TEMPLATE.md; merge to main when acceptance passes."* +- Lane X: *"Clone ssh://git@100.71.119.27:222/monster/festifun.git. Read OPUS_BUILD_INSTRUCTIONS.md, plan/README.md, plan/lane-X-*.md, and the latest round of plan/DIRECTIVES.md. Work only on branch `lane/x-...`, only in your owned files; maintain plan/status/lane-X.md per the template; re-read DIRECTIVES.md after each milestone; merge to main when acceptance passes."* +- Integration: *"Clone the repo. Read OPUS_BUILD_INSTRUCTIONS.md, plan/10-integration.md, all of plan/status/, and the latest DIRECTIVES round. All lanes are merged; execute on branch `integration`; maintain plan/status/integration.md."* diff --git a/plan/status/TEMPLATE.md b/plan/status/TEMPLATE.md new file mode 100644 index 0000000..7bec14c --- /dev/null +++ b/plan/status/TEMPLATE.md @@ -0,0 +1,22 @@ +# Status — + + + +## Round N — — STATUS: in_progress | blocked | ready_to_merge | merged + +**Directives acknowledged:** round N of plan/DIRECTIVES.md (state the round number you read) + +**Acceptance checklist** (copy items from your lane brief / spec milestones): +- [ ] ... + +**Done this round:** what actually works now, with evidence (passing test names, exact commands + observed output). Claims without evidence don't count. + +**Blockers / questions for coordinator:** anything preventing progress; anything ambiguous in the spec; any change request filed in plan/CHANGE_REQUESTS.md (link the entry). + +**Next:** the immediate next steps.