279 lines
7.9 KiB
Markdown
279 lines
7.9 KiB
Markdown
# 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
|
|
|
|
## ASCII Flow
|
|
|
|
```text
|
|
MAILBOX-FIRST COLLABORATION
|
|
|
|
new actionable work / request / finding / handoff
|
|
|
|
|
v
|
|
+----------------------------------------------------------------------------------+
|
|
| minions/mail/YYYY-MM-DD-sender-to-recipient-topic/ |
|
|
| |
|
|
| request.md -> written by sender only |
|
|
| response.md -> written by addressed recipient only |
|
|
| verdict.md -> written by gate owner only (usually PM, only if needed) |
|
|
+----------------------------------------------------------------------------------+
|
|
|
|
|
v
|
|
packet decision / response exists
|
|
|
|
|
v
|
|
+---------------------------------------------+
|
|
| PM mirrors durable outcomes into project |
|
|
| truth docs as needed: |
|
|
| - README.md |
|
|
| - MEMORY.md |
|
|
| - ROADMAP.md |
|
|
| - TODO.md |
|
|
| - plans / other controlled docs |
|
|
+---------------------------------------------+
|
|
|
|
|
v
|
|
+---------------------------------------------+
|
|
| PM posts same-day summary into |
|
|
| minions/chat/YYYY-MM-DD.md |
|
|
| chat is summary/history only |
|
|
| not the live multi-writer work surface |
|
|
+---------------------------------------------+
|
|
```
|
|
|
|
## 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.
|