docs: add mailbox-first collaboration model
This commit is contained in:
deamonkai
28
CHANGELOG.md
28
CHANGELOG.md
@@ -2,6 +2,34 @@
|
||||
|
||||
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
|
||||
|
||||
- Commit hash: pending (next commit)
|
||||
|
||||
18
INIT.md
18
INIT.md
@@ -9,7 +9,8 @@ SM, and OM discipline, durable evidence, and milestone execution.
|
||||
|
||||
- collaboration baseline imported
|
||||
- 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
|
||||
|
||||
## Immediate Startup Sequence
|
||||
@@ -22,7 +23,13 @@ SM, and OM discipline, durable evidence, and milestone execution.
|
||||
- environments
|
||||
- safety constraints
|
||||
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.
|
||||
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)
|
||||
|
||||
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):
|
||||
|
||||
@@ -119,5 +128,6 @@ This project is considered fully onboarded when all are true:
|
||||
- operator onboarding checklist status is approved
|
||||
- project-specific MEMORY sections are complete
|
||||
- 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
|
||||
|
||||
54
MEMORY.md
54
MEMORY.md
@@ -46,6 +46,35 @@ This project uses multiple AI agents ("minions") that coordinate through git:
|
||||
- `OM-Test` — test-environment operations, restarts, runtime verification
|
||||
- `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 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
|
||||
- `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
|
||||
- actionable packet communication belongs in `minions/mail/`
|
||||
- Role-specific deltas belong in `minions/roles/`
|
||||
- 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
|
||||
|
||||
## 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 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.
|
||||
- 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.
|
||||
- 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.
|
||||
@@ -191,15 +221,23 @@ Interpretation:
|
||||
|
||||
## Communication Conventions
|
||||
|
||||
- general daily thread: `minions/chat/YYYY-MM-DD.md`
|
||||
- substantive topic thread: `minions/chat/YYYY-MM-DD-topic-name.md`
|
||||
- when a minion is bootstrapped, it must announce itself in the current general daily thread
|
||||
- chat-thread updates are commit-by-default so discussion remains durable in git history
|
||||
- default commit message format for chat-thread updates: `chat: YYYY-MM-DD thread update`
|
||||
- primary packet directory: `minions/mail/YYYY-MM-DD-sender-to-recipient-topic/`
|
||||
- sender writes `request.md`
|
||||
- addressed recipient writes `response.md`
|
||||
- gate owner writes `verdict.md` when needed
|
||||
- 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)
|
||||
|
||||
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):
|
||||
|
||||
|
||||
54
README.md
54
README.md
@@ -1,6 +1,7 @@
|
||||
# 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:
|
||||
|
||||
@@ -14,43 +15,64 @@ It provides a baseline operating model for:
|
||||
|
||||
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
|
||||
|
||||
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
|
||||
- role-specific context files
|
||||
- formal planning artifacts
|
||||
- chat-thread decision history
|
||||
- mailbox packet history
|
||||
- PM-owned continuity summaries
|
||||
- explicit handoff and evidence discipline
|
||||
|
||||
## 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).
|
||||
2. Complete [docs/operator-onboarding-checklist.md](docs/operator-onboarding-checklist.md) with the Operator.
|
||||
1. Establish a filtered vendored template snapshot and perform the first
|
||||
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).
|
||||
4. Open the first milestone plan from [minions/plans](minions/plans).
|
||||
5. Create and use the current daily thread in [minions/chat](minions/chat).
|
||||
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.
|
||||
5. Bootstrap mailbox coordination using
|
||||
[docs/project/mailbox-collaboration-model.md](docs/project/mailbox-collaboration-model.md)
|
||||
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
|
||||
|
||||
- [INIT.md](INIT.md): startup framing and handoff expectations
|
||||
- [MEMORY.md](MEMORY.md): shared truth and baseline guardrails
|
||||
- [minion-version.md](minion-version.md): template/downstream versioning format
|
||||
- [docs/collaboration-playbook.md](docs/collaboration-playbook.md): high-level operating pattern
|
||||
- [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
|
||||
- [docs/collaboration-playbook.md](docs/collaboration-playbook.md): high-level
|
||||
operating pattern
|
||||
- [docs/project/mailbox-collaboration-model.md](docs/project/mailbox-collaboration-model.md):
|
||||
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/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
|
||||
|
||||
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.
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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 |
|
||||
|
||||
@@ -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
239
docs/project/mailbox-collaboration-model.md
Normal 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.
|
||||
@@ -1,10 +1,10 @@
|
||||
# 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>`
|
||||
|
||||
Example downstream version: `1.3.1-1.0.0`
|
||||
Example downstream version: `1.4.0-1.0.0`
|
||||
|
||||
## 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.
|
||||
- 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.
|
||||
- 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.
|
||||
|
||||
## Downstream Upgrade Method
|
||||
|
||||
@@ -8,7 +8,8 @@ This folder is the durable coordination layer for the minion workflow.
|
||||
minions/
|
||||
roles/ # Role-specific charters
|
||||
plans/ # Formal plans and milestone docs
|
||||
chat/ # Dated discussion threads
|
||||
mail/ # Mailbox packets and handoffs
|
||||
chat/ # PM-owned summaries and continuity
|
||||
```
|
||||
|
||||
## Rules
|
||||
@@ -16,4 +17,5 @@ minions/
|
||||
- `MEMORY.md` remains the shared project truth
|
||||
- `roles/` contains only role-specific deltas
|
||||
- `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
|
||||
|
||||
@@ -1,54 +1,52 @@
|
||||
# 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
|
||||
|
||||
- `YYYY-MM-DD.md` for general daily notes
|
||||
- `YYYY-MM-DD-topic-name.md` for substantive topics
|
||||
- `YYYY-MM-DD.md` for PM daily summary notes
|
||||
- `YYYY-MM-DD-topic-name.md` for PM topic summaries or historical recap
|
||||
|
||||
## Required Workflow
|
||||
|
||||
- when a minion is bootstrapped, it must post a short role/intention announcement in the current `YYYY-MM-DD.md` general thread
|
||||
- all chat-thread changes are commit-by-default to keep the coordination trail durable
|
||||
- `PM` owns the daily chat thread by default
|
||||
- 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`
|
||||
|
||||
## 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 design or review topic has its own decisions
|
||||
- bug scrub findings need separation from the daily thread
|
||||
- a deploy / runtime topic needs clear history
|
||||
- a mailbox packet series needs a condensed historical recap
|
||||
- a design or review topic has enough history that a summary helps humans
|
||||
- bug scrub findings need a clean summary separate from the daily thread
|
||||
- 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
|
||||
DECISION:
|
||||
RATIONALE:
|
||||
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.
|
||||
|
||||
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.
|
||||
Use `minions/mail/` for primary handoffs and packet exchanges. Use
|
||||
`minions/chat/` to summarize them.
|
||||
|
||||
@@ -1,52 +1,25 @@
|
||||
# General Thread Template
|
||||
|
||||
## Bootstrap Announcements
|
||||
|
||||
Use this once per minion bootstrap.
|
||||
|
||||
- minion:
|
||||
- role:
|
||||
- intent for this session:
|
||||
# PM Daily Summary Template
|
||||
|
||||
## PM
|
||||
|
||||
General coordination notes for the day.
|
||||
|
||||
- active milestone:
|
||||
- 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
|
||||
|
||||
DECISION:
|
||||
|
||||
RATIONALE:
|
||||
|
||||
ACTION NEEDED:
|
||||
|
||||
## SM
|
||||
|
||||
DECISION:
|
||||
|
||||
RATIONALE:
|
||||
|
||||
ACTION NEEDED:
|
||||
|
||||
## OM-Test / OM
|
||||
|
||||
DECISION:
|
||||
|
||||
RATIONALE:
|
||||
|
||||
ACTION NEEDED:
|
||||
- related packet:
|
||||
- summary note:
|
||||
|
||||
## Operator
|
||||
|
||||
|
||||
@@ -1,6 +1,8 @@
|
||||
## PM Request
|
||||
# PM Topic Summary Template
|
||||
|
||||
TARGET ROLE:
|
||||
Related packets:
|
||||
|
||||
- `minions/mail/YYYY-MM-DD-sender-to-recipient-topic/`
|
||||
|
||||
DECISION:
|
||||
|
||||
@@ -8,38 +10,10 @@ RATIONALE:
|
||||
|
||||
ACTION NEEDED:
|
||||
|
||||
### AM
|
||||
NEXT OWNER:
|
||||
|
||||
No action needed yet.
|
||||
## Summary
|
||||
|
||||
### CM
|
||||
|
||||
No action needed yet.
|
||||
|
||||
### 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:
|
||||
- what changed:
|
||||
- key evidence:
|
||||
- remaining risk:
|
||||
|
||||
72
minions/mail/README.md
Normal file
72
minions/mail/README.md
Normal 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
75
minions/mail/packet-template.md
Normal 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:
|
||||
```
|
||||
@@ -6,7 +6,8 @@ Status: Active
|
||||
Current phase:
|
||||
Next review point:
|
||||
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`
|
||||
TODO linkage: `TODO.md`
|
||||
Changelog impact expected: yes/no
|
||||
|
||||
Reference in New Issue
Block a user