123 lines
4.3 KiB
Markdown
123 lines
4.3 KiB
Markdown
# 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
|