minions-template/docs/downstream-onboarding-playbook.md

Downstream Onboarding Playbook

Owner: PM by default

Use this playbook when introducing the minion template into a downstream project for the first time.

Core Idea

Initial onboarding should not be a blind copy of the template repo into the downstream repo.

Treat onboarding as the first controlled export from a vendored template snapshot.

This gives AI agents a durable provenance model:

1. vendored template baseline
2. live downstream operating files
3. project-specific downstream state

Recommended Paths

• approved template snapshot: .minions-template/
• live downstream files: repo root, docs/, and minions/

Do not stage onboarding from .minions-template.next/; that path is for later upgrade candidates.

The vendored snapshot is an export-ready copy of the template, not a full Git clone.

• exclude .git/
• exclude files marked do-not-export in docs/export-manifest.md
• .mm.md should not appear in .minions-template/ unless the Operator intentionally chooses to carry MM context downstream

Ownership

• PM owns the onboarding export packet and Operator-facing checklist
• AM reviews architecture/design assumptions when project structure or system boundaries need clarification
• SM reviews baseline guardrails, secrets posture, and trust-boundary setup
• CM helps apply technical merges where project constraints require them
• OM-Test / OM confirm environment and runtime workflow expectations when relevant
• Operator approves the exported operating surface

Onboarding Workflow

1. Create .minions-template/ as an export-ready snapshot of the template:
   • copy the files needed for onboarding and future upgrades
   • do not carry Git metadata such as .git/
   • do not carry do-not-export files such as .mm.md
2. Review docs/export-manifest.md before exporting any live files.
3. Export template-replace files from .minions-template/ into the live downstream repo.
4. Create manual-merge files by combining the template baseline with project-specific reality:
   • INIT.md
   • MEMORY.md
   • docs/operator-onboarding-checklist.md
   • minion-version.md
5. Do not export do-not-export files, and do not keep them in the vendored snapshot, unless the Operator explicitly wants them downstream.
6. Treat downstream-owned files as project surfaces, not template clones:
   • project README.md
   • live plans
   • live mail packet history
   • live chat summary history
   • downstream CHANGELOG.md
   • ROADMAP.md
   • TODO.md
7. Run the onboarding checklist with the Operator and fill in project-specific decisions.
8. Bootstrap mailbox use in the live downstream repo:
   • read MEMORY.md
   • read docs/project/mailbox-collaboration-model.md
   • read minions/mail/README.md
   • read minions/mail/packet-template.md
   • use minions/mail/ for new actionable packets
   • use minions/chat/ for PM daily summaries
9. Commit the vendored snapshot and exported live files together so the repo has a clear starting baseline.
10. After onboarding is approved, future template changes should use docs/downstream-upgrade-playbook.md.

Manual-Merge Guidance

INIT.md

• keep the template workflow framing
• adapt onboarding language to the downstream project
• preserve project-specific paths, environments, and immediate startup notes

MEMORY.md

• keep shared guardrails and role definitions from the template
• add project-specific purpose, architecture, environments, and constraints
• preserve downstream operational truth over template examples

docs/operator-onboarding-checklist.md

• keep the evolving checklist from the template
• record real downstream decisions instead of leaving template placeholders

minion-version.md

• set the initial base-template version from .minions-template/
• initialize the downstream version suffix for the project

Minimum PM Onboarding Packet

• template version being onboarded
• vendored snapshot path
• confirmation that .git/ and do-not-export files were excluded from the vendored snapshot
• files exported directly from template
• files manually merged for downstream use
• files intentionally left downstream-owned
• confirmation that mailbox bootstrap docs were reviewed and minions/mail/ is the active packet surface for new work
• open Operator decisions
• first commit scope and next owner