docs: add mailbox-first collaboration model

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

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` — 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):