diff --git a/CHANGELOG.md b/CHANGELOG.md index 0b74078..7e2909e 100644 --- a/CHANGELOG.md +++ b/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) diff --git a/INIT.md b/INIT.md index 4640050..ca80e98 100644 --- a/INIT.md +++ b/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 diff --git a/MEMORY.md b/MEMORY.md index 2233781..9b3965d 100644 --- a/MEMORY.md +++ b/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): diff --git a/README.md b/README.md index d33173d..55d5679 100644 --- a/README.md +++ b/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. diff --git a/docs/collaboration-playbook.md b/docs/collaboration-playbook.md index 802a71b..07e89b9 100644 --- a/docs/collaboration-playbook.md +++ b/docs/collaboration-playbook.md @@ -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 diff --git a/docs/downstream-onboarding-playbook.md b/docs/downstream-onboarding-playbook.md index c8c5ba7..526e695 100644 --- a/docs/downstream-onboarding-playbook.md +++ b/docs/downstream-onboarding-playbook.md @@ -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 diff --git a/docs/downstream-upgrade-playbook.md b/docs/downstream-upgrade-playbook.md index 5466104..676c71b 100644 --- a/docs/downstream-upgrade-playbook.md +++ b/docs/downstream-upgrade-playbook.md @@ -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 diff --git a/docs/export-manifest.md b/docs/export-manifest.md index af00312..3ce378e 100644 --- a/docs/export-manifest.md +++ b/docs/export-manifest.md @@ -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 | diff --git a/docs/operator-onboarding-checklist.md b/docs/operator-onboarding-checklist.md index ebd8da0..65af1bb 100644 --- a/docs/operator-onboarding-checklist.md +++ b/docs/operator-onboarding-checklist.md @@ -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`) diff --git a/docs/project/mailbox-collaboration-model.md b/docs/project/mailbox-collaboration-model.md new file mode 100644 index 0000000..1c72ace --- /dev/null +++ b/docs/project/mailbox-collaboration-model.md @@ -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--to--` + +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. diff --git a/minion-version.md b/minion-version.md index 5cf5dc7..eb30248 100644 --- a/minion-version.md +++ b/minion-version.md @@ -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: `-` -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 diff --git a/minions/README.md b/minions/README.md index 03a9d90..f60a820 100644 --- a/minions/README.md +++ b/minions/README.md @@ -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 diff --git a/minions/chat/README.md b/minions/chat/README.md index f5cace7..5816079 100644 --- a/minions/chat/README.md +++ b/minions/chat/README.md @@ -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. diff --git a/minions/chat/general-thread-template.md b/minions/chat/general-thread-template.md index e8687a6..e21d09e 100644 --- a/minions/chat/general-thread-template.md +++ b/minions/chat/general-thread-template.md @@ -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 diff --git a/minions/chat/topic-thread-template.md b/minions/chat/topic-thread-template.md index 98a5c4a..1c05298 100644 --- a/minions/chat/topic-thread-template.md +++ b/minions/chat/topic-thread-template.md @@ -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: diff --git a/minions/mail/README.md b/minions/mail/README.md new file mode 100644 index 0000000..7b93c5c --- /dev/null +++ b/minions/mail/README.md @@ -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--to--` + +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. diff --git a/minions/mail/packet-template.md b/minions/mail/packet-template.md new file mode 100644 index 0000000..94dbb07 --- /dev/null +++ b/minions/mail/packet-template.md @@ -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: +``` diff --git a/minions/plans/milestone-plan-template.md b/minions/plans/milestone-plan-template.md index f80157b..4c8b4b3 100644 --- a/minions/plans/milestone-plan-template.md +++ b/minions/plans/milestone-plan-template.md @@ -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