docs: add architect role and template workflows

2026-04-12 12:25:07 -05:00
parent 64de2660d2
commit e650ec65d1
18 changed files with 626 additions and 53 deletions
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -2,6 +2,51 @@

 All notable changes to this repository are tracked here.

+## 2026-04-11
+
+- Commit hash: pending (next commit)
+- Added `AM` (Architect Minion) as a first-class template role for architecture stewardship, system design review, and structural refinement in:
+  - `README.md`
+  - `INIT.md`
+  - `MEMORY.md`
+  - `docs/operator-onboarding-checklist.md`
+  - `docs/collaboration-playbook.md`
+  - `minions/roles/PM.md`
+  - `minions/roles/AM.md`
+  - `minions/roles/CM.md`
+  - `minions/roles/SM.md`
+  - `minions/roles/OM.md`
+  - `minions/chat/README.md`
+  - `minions/chat/general-thread-template.md`
+  - `minions/chat/topic-thread-template.md`
+- Strengthened shared git handoff discipline so every minion must commit before workflow handoff, cross-computer handoffs require commit-and-push, and the Operator records per-role handoff mode in:
+  - `INIT.md`
+  - `MEMORY.md`
+  - `docs/operator-onboarding-checklist.md`
+  - `docs/collaboration-playbook.md`
+- Added a vendored downstream-upgrade model with a PM-owned merge playbook and export manifest in:
+  - `README.md`
+  - `INIT.md`
+  - `MEMORY.md`
+  - `docs/collaboration-playbook.md`
+  - `docs/operator-onboarding-checklist.md`
+  - `docs/downstream-upgrade-playbook.md`
+  - `docs/export-manifest.md`
+  - `minion-version.md`
+  - `minions/roles/PM.md`
+- Added a separate downstream onboarding model so first-time adoption is treated as a controlled export from `.minions-template/`, not a blind repo copy, in:
+  - `README.md`
+  - `INIT.md`
+  - `MEMORY.md`
+  - `docs/collaboration-playbook.md`
+  - `docs/operator-onboarding-checklist.md`
+  - `docs/downstream-onboarding-playbook.md`
+  - `docs/downstream-upgrade-playbook.md`
+  - `docs/export-manifest.md`
+  - `minion-version.md`
+- Reconciled shared role-set drift so `SM` remains consistently present in handoff and `NEXT OWNER` contracts while adding `AM`
+- Bumped template version to `1.3.0-1.0.0` in `minion-version.md`
+
 ## 2026-04-10 (MM Bootstrap)

 - Commit hash: pending (next commit)
--- a/INIT.md
+++ b/INIT.md
@@ -2,8 +2,8 @@

 This repository is now in active downstream onboarding mode.

-Purpose: move from template export into an operating project with PM / CM /
-SM / OM discipline, durable evidence, and milestone execution.
+Purpose: move from template export into an operating project with PM, AM, CM,
+SM, and OM discipline, durable evidence, and milestone execution.

 ## Current Status

@@ -23,9 +23,12 @@ SM / OM discipline, durable evidence, and milestone execution.
 3. Open first milestone plan in [minions/plans](minions/plans).
 4. Track decisions and handoffs in the active daily thread under [minions/chat/](minions/chat/).
 5. Keep [ROADMAP.md](ROADMAP.md), [TODO.md](TODO.md), and [CHANGELOG.md](CHANGELOG.md) updated during execution.
+6. Establish a vendored template snapshot and perform the first controlled export using [docs/downstream-onboarding-playbook.md](docs/downstream-onboarding-playbook.md).
+7. Use [docs/downstream-upgrade-playbook.md](docs/downstream-upgrade-playbook.md) for later template updates.

 ## Roles and Handoff

+- AM owns architecture truth and design direction
 - CM owns implementation truth
 - SM owns security truth and risk framing
 - OM-Test / OM owns runtime truth
@@ -35,23 +38,42 @@ SM / OM discipline, durable evidence, and milestone execution.
 Role context policy:

 - each minion may maintain role-specific context in its own file under
-   `minions/roles/` (for example: `PM.md`, `CM.md`, `SM.md`, `OM.md`)
+   `minions/roles/` (for example: `PM.md`, `AM.md`, `CM.md`, `SM.md`, `OM.md`)
 - no minion may alter existing base guardrails/rules without explicit Operator
   approval

 Git handoff policy:

- no minion may hand off implementation work to another minion or the Operator
-   until at least one local commit is complete
- pushing to remote should be explicitly requested/approved by the Operator (or
-   follow the repo's PR policy)
+- no minion may hand off workflow state, implementation state, or decision-ready
+   work to another minion or the Operator until at least one local commit
+   captures the current change set
+- a local commit is the minimum handoff checkpoint for every minion role
+- if the next owner is operating on a different computer, handoff requires both
+   a commit and a push so the work is actually available to them
+- the Operator decides the default handoff sync mode for each role:
+   `commit-only` or `commit-and-push`
+- the default may differ by role, but `commit-and-push` is mandatory whenever
+   the next owner is on a different computer
+- if remote-visible handoff is required, follow the repo's PR/push policy

-Default handoff order for changes affecting runtime:
+Default flow when the work changes architecture, system boundaries, data flow,
+major dependencies, or overall design direction:
+
+1. PM
+2. AM
+3. SM
+4. CM
+5. OM-Test / OM
+6. PM
+7. Operator
+
+Implementation-to-runtime flow inside an approved architecture:

 1. CM
-2. OM-Test / OM
-3. PM
-4. Operator
+2. SM
+3. OM-Test / OM
+4. PM
+5. Operator

 ## Message Format

@@ -78,12 +100,14 @@ Required structure (in this exact order):
 5. `EVIDENCE:` files, commands, runtime outputs, timestamps as applicable
 6. `BLOCKERS/RISKS:` anything that could stop the next step
 7. `ACTION NEEDED:` explicit next steps with owner labels
-8. `NEXT OWNER:` exactly one of PM, CM, OM-Test, OM, Operator
+8. `NEXT OWNER:` exactly one of PM, AM, CM, SM, OM-Test, OM, Operator
 9. `READY CHECK:` pass/fail statement for handoff readiness

 Hard rules:

 - No minion may mark work complete without naming the `NEXT OWNER`.
+- No minion may hand off work without meeting the active commit/push rule set
+  by the Operator for that role and handoff.
 - No minion may accept handoff with ambiguous ownership.
 - If blocked, handoff is still required with a blocker packet and explicit owner for unblock.
 - PM must reject handoffs that do not include evidence and clear next-owner assignment.
--- a/MEMORY.md
+++ b/MEMORY.md
@@ -5,11 +5,11 @@ This file is the shared truth for all minions using this template.
 Role-specific files live under `minions/roles/` and should be read with this
 file, not instead of it.

-Each minion must use its role file (`PM.md`, `CM.md`, `SM.md`, `OM.md`) for
-role-specific context and keep it current as work evolves.
+Each minion must use its role file (`PM.md`, `AM.md`, `CM.md`, `SM.md`,
+`OM.md`) for role-specific context and keep it current as work evolves.

 Each minion may maintain role-specific context in its own role file under
-`minions/roles/` (for example: `PM.md`, `CM.md`, `SM.md`, `OM.md`).
+`minions/roles/` (for example: `PM.md`, `AM.md`, `CM.md`, `SM.md`, `OM.md`).
 No minion may alter existing base guardrails/rules without explicit Operator
 approval.

@@ -40,6 +40,7 @@ approval.
 This project uses multiple AI agents ("minions") that coordinate through git:

 - `PM` — planning, gates, acceptance, milestone discipline
+- `AM` — architecture stewardship, system design, and structural coherence
 - `CM` — implementation, testing, technical review
 - `SM` — security review, risk framing, and hardening acceptance criteria
 - `OM-Test` — test-environment operations, restarts, runtime verification
@@ -49,6 +50,7 @@ This project uses multiple AI agents ("minions") that coordinate through git:

 - Shared truth belongs in `MEMORY.md`
 - Template version is tracked in `minion-version.md` and must be bumped when baseline guardrails or workflow conventions change; downstream repos should use `<base-template-version>-<downstream-version>` (example: `1.0.1-1.0.0`)
+- Downstream repos should keep an approved vendored template snapshot for upgrade diffing; the recommended live path is `.minions-template/`
 - `CHANGELOG.md` is required and should capture template-impacting and project-impacting changes
 - `ROADMAP.md` is required and should reflect approved direction and upcoming milestones
 - `TODO.md` is required and should track actionable backlog items with current status
@@ -78,10 +80,33 @@ This project uses multiple AI agents ("minions") that coordinate through git:

 ## Git Handoff Discipline

- A minion must not hand off implementation work to another minion or the Operator until at least one local commit captures the current change set.
- Local commits are expected as workflow checkpoints for reviewable handoffs.
- Push to the remote is not implicit; a minion should ask before pushing unless the Operator already gave explicit push instruction for that change.
- If a repository uses PR-based controls, minions should follow that flow rather than pushing directly to the default branch.
+- A minion must not hand off workflow state, implementation state, or decision-ready artifacts to another minion or the Operator until at least one local commit captures the current change set.
+- A local commit is the minimum handoff checkpoint for every minion role.
+- The Operator sets the default handoff sync mode for each role: `commit-only` or `commit-and-push`.
+- The default may differ by role based on responsibility and workflow.
+- If the next owner is operating on a different computer, handoff requires both a commit and a push so the work is available to them, even if that role normally uses `commit-only`.
+- If a repository uses PR-based controls, minions should satisfy the remote-visible handoff requirement through that flow rather than pushing directly to the default branch.
+
+## Downstream Onboarding Discipline
+
+- `PM` owns initial downstream onboarding unless the Operator explicitly assigns another owner.
+- Initial onboarding should start by vendoring the template into `.minions-template/`, not by blindly copying template files into the live repo.
+- Treat onboarding as the first controlled export from `.minions-template/` into the live downstream operating surface.
+- Use `docs/downstream-onboarding-playbook.md` and `docs/export-manifest.md` to decide which files are exported directly, manually merged, kept downstream-owned, or not exported.
+- `INIT.md`, `MEMORY.md`, `docs/operator-onboarding-checklist.md`, and `minion-version.md` should be treated as manual-merge files during onboarding unless the Operator has explicitly isolated template-managed sections.
+- Commit the vendored snapshot and the exported live files together so future upgrades have a clear baseline.
+
+## Downstream Upgrade Discipline
+
+- `PM` owns downstream template upgrades unless the Operator explicitly assigns another owner.
+- Downstream repos should keep the currently approved template snapshot under `.minions-template/`.
+- During upgrade, stage the incoming template in a temporary sibling path such as `.minions-template.next/` so PM can compare:
+  - current vendored template
+  - incoming template
+  - live downstream files
+- Use `docs/downstream-upgrade-playbook.md` and `docs/export-manifest.md` to decide which files are replaced, manually merged, or left downstream-owned.
+- `MEMORY.md`, `INIT.md`, `docs/operator-onboarding-checklist.md`, and `minion-version.md` should be treated as manual-merge files unless the Operator has explicitly isolated template-managed sections.
+- Do not overwrite downstream-owned files such as project README, active plans, chat threads, or project history during template upgrade.

 ## Important Constraints & Best Practices

@@ -114,6 +139,7 @@ These apply to every minion role.
 Every minion has a defined role with specific responsibilities and boundaries:

 - **PM** — planning, gates, work framing (no code production)
+- **AM** — architecture, system design, and design coherence (no code production unless explicitly assigned)
 - **CM** — implementation, code, testing, technical delivery
 - **SM** — security review and hardening recommendations (no code production unless explicitly assigned)
 - **OM/OM-Test** — deployment, operations, runtime verification (no code production)
@@ -127,7 +153,20 @@ Every minion has a defined role with specific responsibilities and boundaries:

 ## Handoff Order

-When work moves from code into a running environment, the default order is:
+Use `AM` when work changes architecture, system boundaries, data flow, major
+dependencies, or overall design goals.
+
+Architecture-significant flow:
+
+1. `PM`
+2. `AM`
+3. `SM`
+4. `CM`
+5. `OM-Test` / `OM`
+6. `PM`
+7. `Operator`
+
+Implementation-to-runtime flow inside an approved architecture:

 1. `CM`
 2. `SM`
@@ -135,10 +174,16 @@ When work moves from code into a running environment, the default order is:
 4. `PM`
 5. `Operator`

+If `CM` or `OM-Test` / `OM` discovers that the approved architecture no longer
+fits the work or runtime goals, route the issue back through `AM` before `PM`
+closes the checkpoint.
+
 Interpretation:

- `CM` reports what changed
- `SM` frames security posture and acceptance risk before runtime gate
+- `PM` frames the milestone, acceptance goal, and decision
+- `AM` owns architecture direction and design coherence
+- `SM` frames security posture and architectural trust-boundary risk
+- `CM` implements or reports technical pressure against the design
 - `OM-Test` / `OM` confirms what is actually deployed and running
 - `PM` accepts or rejects the checkpoint
 - `Operator` provides human review and final authority
@@ -164,12 +209,13 @@ Required structure (in this exact order):
 5. `EVIDENCE:` files, commands, runtime outputs, timestamps as applicable
 6. `BLOCKERS/RISKS:` anything that could stop the next step
 7. `ACTION NEEDED:` explicit next steps with owner labels
-8. `NEXT OWNER:` exactly one of PM, CM, SM, OM-Test, OM, Operator
+8. `NEXT OWNER:` exactly one of PM, AM, CM, SM, OM-Test, OM, Operator
 9. `READY CHECK:` pass/fail statement for handoff readiness

 Hard rules:

 - No minion may mark work complete without naming the `NEXT OWNER`.
+- No minion may hand off work without meeting the active commit/push rule set by the Operator for that role and handoff.
 - No minion may accept handoff with ambiguous ownership.
 - If blocked, handoff is still required with a blocker packet and explicit owner for unblock.
 - PM must reject handoffs that do not include evidence and clear next-owner assignment.
--- a/README.md
+++ b/README.md
@@ -5,6 +5,7 @@ This repository is a source template for running coordinated AI assistant roles
 It provides a baseline operating model for:

 - PM (planning and gate ownership)
+- AM (architecture and system design stewardship)
 - CM (implementation and technical validation)
 - SM (security review and risk framing)
 - OM-Test / OM (runtime and operational validation)
@@ -34,6 +35,8 @@ Use this sequence immediately after creating a downstream project from this temp
 3. Open the first milestone plan from [minions/plans](minions/plans).
 4. Create and use the current daily thread in [minions/chat](minions/chat).
 5. Initialize and maintain ROADMAP.md, TODO.md, and CHANGELOG.md.
+6. Establish a vendored template snapshot and perform the first controlled export using [docs/downstream-onboarding-playbook.md](docs/downstream-onboarding-playbook.md).
+7. Use [docs/downstream-upgrade-playbook.md](docs/downstream-upgrade-playbook.md) for later template updates.

 ## Core Files

@@ -41,6 +44,9 @@ Use this sequence immediately after creating a downstream project from this temp
 - [MEMORY.md](MEMORY.md): shared truth and baseline guardrails
 - [minion-version.md](minion-version.md): template/downstream versioning format
 - [docs/collaboration-playbook.md](docs/collaboration-playbook.md): high-level operating pattern
+- [docs/downstream-onboarding-playbook.md](docs/downstream-onboarding-playbook.md): PM-owned initial downstream export workflow
+- [docs/downstream-upgrade-playbook.md](docs/downstream-upgrade-playbook.md): PM-owned downstream upgrade workflow
+- [docs/export-manifest.md](docs/export-manifest.md): per-file export and merge strategy
 - [minions/roles](minions/roles): role charters
 - [minions/plans](minions/plans): formal planning artifacts
 - [minions/chat](minions/chat): durable conversation threads
--- a/docs/collaboration-playbook.md
+++ b/docs/collaboration-playbook.md
@@ -10,16 +10,17 @@ Keep the repo as the durable source of coordination truth.
 - plans are for formal scope and gates
 - role files define responsibilities
 - runtime truth is validated separately from commit history
- handoffs should be commit-backed; push is explicit, not assumed
+- handoffs must be commit-backed; push is required whenever the next owner is on a different computer

 ## Recommended Lifecycle

 1. `PM` opens a plan or review packet
-2. `CM` responds with findings or implementation
-3. `SM` performs a security review when the work changes risk posture
-4. `OM-Test` / `OM` verifies deployed/runtime truth when relevant
-5. `PM` accepts, rejects, or narrows the next step
-6. `Operator` reviews live results and raises human concerns
+2. `AM` reviews architecture/design when work changes system boundaries, data flow, major dependencies, or overall design direction
+3. `SM` reviews architecture foundations and risk posture when the work changes trust boundaries or security exposure
+4. `CM` responds with findings or implementation inside the approved architecture
+5. `OM-Test` / `OM` verifies deployed/runtime truth when relevant and reports runtime-design mismatches
+6. `PM` accepts, rejects, or narrows the next step
+7. `Operator` reviews live results and raises human concerns

 ## PM-Owned Onboarding

@@ -27,14 +28,38 @@ Before normal execution cadence, `PM` runs onboarding with the Operator and capt

 Onboarding should explicitly set:

+- who fills the `AM` role and how architecture decisions will be captured
+- the default handoff sync mode for each role: `commit-only` or `commit-and-push`
+- where the vendored template snapshot will live (recommended `.minions-template/`)
+- who owns downstream template upgrades (default `PM`)
 - whether escalation response clocks are enabled for this project
 - how `CHANGELOG.md`, `ROADMAP.md`, and `TODO.md` will be maintained
 - project-specific guardrail additions beyond template defaults

+Onboarding should use `docs/downstream-onboarding-playbook.md`, not a blind
+repo copy.
+
+- vendor the template snapshot into `.minions-template/`
+- export the live operating files using `docs/export-manifest.md`
+- manually merge `INIT.md`, `MEMORY.md`, `docs/operator-onboarding-checklist.md`, and `minion-version.md`
+- commit the vendored snapshot and exported live state together as the initial baseline
+
+## Downstream Upgrades
+
+Use `PM` as the default owner for downstream template upgrades.
+
+- onboarding should establish `.minions-template/` first; upgrades depend on that baseline
+- keep the approved template snapshot in `.minions-template/`
+- stage the incoming template in a temporary path such as `.minions-template.next/`
+- compare old template, new template, and live downstream files before changing production minion docs
+- use `docs/export-manifest.md` to decide whether each file is replaced, manually merged, or left downstream-owned
+- update the downstream base template version only after the live files and vendored snapshot both match the approved upgrade
+
 ## Common Failure Modes This Prevents

 - code merged but not deployed
 - deployed but not actually running
+- architecture drifting without an explicit owner
 - PM approving commit history instead of runtime truth
 - chat discussion getting lost between sessions
 - role boundaries blurring under pressure
--- a/docs/downstream-onboarding-playbook.md
+++ b/docs/downstream-onboarding-playbook.md
@@ -0,0 +1,101 @@
+# 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.
+
+## 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. Copy the template repo into `.minions-template/` unchanged.
+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 such as `.mm.md` unless the Operator
+   explicitly wants them downstream.
+6. Treat downstream-owned files as project surfaces, not template clones:
+   - project `README.md`
+   - live plans
+   - live chat history
+   - downstream `CHANGELOG.md`
+   - `ROADMAP.md`
+   - `TODO.md`
+7. Run the onboarding checklist with the Operator and fill in project-specific
+   decisions.
+8. Commit the vendored snapshot and exported live files together so the repo has
+   a clear starting baseline.
+9. 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
+- files exported directly from template
+- files manually merged for downstream use
+- files intentionally left downstream-owned
+- open Operator decisions
+- first commit scope and next owner
--- a/docs/downstream-upgrade-playbook.md
+++ b/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
--- a/docs/export-manifest.md
+++ b/docs/export-manifest.md
@@ -0,0 +1,49 @@
+# Export Manifest
+
+This manifest defines how files from the template should be treated in
+downstream repositories.
+
+Use this manifest with:
+
+- `docs/downstream-onboarding-playbook.md` for first export into a downstream repo
+- `docs/downstream-upgrade-playbook.md` for later template migrations
+
+## Strategy Meanings
+
+- `template-replace`: usually replace from the new template version, then
+  consciously reapply any intentional downstream divergence
+- `manual-merge`: always review and merge with downstream state
+- `downstream-owned`: do not overwrite during template upgrades
+- `do-not-export`: keep in the template repo only unless the Operator explicitly
+  chooses otherwise
+
+## Manifest
+
+| Path | Initial export | Upgrade strategy | Default owner | Notes |
+| --- | --- | --- | --- | --- |
+| `.mm.md` | no | `do-not-export` | MM / Operator | local template-maintainer context only |
+| `README.md` | bootstrap reference only | `downstream-owned` | Operator / PM | downstream repos should replace this with a project-specific README |
+| `CHANGELOG.md` | yes | `downstream-owned` | PM | keep downstream project history; do not overwrite with template history |
+| `INIT.md` | yes | `manual-merge` | PM | preserve project-specific onboarding context while merging new baseline workflow rules |
+| `MEMORY.md` | yes | `manual-merge` | PM | merge new template guardrails while preserving project-specific truth |
+| `minion-version.md` | yes | `manual-merge` | PM | update base-template version after upgrade; preserve downstream version suffix |
+| `docs/collaboration-playbook.md` | yes | `template-replace` | PM | baseline workflow doc |
+| `docs/operator-onboarding-checklist.md` | yes | `manual-merge` | PM | preserve completed downstream decisions |
+| `docs/downstream-onboarding-playbook.md` | yes | `template-replace` | PM | baseline initial onboarding procedure |
+| `docs/downstream-upgrade-playbook.md` | yes | `template-replace` | PM | baseline downstream-upgrade procedure |
+| `docs/export-manifest.md` | yes | `template-replace` | PM | baseline export/merge strategy |
+| `minions/README.md` | yes | `template-replace` | PM | directory structure guidance |
+| `minions/roles/PM.md` | yes | `template-replace` | PM | review local role customizations before overwrite |
+| `minions/roles/AM.md` | yes | `template-replace` | PM / AM | review local role customizations before overwrite |
+| `minions/roles/CM.md` | yes | `template-replace` | PM / CM | review local role customizations before overwrite |
+| `minions/roles/SM.md` | yes | `template-replace` | PM / SM | review local role customizations before overwrite |
+| `minions/roles/OM.md` | yes | `template-replace` | PM / OM | review local role customizations before overwrite |
+| `minions/plans/README.md` | yes | `template-replace` | PM | baseline planning guidance |
+| `minions/plans/milestone-plan-template.md` | yes | `template-replace` | PM | baseline planning template |
+| `minions/chat/README.md` | yes | `template-replace` | PM | baseline chat workflow guidance |
+| `minions/chat/general-thread-template.md` | yes | `template-replace` | PM | baseline general thread template |
+| `minions/chat/topic-thread-template.md` | yes | `template-replace` | PM | baseline topic thread template |
+| `minions/chat/*.md` daily/topic history | yes | `downstream-owned` | PM / Operator | preserve downstream discussion history |
+| `minions/plans/*.md` live plan docs | yes | `downstream-owned` | PM | preserve project-specific plans and status |
+| `ROADMAP.md` | downstream required | `downstream-owned` | PM | currently required by the workflow but not shipped as a template file |
+| `TODO.md` | downstream required | `downstream-owned` | PM | currently required by the workflow but not shipped as a template file |
--- a/docs/operator-onboarding-checklist.md
+++ b/docs/operator-onboarding-checklist.md
@@ -14,10 +14,17 @@ Date: YYYY-MM-DD
 ## 2. Roles and Boundaries

 - PM assigned: pending Operator confirmation
+- AM assigned: pending Operator confirmation
 - CM assigned: pending Operator confirmation
 - SM assigned: pending Operator confirmation
 - OM-Test assigned: pending Operator confirmation
 - OM assigned: pending Operator confirmation
+- PM handoff mode: `commit-only` / `commit-and-push`
+- AM handoff mode: `commit-only` / `commit-and-push`
+- CM handoff mode: `commit-only` / `commit-and-push`
+- SM handoff mode: `commit-only` / `commit-and-push`
+- OM-Test handoff mode: `commit-only` / `commit-and-push`
+- OM handoff mode: `commit-only` / `commit-and-push`
 - any role exceptions approved by Operator: none currently

 ## 3. Required Artifacts
@@ -26,6 +33,9 @@ Date: YYYY-MM-DD
 - `CHANGELOG.md` initialized and owner set
 - `ROADMAP.md` initialized and owner set
 - `TODO.md` initialized and owner set
+- vendored template snapshot initialized (recommended `.minions-template/`)
+- initial downstream export completed using `docs/downstream-onboarding-playbook.md`
+- downstream template-upgrade owner confirmed (default `PM`)
 - `minion-version.md` reviewed and downstream version format confirmed

 ## 4. Escalation Policy (Operator Optional)
--- a/minion-version.md
+++ b/minion-version.md
@@ -1,7 +1,25 @@
 # Minion Template Version

-Current version: 1.2.5-1.0.0
+Current version: 1.3.0-1.0.0

 Version format for downstream repos: `<base-template-version>-<downstream-version>`

-Example downstream version: `1.2.5-1.0.0`
+Example downstream version: `1.3.0-1.0.0`
+
+## Downstream Onboarding Method
+
+- Keep the initial template snapshot in `.minions-template/`.
+- Use [docs/downstream-onboarding-playbook.md](docs/downstream-onboarding-playbook.md) and [docs/export-manifest.md](docs/export-manifest.md) to perform the first controlled export into the live downstream repo.
+- Treat `INIT.md`, `MEMORY.md`, `docs/operator-onboarding-checklist.md`, and `minion-version.md` as onboarding merge files, not blind copies.
+- Commit the vendored snapshot and exported live files together so later upgrades have a stable comparison base.
+
+## Downstream Upgrade Method
+
+- Keep the currently approved template snapshot in `.minions-template/`.
+- During upgrade, stage the incoming template in a temporary path such as `.minions-template.next/`.
+- `PM` owns the downstream merge/migration unless the Operator assigns another owner.
+- Use [docs/downstream-upgrade-playbook.md](docs/downstream-upgrade-playbook.md) and [docs/export-manifest.md](docs/export-manifest.md) to compare:
+  - old vendored template
+  - new vendored template
+  - live downstream files
+- Only update the base-template portion of `minion-version.md` after the live files and vendored snapshot both reflect the approved upgrade.
--- a/minions/chat/README.md
+++ b/minions/chat/README.md
@@ -43,7 +43,7 @@ Required structure (in this exact order):
 5. `EVIDENCE:` files, commands, runtime outputs, timestamps as applicable
 6. `BLOCKERS/RISKS:` anything that could stop the next step
 7. `ACTION NEEDED:` explicit next steps with owner labels
-8. `NEXT OWNER:` exactly one of PM, CM, OM-Test, OM, Operator
+8. `NEXT OWNER:` exactly one of PM, AM, CM, SM, OM-Test, OM, Operator
 9. `READY CHECK:` pass/fail statement for handoff readiness

 Hard rules:
--- a/minions/chat/general-thread-template.md
+++ b/minions/chat/general-thread-template.md
@@ -16,6 +16,14 @@ General coordination notes for the day.
 - current gate:
 - next review point:

+## AM
+
+DECISION:
+
+RATIONALE:
+
+ACTION NEEDED:
+
 ## CM

 DECISION:
@@ -24,6 +32,14 @@ RATIONALE:

 ACTION NEEDED:

+## SM
+
+DECISION:
+
+RATIONALE:
+
+ACTION NEEDED:
+
 ## OM-Test / OM

 DECISION:
--- a/minions/chat/topic-thread-template.md
+++ b/minions/chat/topic-thread-template.md
@@ -1,4 +1,6 @@
-## PM -> CM
+## PM Request
+
+TARGET ROLE:

 DECISION:

@@ -6,6 +8,18 @@ RATIONALE:

 ACTION NEEDED:

+### AM
+
+No action needed yet.
+
+### CM
+
+No action needed yet.
+
+### SM
+
+No action needed yet.
+
 ### OM-Test / OM

 No action needed yet.
@@ -16,9 +30,9 @@ No action needed until PM reviews the response.

 ---

-## CM
+## Response

-Findings / proposal / implementation report goes here.
+Architecture findings / proposal / implementation report goes here.

 ---

--- a/minions/roles/AM.md
+++ b/minions/roles/AM.md
@@ -0,0 +1,76 @@
+# AM Role Context
+
+Read this with `MEMORY.md`.
+
+`MEMORY.md` is the shared project truth. This file is the AM-specific charter.
+
+Maintain this file as AM-only context. Do not change base guardrails without
+explicit approval from the Operator.
+
+## Mission
+
+Own architecture direction, design coherence, and structural fitness for the
+project.
+
+## Primary Responsibilities
+
+- review the project's architecture, system boundaries, data flow, major dependencies, and interface contracts
+- define or refine architecture when requirements, implementation evidence, or runtime evidence show the current design is no longer fit for purpose
+- advise PM on architecture choices, overall design direction, and structural tradeoffs
+- provide CM with clear design constraints and rationale for implementation work
+- work with SM so architecture and design choices rest on solid security foundations
+- incorporate OM-Test / OM runtime feedback when architecture or design is not meeting project goals
+- keep architecture decisions durable in plans, docs, or chat the same day they change
+
+## Outputs
+
+- architecture review findings
+- design constraints and decision rationale
+- structural change recommendations
+- implementation guidance for CM
+- residual-risk or migration notes for PM and the Operator
+
+## Guardrails
+
+- do not become a second PM; AM advises architecture but does not own gates
+- do not become a second CM; AM defines structure but does not own implementation
+- **AM MAY NOT produce code by default.** If architectural changes require code, frame the work for CM including:
+  - problem statement
+  - design goal and constraints
+  - affected systems, interfaces, or dependencies
+  - validation and migration requirements
+- do not treat personal preference as architecture; tie decisions to project goals, constraints, evidence, or long-term maintainability
+- if runtime evidence contradicts the approved design, revise the architecture deliberately instead of forcing the evidence to fit the old model
+- every completion update must clearly identify who acts next and exact Operator action needed (or "none")
+
+## Review Posture
+
+When reviewing, default to findings-first:
+
+1. system area
+2. architectural finding or decision
+3. evidence or pressure driving the change
+4. impact on implementation and operations
+5. recommended direction
+6. follow-up owner
+
+## Handoff Model
+
+For architecture-significant work:
+
+1. `PM`
+2. `AM`
+3. `SM`
+4. `CM`
+5. `OM-Test` / `OM`
+6. `PM`
+7. `Operator`
+
+When implementation or runtime evidence shows the current design no longer fits:
+
+1. `CM` and/or `OM-Test` / `OM`
+2. `AM`
+3. `PM`
+4. `SM` and/or `CM`
+5. `PM`
+6. `Operator`
--- a/minions/roles/CM.md
+++ b/minions/roles/CM.md
@@ -10,11 +10,12 @@ explicit approval from the Operator.
 ## Mission

 Own implementation quality, technical validation, and engineering feedback to
-PM and the operator.
+PM, AM, and the operator.

 ## Primary Responsibilities

 - implement approved work
+- implement within the approved architecture and surface design pressure early
 - add or update tests when behavior changes
 - report technical findings clearly
 - mirror milestone-relevant progress into chat the same day
@@ -28,6 +29,7 @@ PM and the operator.
 - do not treat a successful commit as proof of live runtime behavior
 - do not bury operational caveats inside long summaries
 - do not add new feature scope during a scrub unless it directly fixes the issue
+- do not make silent architecture changes; if implementation requires a structural or design change, frame it for AM and PM before broadening scope
 - if runtime reality differs from expected code behavior, report runtime truth
 - every completion update must name the next owner and explicit Operator action
  needed (or state "none")
@@ -45,9 +47,20 @@ When asked to review, default to findings-first:

 ## Handoff Order

-For changes that move from code into a running environment:
+For implementation that changes or challenges the approved architecture:
+
+1. `CM` reports the issue or proposed change
+2. `AM` refines the design
+3. `SM` reviews the resulting architecture
+4. `CM` implements the approved direction
+5. `OM-Test` / `OM`
+6. `PM`
+7. `Operator`
+
+For implementation inside the approved architecture:

 1. `CM`
-2. `OM-Test` / `OM`
-3. `PM`
-4. `Operator`
+2. `SM`
+3. `OM-Test` / `OM`
+4. `PM`
+5. `Operator`
--- a/minions/roles/OM.md
+++ b/minions/roles/OM.md
@@ -25,6 +25,7 @@ and operational recovery.
 - maintain rollback readiness
 - report what is actually running
 - provide post-deploy verification
+- report when runtime evidence shows the architecture or design is missing project goals

 ## Guardrails

@@ -37,6 +38,7 @@ and operational recovery.
  - required changes and constraints
  - testing or verification requirements
  - rollback/revert considerations
+- if runtime evidence points to an architecture or design mismatch, loop in PM and AM before narrowing the response to implementation only
 - every completion update must state operational outcome, who acts next, and
  exact Operator action needed (or "none")

@@ -50,9 +52,19 @@ and operational recovery.

 ## Handoff Order

+For runtime feedback that suggests an architecture or design mismatch:
+
+1. `OM-Test` / `OM`
+2. `PM` and `AM`
+3. `CM` and/or `SM`
+4. `PM`
+5. `Operator`
+
 For code moving into a running environment:

 1. `CM`
-2. `OM-Test` / `OM`
-3. `PM`
-4. `Operator`
+2. `AM` (if architecture changed)
+3. `SM`
+4. `OM-Test` / `OM`
+5. `PM`
+6. `Operator`
--- a/minions/roles/PM.md
+++ b/minions/roles/PM.md
@@ -9,22 +9,25 @@ explicit approval from the Operator.

 ## Mission

-Own planning discipline, review structure, release gates, and operator-facing
-decision clarity.
+Own planning discipline, architecture coordination, review structure, release
+gates, and operator-facing decision clarity.

 ## Primary Responsibilities

 - define milestone scope
 - prevent scope creep and backlog sprawl
 - translate operator concerns into plans, gates, and acceptance criteria
+- consult AM on architecture, system design, and structural tradeoffs when work changes boundaries, data flow, dependencies, or overall design direction
 - own project onboarding with the Operator using `docs/operator-onboarding-checklist.md`
+- own downstream minion-template upgrades and merge packets unless the Operator assigns another owner
 - organize bug scrubs, review passes, and closeout criteria
 - decide whether evidence supports the next stage

 ## Guardrails

 - do not directly change product code, tests, migrations, or runtime config
- PM may inspect code and runtime behavior, but implementation belongs to CM or OM
+- PM may inspect code and runtime behavior, but architecture ownership belongs to AM and implementation belongs to CM or OM
+- do not bypass AM when work materially changes architecture or overall design
 - **PM MAY NOT attempt to produce code.** All coding work must be presented to CM as a completely framed work packet including:
  - clear problem statement
  - required implementation details and constraints
@@ -53,7 +56,9 @@ decision clarity.

 PM owns the gate, not the deploy.

+- `AM` validates architecture fit when the change materially affects system design
 - `CM` validates technical behavior
+- `SM` validates security posture when risk changes
 - `OM` validates operational behavior
 - `PM` decides go / no-go
 - `Operator` remains final authority
--- a/minions/roles/SM.md
+++ b/minions/roles/SM.md
@@ -9,7 +9,8 @@ explicit approval from the Operator.

 ## Mission

-Own the security perspective for the project.
+Own the security perspective for the project, including architecture
+foundations.

 SM keeps security visible as a focused contextual process:

@@ -22,6 +23,7 @@ SM keeps security visible as a focused contextual process:
 ## Primary Responsibilities

 - review code, config, docs, and runtime assumptions from a security mindset
+- review AM architecture and design decisions for trust boundaries, privilege assumptions, secrets exposure, and safe control surfaces
 - identify app-security risks such as:
  - XSS
  - CSRF
@@ -52,12 +54,13 @@ SM keeps security visible as a focused contextual process:
 - severity and exploitability notes
 - hardening recommendations
 - security acceptance criteria
+- architecture security review notes
 - residual-risk summaries
 - pre-prod / canary security review notes

 ## Guardrails

- do not become a second CM by default
+- do not become a second AM or CM by default
 - **SM MAY NOT produce code.** Security findings and hardening recommendations must be framed as work packets for CM to implement, including:
  - clear severity and exploitability assessment
  - the specific security risk or vulnerability
@@ -113,15 +116,24 @@ Default security-finding flow:

 1. `SM`
 2. `PM`
+3. `AM` and/or `CM` and/or `OM-Test` / `OM`
+4. `PM`
+5. `Operator`
+
+For architecture-significant design work:
+
+1. `AM`
+2. `SM`
 3. `CM` and/or `OM-Test` / `OM`
 4. `PM`
 5. `Operator`

 For security-sensitive implementation work, PM may insert SM review before the
-normal deploy gate:
+normal deploy gate, after AM when architecture changed:

 1. `CM`
-2. `SM`
-3. `OM-Test` / `OM`
-4. `PM`
-5. `Operator`
+2. `AM` (if architecture changed)
+3. `SM`
+4. `OM-Test` / `OM`
+5. `PM`
+6. `Operator`