monster/festifun
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Add coordination loop: run order (DIRECTIVES.md), per-agent status protocol

Browse Source 
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
This commit is contained in:
m3ultra 2026-07-16 00:08:54 +10:00
parent e31e8ac559
commit 47bec93bc5
3 changed files with 58 additions and 3 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

25
plan/DIRECTIVES.md Normal file
View File

@ -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/<your-lane>.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.)*

14
plan/README.md
View File

@ -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/<lane>.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/<lane>.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."*

22
plan/status/TEMPLATE.md Normal file
View File

@ -0,0 +1,22 @@
# Status — <foundation | lane-A | lane-B | lane-C | lane-D | integration>
<!-- Copy this file to plan/status/<your-lane>.md on your first session. You own that file.
UPDATE IT (and commit+push to YOUR branch) at these moments, no exceptions:
1. Session start — claim the lane, state your plan for the round
2. Each milestone pass — check the boxes, note evidence (test names, commands run)
3. Any blocker — immediately, don't sit on it
4. Before merging — final summary
Prepend new rounds at the top; never delete old rounds. Keep each round under ~30 lines. -->
## Round N — <date> — 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.