docs: add mailbox-first collaboration model

This commit is contained in:
deamonkai
2026-04-14 08:20:24 -05:00
parent 7dd35f3975
commit 77ee3d3562
18 changed files with 623 additions and 152 deletions

View File

@@ -6,15 +6,39 @@ This is the high-level operating pattern behind the minion workflow.
Keep the repo as the durable source of coordination truth.
- chat is for decisions and back-and-forth
- mail is for actionable request/response/verdict packets
- chat is for PM summaries, continuity, and operator-facing recap
- plans are for formal scope and gates
- role files define responsibilities
- runtime truth is validated separately from commit history
- handoffs must be commit-backed; push is required whenever the next owner is on a different computer
## Mailbox-First Coordination
Use a mailbox-style packet model for primary minion communication.
- `minions/mail/` is the primary coordination surface
- one packet thread gets one packet directory
- one owned message gets one owned file
- sender writes `request.md`
- recipient writes `response.md`
- gate owner writes `verdict.md` when needed
- `PM` mirrors outcomes into shared state docs and same-day chat summary
`minions/chat/` is still durable, but it is no longer the default multi-writer
request/response surface.
See `docs/project/mailbox-collaboration-model.md` for the full operating model.
Rollout posture:
- existing in-flight legacy chat packets may finish where they started
- all new follow-up packets should open in `minions/mail/`
- `PM` should leave transition notes in legacy packets during staged rollout
## Recommended Lifecycle
1. `PM` opens a plan or review packet
1. `PM` opens a mailbox packet or plan packet
2. `AM` reviews architecture/design when work changes system boundaries, data flow, major dependencies, or overall design direction
3. `SM` reviews architecture foundations and risk posture when the work changes trust boundaries or security exposure
4. `CM` responds with findings or implementation inside the approved architecture
@@ -61,5 +85,5 @@ Use `PM` as the default owner for downstream template upgrades.
- deployed but not actually running
- architecture drifting without an explicit owner
- PM approving commit history instead of runtime truth
- chat discussion getting lost between sessions
- packet discussion being lost or overwritten between sessions
- role boundaries blurring under pressure