109 lines
3.9 KiB
Markdown
109 lines
3.9 KiB
Markdown
# Downstream Upgrade Playbook
|
|
|
|
Owner: `PM` by default
|
|
|
|
Use this playbook when a downstream project wants to adopt a newer version of
|
|
the minion template without overwriting project-specific state.
|
|
|
|
For first-time setup, use `docs/downstream-onboarding-playbook.md` instead.
|
|
|
|
## Goal
|
|
|
|
Make downstream upgrades reviewable by comparing:
|
|
|
|
1. the currently approved vendored template
|
|
2. the incoming template version
|
|
3. the live downstream files
|
|
|
|
## Recommended Paths
|
|
|
|
- current approved template snapshot: `.minions-template/`
|
|
- incoming candidate snapshot during upgrade: `.minions-template.next/`
|
|
|
|
If the downstream repo does not already keep a vendored template snapshot, the
|
|
first upgrade should establish one that matches the repo's current base-template
|
|
version before attempting a larger template jump. If the repo is truly new,
|
|
run the onboarding playbook first.
|
|
|
|
Both snapshot paths should contain export-ready copies of the template, not full
|
|
Git clones.
|
|
|
|
- exclude `.git/`
|
|
- exclude files marked `do-not-export` in `docs/export-manifest.md`
|
|
|
|
## Ownership
|
|
|
|
- `PM` owns the upgrade packet, merge order, and Operator-facing decision
|
|
summary
|
|
- `AM` reviews architecture and design changes that affect role boundaries,
|
|
plans, or shared structure
|
|
- `SM` reviews new guardrails, security expectations, and trust-boundary changes
|
|
- `CM` applies downstream file merges that require implementation-oriented
|
|
technical judgment
|
|
- `OM-Test` / `OM` review deployment or runtime workflow changes when relevant
|
|
- `Operator` approves the downstream adoption decision
|
|
|
|
## Upgrade Workflow
|
|
|
|
1. Confirm the downstream repo's current base-template version in
|
|
`minion-version.md`.
|
|
2. Stage the current approved export-ready template snapshot in
|
|
`.minions-template/` if it is not already present.
|
|
3. Import the incoming template version into `.minions-template.next/` using the
|
|
same export-ready filtering rules.
|
|
4. Diff `.minions-template/` against `.minions-template.next/` to see what the
|
|
template changed.
|
|
5. Use `docs/export-manifest.md` to classify each affected live file as:
|
|
- `template-replace`
|
|
- `manual-merge`
|
|
- `downstream-owned`
|
|
- `do-not-export`
|
|
6. Apply `template-replace` files first, while reviewing any intentional local
|
|
downstream divergence before overwriting.
|
|
7. Manually merge files such as `MEMORY.md`, `INIT.md`,
|
|
`docs/operator-onboarding-checklist.md`, and `minion-version.md`.
|
|
8. Preserve `downstream-owned` files unless the Operator explicitly directs a
|
|
project-specific rewrite.
|
|
9. Record the upgrade packet in `minions/mail/`, mirror the same-day summary
|
|
into `minions/chat/`, and update the downstream `CHANGELOG.md`.
|
|
10. After approval, replace `.minions-template/` with the new approved snapshot
|
|
and remove `.minions-template.next/`.
|
|
11. Update the base-template portion of `minion-version.md` only after the live
|
|
downstream files and vendored snapshot are aligned.
|
|
|
|
## Manual-Merge Guidance
|
|
|
|
### `MEMORY.md`
|
|
|
|
- preserve project-specific facts, constraints, environments, and operating
|
|
history
|
|
- merge new template guardrails, role definitions, and workflow rules
|
|
- if the file is later split into template-managed and project-managed sections,
|
|
restrict template upgrades to the template-managed sections
|
|
|
|
### `INIT.md`
|
|
|
|
- preserve the downstream project's onboarding framing and project-specific
|
|
references
|
|
- merge new baseline workflow expectations, role sets, and handoff rules
|
|
|
|
### `docs/operator-onboarding-checklist.md`
|
|
|
|
- preserve completed downstream decisions
|
|
- merge new template checklist items so future onboarding reviews stay current
|
|
|
|
### `minion-version.md`
|
|
|
|
- preserve the downstream version suffix
|
|
- update the base-template version only after the upgrade is actually complete
|
|
|
|
## Minimum PM Upgrade Packet
|
|
|
|
- current downstream version
|
|
- target template version
|
|
- files replaced from template
|
|
- files manually merged
|
|
- files intentionally left downstream-owned
|
|
- Operator decision needed
|
|
- follow-up owners and verification steps
|