Molloy-Home/minions-template
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: add mailbox-first collaboration model

Browse Source
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
Download Patch File Download Diff File Expand all files Collapse all files

30
docs/collaboration-playbook.md
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

15
docs/downstream-onboarding-playbook.md
View File

@@ -66,15 +66,23 @@ clone.
6. Treat downstream-owned files as project surfaces, not template clones:
- project `README.md`
- live plans
- live chat history
- live mail packet history
- live chat summary history
- downstream `CHANGELOG.md`
- `ROADMAP.md`
- `TODO.md`
7. Run the onboarding checklist with the Operator and fill in project-specific
decisions.
8. Commit the vendored snapshot and exported live files together so the repo has
8. Bootstrap mailbox use in the live downstream repo:
- read `MEMORY.md`
- read `docs/project/mailbox-collaboration-model.md`
- read `minions/mail/README.md`
- read `minions/mail/packet-template.md`
- use `minions/mail/` for new actionable packets
- use `minions/chat/` for PM daily summaries
9. Commit the vendored snapshot and exported live files together so the repo has
a clear starting baseline.
9. After onboarding is approved, future template changes should use
10. After onboarding is approved, future template changes should use
`docs/downstream-upgrade-playbook.md`.
## Manual-Merge Guidance
@@ -109,5 +117,6 @@ clone.
- files exported directly from template
- files manually merged for downstream use
- files intentionally left downstream-owned
- confirmation that mailbox bootstrap docs were reviewed and `minions/mail/` is the active packet surface for new work
- open Operator decisions
- first commit scope and next owner

4
docs/downstream-upgrade-playbook.md
View File

@@ -64,8 +64,8 @@ Git clones.
`docs/operator-onboarding-checklist.md`, and `minion-version.md`.
8. Preserve `downstream-owned` files unless the Operator explicitly directs a
project-specific rewrite.
9. Record the upgrade packet in the active chat thread and downstream
`CHANGELOG.md`.
9. Record the upgrade packet in `minions/mail/`, mirror the same-day summary
into `minions/chat/`, and update the downstream `CHANGELOG.md`.
10. After approval, replace `.minions-template/` with the new approved snapshot
and remove `.minions-template.next/`.
11. Update the base-template portion of `minion-version.md` only after the live

14
docs/export-manifest.md
View File

@@ -39,6 +39,7 @@ template repo.
| `MEMORY.md` | yes | `manual-merge` | PM | merge new template guardrails while preserving project-specific truth |
| `minion-version.md` | yes | `manual-merge` | PM | update base-template version after upgrade; preserve downstream version suffix |
| `docs/collaboration-playbook.md` | yes | `template-replace` | PM | baseline workflow doc |
| `docs/project/mailbox-collaboration-model.md` | yes | `template-replace` | PM | baseline mailbox-first coordination model |
| `docs/operator-onboarding-checklist.md` | yes | `manual-merge` | PM | preserve completed downstream decisions |
| `docs/downstream-onboarding-playbook.md` | yes | `template-replace` | PM | baseline initial onboarding procedure |
| `docs/downstream-upgrade-playbook.md` | yes | `template-replace` | PM | baseline downstream-upgrade procedure |
@@ -51,10 +52,13 @@ template repo.
| `minions/roles/OM.md` | yes | `template-replace` | PM / OM | review local role customizations before overwrite |
| `minions/plans/README.md` | yes | `template-replace` | PM | baseline planning guidance |
| `minions/plans/milestone-plan-template.md` | yes | `template-replace` | PM | baseline planning template |
| `minions/chat/README.md` | yes | `template-replace` | PM | baseline chat workflow guidance |
| `minions/chat/general-thread-template.md` | yes | `template-replace` | PM | baseline general thread template |
| `minions/chat/topic-thread-template.md` | yes | `template-replace` | PM | baseline topic thread template |
| `minions/chat/*.md` daily/topic history | yes | `downstream-owned` | PM / Operator | preserve downstream discussion history |
| `minions/plans/*.md` live plan docs | yes | `downstream-owned` | PM | preserve project-specific plans and status |
| `minions/mail/README.md` | yes | `template-replace` | PM | baseline mailbox workflow guidance |
| `minions/mail/packet-template.md` | yes | `template-replace` | PM | baseline packet structure |
| `minions/chat/README.md` | yes | `template-replace` | PM | baseline PM-summary workflow guidance |
| `minions/chat/general-thread-template.md` | yes | `template-replace` | PM | baseline daily summary template |
| `minions/chat/topic-thread-template.md` | yes | `template-replace` | PM | baseline topic summary template |
| `minions/mail/*/` live packet history | no | `downstream-owned` | PM / Operator | preserve downstream packet history; do not export template packet history |
| `minions/chat/*.md` daily/topic history | no | `downstream-owned` | PM / Operator | preserve downstream summary history; do not export template history |
| `minions/plans/*.md` live plan docs | no | `downstream-owned` | PM | preserve project-specific plans and status |
| `ROADMAP.md` | downstream required | `downstream-owned` | PM | currently required by the workflow but not shipped as a template file |
| `TODO.md` | downstream required | `downstream-owned` | PM | currently required by the workflow but not shipped as a template file |

1
docs/operator-onboarding-checklist.md
View File

@@ -33,6 +33,7 @@ Date: YYYY-MM-DD
- `CHANGELOG.md` initialized and owner set
- `ROADMAP.md` initialized and owner set
- `TODO.md` initialized and owner set
- mailbox coordination workflow reviewed (`docs/project/mailbox-collaboration-model.md`, `minions/mail/README.md`)
- vendored template snapshot initialized (recommended `.minions-template/`; exclude `.git/` and `do-not-export` files)
- initial downstream export completed using `docs/downstream-onboarding-playbook.md`
- downstream template-upgrade owner confirmed (default `PM`)

239
docs/project/mailbox-collaboration-model.md Normal file
View 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.