docs: add mailbox-first collaboration model
This commit is contained in:
deamonkai
239
docs/project/mailbox-collaboration-model.md
Normal file
239
docs/project/mailbox-collaboration-model.md
Normal file
@@ -0,0 +1,239 @@
|
||||
# Mailbox Collaboration Model
|
||||
|
||||
Last updated: 2026-04-14
|
||||
Owner: PM
|
||||
|
||||
## Decision
|
||||
|
||||
This template uses a mailbox-style, packet-first coordination model for minion
|
||||
communication.
|
||||
|
||||
Accepted model:
|
||||
|
||||
- actionable role-to-role communication belongs in `minions/mail/`
|
||||
- mailbox packets are the primary request/response/verdict surface
|
||||
- `minions/chat/` becomes a PM-owned summary and continuity surface, not the
|
||||
primary multi-writer conversation surface
|
||||
- shared state docs remain single-owner surfaces, usually `PM`
|
||||
|
||||
## Problem This Solves
|
||||
|
||||
The issue is not plain text itself. The issue is shared mutable text files used
|
||||
for too many roles at once.
|
||||
|
||||
The old pattern mixed:
|
||||
|
||||
- communication
|
||||
- current state
|
||||
- audit history
|
||||
|
||||
inside the same small set of files. That created avoidable collisions:
|
||||
|
||||
- multiple minions editing the same daily thread
|
||||
- packet state and project state blending together
|
||||
- "current truth" and "historical discussion" fighting in the same document
|
||||
|
||||
The mailbox model separates those concerns.
|
||||
|
||||
## Core Rule
|
||||
|
||||
Minions should post new packet files, not co-edit the same live thread.
|
||||
|
||||
That means:
|
||||
|
||||
- one packet thread gets one packet directory
|
||||
- one message gets one owned file
|
||||
- sender writes the request
|
||||
- recipient writes the response
|
||||
- gate owner writes the verdict when needed
|
||||
- follow-up questions or corrections become new packet files or new packets, not
|
||||
rewrites of another minion's message
|
||||
|
||||
## Directory Layout
|
||||
|
||||
```text
|
||||
minions/
|
||||
mail/
|
||||
YYYY-MM-DD-sender-to-recipient-topic/
|
||||
request.md
|
||||
response.md
|
||||
verdict.md # optional
|
||||
```
|
||||
|
||||
Recommended packet id format:
|
||||
|
||||
`YYYY-MM-DD-<sender>-to-<recipient>-<topic>`
|
||||
|
||||
Examples:
|
||||
|
||||
- `2026-04-14-pm-to-sm-packet-clarification`
|
||||
- `2026-04-14-cm-to-pm-implementation-pressure`
|
||||
- `2026-04-14-pm-to-am-architecture-reset`
|
||||
|
||||
## File Ownership
|
||||
|
||||
Default ownership inside a packet:
|
||||
|
||||
- `request.md`: sender only
|
||||
- `response.md`: addressed recipient only
|
||||
- `verdict.md`: gate owner only, usually `PM`
|
||||
|
||||
Hard rules:
|
||||
|
||||
- do not edit another role's packet file
|
||||
- do not silently rewrite packet history after handoff
|
||||
- do not use a shared mailbox file for multiple independent topics
|
||||
|
||||
If substance changes after a handoff commit:
|
||||
|
||||
- open a new follow-up packet, or
|
||||
- add a new owned file in the same packet only if the workflow explicitly calls
|
||||
for it and ownership is clear
|
||||
|
||||
## Packet Lifecycle
|
||||
|
||||
1. sender opens a packet directory and writes `request.md`
|
||||
2. recipient writes `response.md`
|
||||
3. gate owner writes `verdict.md` when a decision is needed
|
||||
4. `PM` mirrors durable state changes into `README.md`, `MEMORY.md`,
|
||||
`ROADMAP.md`, `TODO.md`, plans, or requirement docs as needed
|
||||
5. `PM` posts a same-day summary into `minions/chat/YYYY-MM-DD.md`
|
||||
|
||||
This keeps:
|
||||
|
||||
- packet history in mail
|
||||
- project truth in shared state docs
|
||||
- human continuity in chat summaries
|
||||
|
||||
## Role Of Other Surfaces
|
||||
|
||||
### `minions/mail/`
|
||||
|
||||
Primary coordination surface for:
|
||||
|
||||
- requests
|
||||
- findings
|
||||
- review responses
|
||||
- verdicts
|
||||
- handoff packets
|
||||
|
||||
### `minions/chat/`
|
||||
|
||||
PM-owned summary surface for:
|
||||
|
||||
- daily continuity
|
||||
- bootstrap announcements mirrored by PM
|
||||
- high-level packet summaries
|
||||
- operator-facing recap
|
||||
- historical topic recap when a lightweight summary is useful
|
||||
|
||||
`minions/chat/` is no longer the default place for multi-role live packet
|
||||
editing.
|
||||
|
||||
### Shared State Docs
|
||||
|
||||
These remain single-owner surfaces and should not absorb raw packet history:
|
||||
|
||||
- `README.md`
|
||||
- `MEMORY.md`
|
||||
- `ROADMAP.md`
|
||||
- `TODO.md`
|
||||
- milestone plans under `minions/plans/`
|
||||
|
||||
## Packet Content Standard
|
||||
|
||||
The existing packet style still works. Mailbox changes location and ownership,
|
||||
not the need for clear handoffs.
|
||||
|
||||
Minimum request structure:
|
||||
|
||||
- `TARGET ROLE:`
|
||||
- `DECISION:`
|
||||
- `RATIONALE:`
|
||||
- `ACTION NEEDED:`
|
||||
|
||||
Minimum response structure:
|
||||
|
||||
- `DECISION:`
|
||||
- `RATIONALE:`
|
||||
- `ACTION NEEDED:`
|
||||
|
||||
Preferred full handoff structure for substantive responses:
|
||||
|
||||
- `DECISION:`
|
||||
- `RATIONALE:`
|
||||
- `SCOPE COMPLETED:`
|
||||
- `OUT OF SCOPE:`
|
||||
- `EVIDENCE:`
|
||||
- `BLOCKERS/RISKS:`
|
||||
- `ACTION NEEDED:`
|
||||
- `NEXT OWNER:`
|
||||
- `READY CHECK:`
|
||||
|
||||
## Migration Rule
|
||||
|
||||
Existing chat threads remain historical record and should not be rewritten to
|
||||
fit the mailbox model.
|
||||
|
||||
Migration posture:
|
||||
|
||||
- keep current `minions/chat/` files as history
|
||||
- use `minions/mail/` for new actionable packet flows
|
||||
- let `PM` summarize mailbox activity into daily chat and project-control docs
|
||||
|
||||
## Staged Rollout Rule
|
||||
|
||||
Mailbox adoption is staged, not all-at-once.
|
||||
|
||||
During rollout:
|
||||
|
||||
- an already-open packet may remain on its legacy `minions/chat/` surface until
|
||||
that exact packet closes
|
||||
- `PM` should add a transition note in the legacy packet when follow-up work
|
||||
must move to mail
|
||||
- any new follow-up packet spawned from a legacy chat packet should open in
|
||||
`minions/mail/`
|
||||
- do not duplicate the same active packet in both chat and mail
|
||||
- do not migrate old packet history by rewriting it into mail
|
||||
|
||||
Practical rule:
|
||||
|
||||
- finish the current packet where it already lives
|
||||
- open the next packet in `minions/mail/`
|
||||
|
||||
## Mailbox Bootstrap
|
||||
|
||||
Before opening a new mailbox packet, the acting minion should read:
|
||||
|
||||
1. `MEMORY.md`
|
||||
2. `docs/project/mailbox-collaboration-model.md`
|
||||
3. `minions/mail/README.md`
|
||||
4. `minions/mail/packet-template.md`
|
||||
|
||||
## Benefits
|
||||
|
||||
This model is intended to reduce:
|
||||
|
||||
- merge conflicts from shared daily-thread editing
|
||||
- packet ambiguity from multi-topic thread reuse
|
||||
- accidental overwrites between minions
|
||||
- confusion between project truth and communication history
|
||||
|
||||
It also makes ownership clearer:
|
||||
|
||||
- communication is append-oriented
|
||||
- summaries are curated
|
||||
- state is owned
|
||||
|
||||
## When To Revisit
|
||||
|
||||
Revisit this model if:
|
||||
|
||||
- mailbox packet count becomes too large to navigate
|
||||
- packet discovery becomes harder than the old thread model
|
||||
- the repo needs a generated index over packets
|
||||
- operators need a richer inbox or dashboard view than git paths alone provide
|
||||
|
||||
If that happens, the next likely step is not a return to shared chat files. It
|
||||
is a mailbox index, event log, or generated view layered on top of the packet
|
||||
model.
|
||||
Reference in New Issue
Block a user