From 6d8cab8d88ffe1c75cf373ad38660e54611ffbb0 Mon Sep 17 00:00:00 2001 From: deamonkai <26585050+deamonkai@users.noreply.github.com> Date: Tue, 14 Apr 2026 08:47:10 -0500 Subject: [PATCH] docs: clarify mailbox packet flow --- CHANGELOG.md | 11 ++++++ MEMORY.md | 4 ++- docs/project/mailbox-collaboration-model.md | 39 +++++++++++++++++++++ minions/mail/README.md | 9 +++++ minions/mail/packet-template.md | 20 ----------- minions/roles/AM.md | 4 ++- minions/roles/CM.md | 3 +- 7 files changed, 67 insertions(+), 23 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 7e2909e..b1dbc60 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -25,6 +25,17 @@ All notable changes to this repository are tracked here. - `docs/project/mailbox-collaboration-model.md` - `minions/mail/README.md` - `minions/mail/packet-template.md` +- Added ASCII mailbox flow diagrams to make packet ownership and PM summary + duties easier to onboard in: + - `docs/project/mailbox-collaboration-model.md` + - `minions/mail/README.md` +- Corrected mailbox-model drift so shared rules and role charters point minions + to owned mail packets while `PM` owns same-day chat summaries, and simplified + the request template to the single-owner packet shape in: + - `MEMORY.md` + - `minions/roles/CM.md` + - `minions/roles/AM.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 diff --git a/MEMORY.md b/MEMORY.md index 9b3965d..1a2cd5e 100644 --- a/MEMORY.md +++ b/MEMORY.md @@ -88,7 +88,9 @@ Current rollout rule: - Role-specific deltas belong in `minions/roles/` - Formal plans belong in `minions/plans/` - 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 made durable in owned mail packets the + same day, and `PM` should receive enough context to publish a same-day chat + summary ## CHANGELOG Maintenance Rule diff --git a/docs/project/mailbox-collaboration-model.md b/docs/project/mailbox-collaboration-model.md index 1c72ace..6fa857d 100644 --- a/docs/project/mailbox-collaboration-model.md +++ b/docs/project/mailbox-collaboration-model.md @@ -105,6 +105,45 @@ This keeps: - project truth in shared state docs - human continuity in chat summaries +## ASCII Flow + +```text + MAILBOX-FIRST COLLABORATION + + new actionable work / request / finding / handoff + | + v ++----------------------------------------------------------------------------------+ +| minions/mail/YYYY-MM-DD-sender-to-recipient-topic/ | +| | +| request.md -> written by sender only | +| response.md -> written by addressed recipient only | +| verdict.md -> written by gate owner only (usually PM, only if needed) | ++----------------------------------------------------------------------------------+ + | + v + packet decision / response exists + | + v + +---------------------------------------------+ + | PM mirrors durable outcomes into project | + | truth docs as needed: | + | - README.md | + | - MEMORY.md | + | - ROADMAP.md | + | - TODO.md | + | - plans / other controlled docs | + +---------------------------------------------+ + | + v + +---------------------------------------------+ + | PM posts same-day summary into | + | minions/chat/YYYY-MM-DD.md | + | chat is summary/history only | + | not the live multi-writer work surface | + +---------------------------------------------+ +``` + ## Role Of Other Surfaces ### `minions/mail/` diff --git a/minions/mail/README.md b/minions/mail/README.md index 7b93c5c..ebc5f62 100644 --- a/minions/mail/README.md +++ b/minions/mail/README.md @@ -42,6 +42,15 @@ Examples: 4. gate owner records verdict if needed 5. `PM` mirrors durable state into shared docs and same-day chat summary +## ASCII Flow + +```text +sender -> opens packet -> writes request.md +recipient -> reads request -> writes response.md +gate owner -> reviews -> writes verdict.md (if needed) +PM -> curates -> updates shared docs + daily chat summary +``` + ## Staged Rollout Rule - already-open legacy chat packets may remain where they are until they close diff --git a/minions/mail/packet-template.md b/minions/mail/packet-template.md index 94dbb07..d893941 100644 --- a/minions/mail/packet-template.md +++ b/minions/mail/packet-template.md @@ -16,26 +16,6 @@ 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` diff --git a/minions/roles/AM.md b/minions/roles/AM.md index 5df2c8e..e5008b1 100644 --- a/minions/roles/AM.md +++ b/minions/roles/AM.md @@ -20,7 +20,9 @@ project. - provide CM with clear design constraints and rationale for implementation work - work with SM so architecture and design choices rest on solid security foundations - incorporate OM-Test / OM runtime feedback when architecture or design is not meeting project goals -- keep architecture decisions durable in plans, docs, or chat the same day they change +- keep architecture decisions durable in plans, docs, or owned mail packets the + same day they change and ensure `PM` has enough context for a same-day + summary ## Outputs diff --git a/minions/roles/CM.md b/minions/roles/CM.md index d59fd20..38e46e1 100644 --- a/minions/roles/CM.md +++ b/minions/roles/CM.md @@ -18,7 +18,8 @@ PM, AM, and the operator. - implement within the approved architecture and surface design pressure early - add or update tests when behavior changes - report technical findings clearly -- mirror milestone-relevant progress into chat the same day +- make milestone-relevant progress durable in owned mail packets the same day + and ensure `PM` has enough context for a same-day summary - distinguish between: - code merged - code deployed