# 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