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

6
minions/README.md
View File

@@ -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

62
minions/chat/README.md
View File

@@ -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.

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

@@ -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

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:
@@ -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
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:
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