# 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--to--` 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.