minions-template/docs/collaboration-playbook.md

Collaboration Playbook

This is the high-level operating pattern behind the minion workflow.

Core Idea

Keep the repo as the durable source of coordination truth.

• 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 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
5. OM-Test / OM verifies deployed/runtime truth when relevant and reports runtime-design mismatches
6. PM accepts, rejects, or narrows the next step
7. Operator reviews live results and raises human concerns

PM-Owned Onboarding

Before normal execution cadence, PM runs onboarding with the Operator and captures decisions in docs/operator-onboarding-checklist.md.

Onboarding should explicitly set:

• who fills the AM role and how architecture decisions will be captured
• the default handoff sync mode for each role: commit-only or commit-and-push
• where the vendored template snapshot will live (recommended .minions-template/)
• who owns downstream template upgrades (default PM)
• whether escalation response clocks are enabled for this project
• how CHANGELOG.md, ROADMAP.md, and TODO.md will be maintained
• project-specific guardrail additions beyond template defaults

Onboarding should use docs/downstream-onboarding-playbook.md, not a blind repo copy.

• vendor an export-ready template snapshot into .minions-template/ with .git/ and do-not-export files excluded
• export the live operating files using docs/export-manifest.md
• manually merge INIT.md, MEMORY.md, docs/operator-onboarding-checklist.md, and minion-version.md
• commit the vendored snapshot and exported live state together as the initial baseline

Downstream Upgrades

Use PM as the default owner for downstream template upgrades.

• onboarding should establish .minions-template/ first; upgrades depend on that baseline
• keep the approved export-ready template snapshot in .minions-template/
• stage the incoming export-ready template in a temporary path such as .minions-template.next/
• compare old template, new template, and live downstream files before changing production minion docs
• use docs/export-manifest.md to decide whether each file is replaced, manually merged, or left downstream-owned
• update the downstream base template version only after the live files and vendored snapshot both match the approved upgrade

Common Failure Modes This Prevents

• code merged but not deployed
• deployed but not actually running
• architecture drifting without an explicit owner
• PM approving commit history instead of runtime truth
• packet discussion being lost or overwritten between sessions
• role boundaries blurring under pressure