docs: add architect role and template workflows

docs/downstream-upgrade-playbook.md

@@ -0,0 +1,101 @@
+# 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.
+
+## 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 template snapshot in `.minions-template/` if it is
+   not already present.
+3. Import the incoming template version into `.minions-template.next/`.
+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 the active chat thread and 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