minions-template/docs/project/mailbox-collaboration-model.md

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

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

                          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.