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

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