66 lines
3.1 KiB
Markdown
66 lines
3.1 KiB
Markdown
# 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 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
|
|
- chat discussion getting lost between sessions
|
|
- role boundaries blurring under pressure
|