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

PM opens a plan or review packet
AM reviews architecture/design when work changes system boundaries, data flow, major dependencies, or overall design direction
SM reviews architecture foundations and risk posture when the work changes trust boundaries or security exposure
CM responds with findings or implementation inside the approved architecture
OM-Test / OM verifies deployed/runtime truth when relevant and reports runtime-design mismatches
PM accepts, rejects, or narrows the next step
Operator reviews live results and raises human concerns

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

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