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

28
CHANGELOG.md
View File

@@ -2,6 +2,34 @@
All notable changes to this repository are tracked here. All notable changes to this repository are tracked here.
## 2026-04-14
- Commit hash: pending (next commit)
- Added a mailbox-first coordination model so actionable minion communication
moves into packet directories while `minions/chat/` becomes a PM-owned
summary surface in:
- `README.md`
- `INIT.md`
- `MEMORY.md`
- `docs/collaboration-playbook.md`
- `docs/downstream-onboarding-playbook.md`
- `docs/downstream-upgrade-playbook.md`
- `docs/export-manifest.md`
- `docs/operator-onboarding-checklist.md`
- `minions/README.md`
- `minions/chat/README.md`
- `minions/chat/general-thread-template.md`
- `minions/chat/topic-thread-template.md`
- `minions/plans/milestone-plan-template.md`
- Added template-managed mailbox assets in:
- `docs/project/mailbox-collaboration-model.md`
- `minions/mail/README.md`
- `minions/mail/packet-template.md`
- Clarified staged rollout and downstream export behavior so legacy chat packets
may finish in place, new follow-up packets move to mail, and template packet
history is not exported into downstream repos
- Bumped template version to `1.4.0-1.0.0` in `minion-version.md`
## 2026-04-12 ## 2026-04-12
- Commit hash: pending (next commit) - Commit hash: pending (next commit)

18
INIT.md
View File

@@ -9,7 +9,8 @@ SM, and OM discipline, durable evidence, and milestone execution.
- collaboration baseline imported - collaboration baseline imported
- operator onboarding checklist not yet started - operator onboarding checklist not yet started
- daily minion thread not yet created - mailbox coordination not yet initialized
- PM daily summary thread not yet created
- milestone 0 planning not yet started - milestone 0 planning not yet started
## Immediate Startup Sequence ## Immediate Startup Sequence
@@ -22,7 +23,13 @@ SM, and OM discipline, durable evidence, and milestone execution.
- environments - environments
- safety constraints - safety constraints
4. Open first milestone plan in [minions/plans](minions/plans). 4. Open first milestone plan in [minions/plans](minions/plans).
5. Track decisions and handoffs in the active daily thread under [minions/chat/](minions/chat/). 5. Bootstrap mailbox coordination:
- read [MEMORY.md](MEMORY.md)
- read [docs/project/mailbox-collaboration-model.md](docs/project/mailbox-collaboration-model.md)
- read [minions/mail/README.md](minions/mail/README.md)
- read [minions/mail/packet-template.md](minions/mail/packet-template.md)
- use [minions/mail/](minions/mail/) for new actionable packets
- use [minions/chat/](minions/chat/) for PM daily summaries
6. Keep [ROADMAP.md](ROADMAP.md), [TODO.md](TODO.md), and [CHANGELOG.md](CHANGELOG.md) updated during execution. 6. Keep [ROADMAP.md](ROADMAP.md), [TODO.md](TODO.md), and [CHANGELOG.md](CHANGELOG.md) updated during execution.
7. Use [docs/downstream-upgrade-playbook.md](docs/downstream-upgrade-playbook.md) for later template updates. 7. Use [docs/downstream-upgrade-playbook.md](docs/downstream-upgrade-playbook.md) for later template updates.
@@ -89,7 +96,9 @@ Optional sections when needed: RISK, BLOCKER, DEADLINE.
## Completion Handoff Contract (ADHD-Friendly) ## Completion Handoff Contract (ADHD-Friendly)
All minions must close work with a clear handoff packet in the active daily thread. All minions must close work with a clear handoff packet on the active packet
surface. Default: `minions/mail/`. During staged rollout, `PM` may allow an
already-open legacy chat packet to close where it started.
Required structure (in this exact order): Required structure (in this exact order):
@@ -119,5 +128,6 @@ This project is considered fully onboarded when all are true:
- operator onboarding checklist status is approved - operator onboarding checklist status is approved
- project-specific MEMORY sections are complete - project-specific MEMORY sections are complete
- first milestone plan is active - first milestone plan is active
- daily thread is being used for same-day durable updates - mailbox packets are being used for new actionable work
- PM daily summary thread is being used for same-day durable recap
- rollback posture expectations are explicitly documented - rollback posture expectations are explicitly documented

54
MEMORY.md
View File

@@ -46,6 +46,35 @@ This project uses multiple AI agents ("minions") that coordinate through git:
- `OM-Test` — test-environment operations, restarts, runtime verification - `OM-Test` — test-environment operations, restarts, runtime verification
- `OM` — production operations, maintenance, rollback, incident handling - `OM` — production operations, maintenance, rollback, incident handling
## Communication Model
- actionable role-to-role communication belongs in `minions/mail/`
- mailbox packets are the default request/response/verdict surface
- `minions/chat/` is a PM-owned daily summary and continuity surface
- shared state docs remain single-owner surfaces, usually `PM`
- the mailbox model is defined in `docs/project/mailbox-collaboration-model.md`
- mailbox rollout is staged:
- already-open legacy chat packets may finish where they started
- any new follow-up packet should default to `minions/mail/`
- `PM` should leave a transition note in legacy packets when follow-up work
moves to mail
## Mailbox Bootstrap
When a minion needs to open or answer a mailbox packet, bootstrap in this
order:
1. `MEMORY.md`
2. `docs/project/mailbox-collaboration-model.md`
3. `minions/mail/README.md`
4. `minions/mail/packet-template.md`
Current rollout rule:
- existing in-flight chat packets stay in place until they close
- all new follow-up packets should use `minions/mail/` unless `PM` says
otherwise
## Shared Rules ## Shared Rules
- Shared truth belongs in `MEMORY.md` - Shared truth belongs in `MEMORY.md`
@@ -55,9 +84,10 @@ This project uses multiple AI agents ("minions") that coordinate through git:
- `CHANGELOG.md` is required and should capture template-impacting and project-impacting changes - `CHANGELOG.md` is required and should capture template-impacting and project-impacting changes
- `ROADMAP.md` is required and should reflect approved direction and upcoming milestones - `ROADMAP.md` is required and should reflect approved direction and upcoming milestones
- `TODO.md` is required and should track actionable backlog items with current status - `TODO.md` is required and should track actionable backlog items with current status
- actionable packet communication belongs in `minions/mail/`
- Role-specific deltas belong in `minions/roles/` - Role-specific deltas belong in `minions/roles/`
- Formal plans belong in `minions/plans/` - Formal plans belong in `minions/plans/`
- Informal but durable discussion belongs in `minions/chat/` - PM summaries and historical continuity belong in `minions/chat/`
- Milestone-relevant progress should be mirrored into chat the same day - Milestone-relevant progress should be mirrored into chat the same day
## CHANGELOG Maintenance Rule ## CHANGELOG Maintenance Rule
@@ -130,7 +160,7 @@ These apply to every minion role.
- Never hide risk, blocker, or incident impact in long status updates; surface it clearly and early. - Never hide risk, blocker, or incident impact in long status updates; surface it clearly and early.
- Never perform destructive actions (deletes, forced resets, irreversible migrations) without explicit Operator approval. - Never perform destructive actions (deletes, forced resets, irreversible migrations) without explicit Operator approval.
- Never store credentials in the repo, ever. Never store personal data in the repo unless explicitly approved by the Operator. - Never store credentials in the repo, ever. Never store personal data in the repo unless explicitly approved by the Operator.
- Use environment variables, approved secret managers, or local untracked files for secrets; if personal data is approved, document scope, purpose, and retention in the relevant plan/chat thread. - Use environment variables, approved secret managers, or local untracked files for secrets; if personal data is approved, document scope, purpose, and retention in the relevant plan, mail packet, or PM summary.
- Maintain `.gitignore` proactively so secrets, personal data artifacts, local env files, and machine-specific noise are not committed. - Maintain `.gitignore` proactively so secrets, personal data artifacts, local env files, and machine-specific noise are not committed.
- Always provide evidence with claims that affect gates, deploy decisions, or incident status. - Always provide evidence with claims that affect gates, deploy decisions, or incident status.
- Always update durable context (role file, plan, or chat) the same day when decisions or reality change. - Always update durable context (role file, plan, or chat) the same day when decisions or reality change.
@@ -191,15 +221,23 @@ Interpretation:
## Communication Conventions ## Communication Conventions
- general daily thread: `minions/chat/YYYY-MM-DD.md` - primary packet directory: `minions/mail/YYYY-MM-DD-sender-to-recipient-topic/`
- substantive topic thread: `minions/chat/YYYY-MM-DD-topic-name.md` - sender writes `request.md`
- when a minion is bootstrapped, it must announce itself in the current general daily thread - addressed recipient writes `response.md`
- chat-thread updates are commit-by-default so discussion remains durable in git history - gate owner writes `verdict.md` when needed
- default commit message format for chat-thread updates: `chat: YYYY-MM-DD thread update` - PM daily summary thread: `minions/chat/YYYY-MM-DD.md`
- PM topic summary thread: `minions/chat/YYYY-MM-DD-topic-name.md`
- when a minion is bootstrapped or a packet closes, `PM` should mirror a short
same-day summary into the current daily summary thread
- packet and chat updates are commit-by-default so coordination remains durable
in git history
- default commit message format for chat summary updates: `chat: YYYY-MM-DD thread update`
## Completion Handoff Contract (ADHD-Friendly) ## Completion Handoff Contract (ADHD-Friendly)
All minions must close work with a clear handoff packet in the active daily thread. All minions must close work with a clear handoff packet on the active packet
surface. Default: `minions/mail/`. During staged rollout, `PM` may allow an
already-open legacy chat packet to close where it started.
Required structure (in this exact order): Required structure (in this exact order):

54
README.md
View File

@@ -1,6 +1,7 @@
# Minion Template # Minion Template
This repository is a source template for running coordinated AI assistant roles (minions) with durable markdown-based collaboration in git. This repository is a source template for running coordinated AI assistant roles
(minions) with durable markdown-based collaboration in git.
It provides a baseline operating model for: It provides a baseline operating model for:
@@ -14,43 +15,64 @@ It provides a baseline operating model for:
This README is template-scaffolding guidance. This README is template-scaffolding guidance.
When this template is used to create a downstream project, this file should not be copied forward as-is. Downstream repositories should replace it with a project-specific README to avoid role/process confusion. When this template is used to create a downstream project, this file should not
be copied forward as-is. Downstream repositories should replace it with a
project-specific README to avoid role/process confusion.
## Repository Purpose ## Repository Purpose
This template exists to make multi-agent coordination explicit, durable, and reviewable by combining: This template exists to make multi-agent coordination explicit, durable, and
reviewable by combining:
- shared memory and guardrails - shared memory and guardrails
- role-specific context files - role-specific context files
- formal planning artifacts - formal planning artifacts
- chat-thread decision history - mailbox packet history
- PM-owned continuity summaries
- explicit handoff and evidence discipline - explicit handoff and evidence discipline
## Basic Onboarding ## Basic Onboarding
Use this sequence immediately after creating a downstream project from this template: Use this sequence immediately after creating a downstream project from this
template:
1. Establish a filtered vendored template snapshot and perform the first controlled export using [docs/downstream-onboarding-playbook.md](docs/downstream-onboarding-playbook.md). 1. Establish a filtered vendored template snapshot and perform the first
2. Complete [docs/operator-onboarding-checklist.md](docs/operator-onboarding-checklist.md) with the Operator. controlled export using
[docs/downstream-onboarding-playbook.md](docs/downstream-onboarding-playbook.md).
2. Complete [docs/operator-onboarding-checklist.md](docs/operator-onboarding-checklist.md)
with the Operator.
3. Finalize project-specific sections in [MEMORY.md](MEMORY.md). 3. Finalize project-specific sections in [MEMORY.md](MEMORY.md).
4. Open the first milestone plan from [minions/plans](minions/plans). 4. Open the first milestone plan from [minions/plans](minions/plans).
5. Create and use the current daily thread in [minions/chat](minions/chat). 5. Bootstrap mailbox coordination using
6. Initialize and maintain ROADMAP.md, TODO.md, and CHANGELOG.md. [docs/project/mailbox-collaboration-model.md](docs/project/mailbox-collaboration-model.md)
7. Use [docs/downstream-upgrade-playbook.md](docs/downstream-upgrade-playbook.md) for later template updates. and [minions/mail](minions/mail); use `minions/mail/` for new actionable
packets and `minions/chat/` for PM summaries.
6. Initialize and maintain `ROADMAP.md`, `TODO.md`, and `CHANGELOG.md`.
7. Use [docs/downstream-upgrade-playbook.md](docs/downstream-upgrade-playbook.md)
for later template updates.
## Core Files ## Core Files
- [INIT.md](INIT.md): startup framing and handoff expectations - [INIT.md](INIT.md): startup framing and handoff expectations
- [MEMORY.md](MEMORY.md): shared truth and baseline guardrails - [MEMORY.md](MEMORY.md): shared truth and baseline guardrails
- [minion-version.md](minion-version.md): template/downstream versioning format - [minion-version.md](minion-version.md): template/downstream versioning format
- [docs/collaboration-playbook.md](docs/collaboration-playbook.md): high-level operating pattern - [docs/collaboration-playbook.md](docs/collaboration-playbook.md): high-level
- [docs/downstream-onboarding-playbook.md](docs/downstream-onboarding-playbook.md): PM-owned initial downstream export workflow operating pattern
- [docs/downstream-upgrade-playbook.md](docs/downstream-upgrade-playbook.md): PM-owned downstream upgrade workflow - [docs/project/mailbox-collaboration-model.md](docs/project/mailbox-collaboration-model.md):
- [docs/export-manifest.md](docs/export-manifest.md): per-file export and merge strategy mailbox-first communication model
- [docs/downstream-onboarding-playbook.md](docs/downstream-onboarding-playbook.md):
PM-owned initial downstream export workflow
- [docs/downstream-upgrade-playbook.md](docs/downstream-upgrade-playbook.md):
PM-owned downstream upgrade workflow
- [docs/export-manifest.md](docs/export-manifest.md): per-file export and merge
strategy
- [minions/roles](minions/roles): role charters - [minions/roles](minions/roles): role charters
- [minions/plans](minions/plans): formal planning artifacts - [minions/plans](minions/plans): formal planning artifacts
- [minions/chat](minions/chat): durable conversation threads - [minions/mail](minions/mail): mailbox packet coordination
- [minions/chat](minions/chat): PM-owned continuity summaries
## Guardrail Reminder ## Guardrail Reminder
Minions may keep role context in their role files under [minions/roles](minions/roles), but no minion may alter existing base guardrails/rules without explicit Operator approval. Minions may keep role context in their role files under
[minions/roles](minions/roles), but no minion may alter existing base
guardrails/rules without explicit Operator approval.

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. 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 - plans are for formal scope and gates
- role files define responsibilities - role files define responsibilities
- runtime truth is validated separately from commit history - 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 - 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 ## 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 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 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 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 - deployed but not actually running
- architecture drifting without an explicit owner - architecture drifting without an explicit owner
- PM approving commit history instead of runtime truth - 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 - 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: 6. Treat downstream-owned files as project surfaces, not template clones:
- project `README.md` - project `README.md`
- live plans - live plans
- live chat history - live mail packet history
- live chat summary history
- downstream `CHANGELOG.md` - downstream `CHANGELOG.md`
- `ROADMAP.md` - `ROADMAP.md`
- `TODO.md` - `TODO.md`
7. Run the onboarding checklist with the Operator and fill in project-specific 7. Run the onboarding checklist with the Operator and fill in project-specific
decisions. 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. 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`. `docs/downstream-upgrade-playbook.md`.
## Manual-Merge Guidance ## Manual-Merge Guidance
@@ -109,5 +117,6 @@ clone.
- files exported directly from template - files exported directly from template
- files manually merged for downstream use - files manually merged for downstream use
- files intentionally left downstream-owned - 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 - open Operator decisions
- first commit scope and next owner - 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`. `docs/operator-onboarding-checklist.md`, and `minion-version.md`.
8. Preserve `downstream-owned` files unless the Operator explicitly directs a 8. Preserve `downstream-owned` files unless the Operator explicitly directs a
project-specific rewrite. project-specific rewrite.
9. Record the upgrade packet in the active chat thread and downstream 9. Record the upgrade packet in `minions/mail/`, mirror the same-day summary
`CHANGELOG.md`. into `minions/chat/`, and update the downstream `CHANGELOG.md`.
10. After approval, replace `.minions-template/` with the new approved snapshot 10. After approval, replace `.minions-template/` with the new approved snapshot
and remove `.minions-template.next/`. and remove `.minions-template.next/`.
11. Update the base-template portion of `minion-version.md` only after the live 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 | | `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 | | `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/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/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-onboarding-playbook.md` | yes | `template-replace` | PM | baseline initial onboarding procedure |
| `docs/downstream-upgrade-playbook.md` | yes | `template-replace` | PM | baseline downstream-upgrade 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/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/README.md` | yes | `template-replace` | PM | baseline planning guidance |
| `minions/plans/milestone-plan-template.md` | yes | `template-replace` | PM | baseline planning template | | `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/mail/README.md` | yes | `template-replace` | PM | baseline mailbox workflow guidance |
| `minions/chat/general-thread-template.md` | yes | `template-replace` | PM | baseline general thread template | | `minions/mail/packet-template.md` | yes | `template-replace` | PM | baseline packet structure |
| `minions/chat/topic-thread-template.md` | yes | `template-replace` | PM | baseline topic thread template | | `minions/chat/README.md` | yes | `template-replace` | PM | baseline PM-summary workflow guidance |
| `minions/chat/*.md` daily/topic history | yes | `downstream-owned` | PM / Operator | preserve downstream discussion history | | `minions/chat/general-thread-template.md` | yes | `template-replace` | PM | baseline daily summary template |
| `minions/plans/*.md` live plan docs | yes | `downstream-owned` | PM | preserve project-specific plans and status | | `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 | | `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 | | `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 - `CHANGELOG.md` initialized and owner set
- `ROADMAP.md` initialized and owner set - `ROADMAP.md` initialized and owner set
- `TODO.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) - vendored template snapshot initialized (recommended `.minions-template/`; exclude `.git/` and `do-not-export` files)
- initial downstream export completed using `docs/downstream-onboarding-playbook.md` - initial downstream export completed using `docs/downstream-onboarding-playbook.md`
- downstream template-upgrade owner confirmed (default `PM`) - 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.

5
minion-version.md
View File

@@ -1,10 +1,10 @@
# Minion Template Version # Minion Template Version
Current version: 1.3.1-1.0.0 Current version: 1.4.0-1.0.0
Version format for downstream repos: `<base-template-version>-<downstream-version>` Version format for downstream repos: `<base-template-version>-<downstream-version>`
Example downstream version: `1.3.1-1.0.0` Example downstream version: `1.4.0-1.0.0`
## Downstream Onboarding Method ## Downstream Onboarding Method
@@ -12,6 +12,7 @@ Example downstream version: `1.3.1-1.0.0`
- Use [docs/downstream-onboarding-playbook.md](docs/downstream-onboarding-playbook.md) and [docs/export-manifest.md](docs/export-manifest.md) to perform the first controlled export into the live downstream repo. - Use [docs/downstream-onboarding-playbook.md](docs/downstream-onboarding-playbook.md) and [docs/export-manifest.md](docs/export-manifest.md) to perform the first controlled export into the live downstream repo.
- Treat `INIT.md`, `MEMORY.md`, `docs/operator-onboarding-checklist.md`, and `minion-version.md` as onboarding merge files, not blind copies. - Treat `INIT.md`, `MEMORY.md`, `docs/operator-onboarding-checklist.md`, and `minion-version.md` as onboarding merge files, not blind copies.
- Exclude `.git/` and `do-not-export` files such as `.mm.md` from the vendored snapshot. - Exclude `.git/` and `do-not-export` files such as `.mm.md` from the vendored snapshot.
- After the first export, bootstrap mailbox coordination with `docs/project/mailbox-collaboration-model.md`, `minions/mail/README.md`, and `minions/mail/packet-template.md` before opening new actionable packets.
- Commit the vendored snapshot and exported live files together so later upgrades have a stable comparison base. - Commit the vendored snapshot and exported live files together so later upgrades have a stable comparison base.
## Downstream Upgrade Method ## Downstream Upgrade Method

6
minions/README.md
View File

@@ -8,7 +8,8 @@ This folder is the durable coordination layer for the minion workflow.
minions/ minions/
roles/ # Role-specific charters roles/ # Role-specific charters
plans/ # Formal plans and milestone docs plans/ # Formal plans and milestone docs
chat/ # Dated discussion threads mail/ # Mailbox packets and handoffs
chat/ # PM-owned summaries and continuity
``` ```
## Rules ## Rules
@@ -16,4 +17,5 @@ minions/
- `MEMORY.md` remains the shared project truth - `MEMORY.md` remains the shared project truth
- `roles/` contains only role-specific deltas - `roles/` contains only role-specific deltas
- `plans/` should be formal and reviewable - `plans/` should be formal and reviewable
- `chat/` should be human-readable and durable across sessions - `mail/` is the default coordination surface for actionable packets
- `chat/` should be PM-owned, human-readable, and durable across sessions

62
minions/chat/README.md
View File

@@ -1,54 +1,52 @@
# Chat Threads # Chat Threads
Use this folder for durable, git-backed discussion. Use this folder for PM-owned summaries and historical continuity.
This is not the primary role-to-role request/response surface anymore.
Actionable minion communication should default to `minions/mail/`.
## Recommended Files ## Recommended Files
- `YYYY-MM-DD.md` for general daily notes - `YYYY-MM-DD.md` for PM daily summary notes
- `YYYY-MM-DD-topic-name.md` for substantive topics - `YYYY-MM-DD-topic-name.md` for PM topic summaries or historical recap
## Required Workflow ## Required Workflow
- when a minion is bootstrapped, it must post a short role/intention announcement in the current `YYYY-MM-DD.md` general thread - `PM` owns the daily chat thread by default
- all chat-thread changes are commit-by-default to keep the coordination trail durable - when a minion is bootstrapped or a packet closes, `PM` should mirror a short
same-day summary into the current `YYYY-MM-DD.md`
- all chat-thread changes are commit-by-default to keep the continuity trail
durable
- default commit message format for chat-thread updates: `chat: YYYY-MM-DD thread update` - default commit message format for chat-thread updates: `chat: YYYY-MM-DD thread update`
## When To Break Out A Topic Thread ## When To Break Out A Topic Thread
Create a dedicated thread when: Create a dedicated PM topic summary when:
- a discussion lasts more than a few exchanges - a mailbox packet series needs a condensed historical recap
- a design or review topic has its own decisions - a design or review topic has enough history that a summary helps humans
- bug scrub findings need separation from the daily thread - bug scrub findings need a clean summary separate from the daily thread
- a deploy / runtime topic needs clear history - a deploy / runtime topic needs a durable operator-facing recap
## Required Format For Actionable Handoffs ## Summary Format
Daily or topic summaries should usually include:
- current gate
- important packet links
- current next owner
- operator-relevant context
## Required Format For Summary Decisions
```text ```text
DECISION: DECISION:
RATIONALE: RATIONALE:
ACTION NEEDED: ACTION NEEDED:
NEXT OWNER:
``` ```
## Completion Handoff Contract (ADHD-Friendly) ## Important Rule
All minions must close work with a clear handoff packet in the active daily thread. Use `minions/mail/` for primary handoffs and packet exchanges. Use
`minions/chat/` to summarize them.
Required structure (in this exact order):
1. `DECISION:` what is now true
2. `RATIONALE:` why this is the right state
3. `SCOPE COMPLETED:` what was done
4. `OUT OF SCOPE:` what was not done
5. `EVIDENCE:` files, commands, runtime outputs, timestamps as applicable
6. `BLOCKERS/RISKS:` anything that could stop the next step
7. `ACTION NEEDED:` explicit next steps with owner labels
8. `NEXT OWNER:` exactly one of PM, AM, CM, SM, OM-Test, OM, Operator
9. `READY CHECK:` pass/fail statement for handoff readiness
Hard rules:
- No minion may mark work complete without naming the `NEXT OWNER`.
- No minion may accept handoff with ambiguous ownership.
- If blocked, handoff is still required with a blocker packet and explicit owner for unblock.
- PM must reject handoffs that do not include evidence and clear next-owner assignment.

51
minions/chat/general-thread-template.md
View File

@@ -1,52 +1,25 @@
# General Thread Template # PM Daily Summary Template
## Bootstrap Announcements
Use this once per minion bootstrap.
- minion:
- role:
- intent for this session:
## PM ## PM
General coordination notes for the day.
- active milestone: - active milestone:
- current gate: - current gate:
- next review point: - important packets:
- next owner:
- operator-relevant notes:
## AM ## Bootstrap Notes
DECISION: Mirror short same-day bootstrap notes here when useful.
RATIONALE: - minion:
- role:
- summary:
ACTION NEEDED: ## Topic Recap Links
## CM - related packet:
- summary note:
DECISION:
RATIONALE:
ACTION NEEDED:
## SM
DECISION:
RATIONALE:
ACTION NEEDED:
## OM-Test / OM
DECISION:
RATIONALE:
ACTION NEEDED:
## Operator ## Operator

44
minions/chat/topic-thread-template.md
View File

@@ -1,6 +1,8 @@
## PM Request # PM Topic Summary Template
TARGET ROLE: Related packets:
- `minions/mail/YYYY-MM-DD-sender-to-recipient-topic/`
DECISION: DECISION:
@@ -8,38 +10,10 @@ RATIONALE:
ACTION NEEDED: ACTION NEEDED:
### AM NEXT OWNER:
No action needed yet. ## Summary
### CM - what changed:
- key evidence:
No action needed yet. - remaining risk:
### SM
No action needed yet.
### OM-Test / OM
No action needed yet.
### Operator
No action needed until PM reviews the response.
---
## Response
Architecture findings / proposal / implementation report goes here.
---
## PM Review
DECISION:
RATIONALE:
ACTION NEEDED:

72
minions/mail/README.md Normal file
View File

@@ -0,0 +1,72 @@
# Mail Packets
Use this folder for primary minion-to-minion communication.
This is the mailbox-style coordination surface. New actionable requests,
responses, and verdicts should default here rather than going into shared chat
threads.
## Packet Layout
```text
minions/mail/
YYYY-MM-DD-sender-to-recipient-topic/
request.md
response.md
verdict.md # optional
```
## Naming Rule
Use:
`YYYY-MM-DD-<sender>-to-<recipient>-<topic>`
Examples:
- `2026-04-14-pm-to-sm-packet-clarification`
- `2026-04-14-cm-to-pm-implementation-pressure`
## Ownership Rule
- sender writes `request.md`
- addressed recipient writes `response.md`
- gate owner writes `verdict.md` when needed
- no minion edits another minion's packet file
## Workflow Rule
1. open packet
2. commit packet request
3. recipient responds in owned file
4. gate owner records verdict if needed
5. `PM` mirrors durable state into shared docs and same-day chat summary
## Staged Rollout Rule
- already-open legacy chat packets may remain where they are until they close
- any new follow-up packet should open in `minions/mail/`
- do not mirror one active packet across both chat and mail
## Bootstrap Steps
Before opening or answering a mailbox packet, read:
1. `MEMORY.md`
2. `docs/project/mailbox-collaboration-model.md`
3. `minions/mail/README.md`
4. `minions/mail/packet-template.md`
## Packet Content Rule
Use `packet-template.md` as the default skeleton.
Keep packet files concise, explicit, and owner-labeled.
## Relationship To `minions/chat/`
- `minions/mail/` is the primary coordination surface
- `minions/chat/` is the PM-owned daily summary and historical continuity
surface
See `docs/project/mailbox-collaboration-model.md` for the full repo policy.

75
minions/mail/packet-template.md Normal file
View File

@@ -0,0 +1,75 @@
# Packet Template
Use this as the default structure for a new mailbox packet.
Recommended path:
`minions/mail/YYYY-MM-DD-sender-to-recipient-topic/`
## `request.md`
```text
TARGET ROLE:
DECISION:
RATIONALE:
ACTION NEEDED:
### AM
No action needed yet.
### CM
No action needed yet.
### SM
No action needed yet.
### OM-Test / OM
No action needed yet.
### Operator
No action needed until the response is reviewed.
```
## `response.md`
```text
DECISION:
RATIONALE:
SCOPE COMPLETED:
OUT OF SCOPE:
EVIDENCE:
BLOCKERS/RISKS:
ACTION NEEDED:
NEXT OWNER:
READY CHECK:
```
## `verdict.md` (optional)
```text
DECISION:
RATIONALE:
ACTION NEEDED:
NEXT OWNER:
READY CHECK:
```

3
minions/plans/milestone-plan-template.md
View File

@@ -6,7 +6,8 @@ Status: Active
Current phase: Current phase:
Next review point: Next review point:
Primary objective: Primary objective:
Working thread: `minions/chat/YYYY-MM-DD-topic-name.md` Primary packet: `minions/mail/YYYY-MM-DD-sender-to-recipient-topic/`
PM summary thread: `minions/chat/YYYY-MM-DD.md`
Roadmap linkage: `ROADMAP.md` Roadmap linkage: `ROADMAP.md`
TODO linkage: `TODO.md` TODO linkage: `TODO.md`
Changelog impact expected: yes/no Changelog impact expected: yes/no