# 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.

- chat is for decisions and back-and-forth
- 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

## Recommended Lifecycle

1. `PM` opens a plan or review 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 the template snapshot into `.minions-template/`
- 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 template snapshot in `.minions-template/`
- stage the incoming 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
- chat discussion getting lost between sessions
- role boundaries blurring under pressure