docs: refine downstream onboarding workflow

2026-04-12 13:56:28 -05:00
parent e650ec65d1
commit 7dd35f3975
11 changed files with 93 additions and 32 deletions
--- a/.mm.md
+++ b/.mm.md
@@ -167,3 +167,10 @@ MM should optimize for continuity, low-friction decision-making, and explicit re
  - `MEMORY.md` still references `REQUIREMENTS.md`, which is absent and not defined in onboarding
 - created `minions/chat/2026-04-10.md` for the durable MM bootstrap announcement required by the shared chat workflow
 - active MM recommendation: fix the shared handoff-contract drift first, then decide whether `ROADMAP.md`, `TODO.md`, and `REQUIREMENTS.md` should exist in the template or only be required during downstream onboarding
+
+### 2026-04-12
+
+- decided that `.minions-template/` should be an export-ready downstream snapshot, not a full clone of the template repo
+- `do-not-export` now means excluded from both downstream live files and the vendored `.minions-template/` snapshot unless the Operator explicitly chooses otherwise
+- `.mm.md` remains template-maintainer-only and should not travel into downstream repos by default
+- `REQUIREMENTS.md` is not currently part of the downstream onboarding model; the shared required-doc contract now uses `README.md`, `ROADMAP.md`, and `TODO.md` instead
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -2,6 +2,28 @@

 All notable changes to this repository are tracked here.

+## 2026-04-12
+
+- Commit hash: pending (next commit)
+- Corrected the downstream onboarding/export model so `.minions-template/` is an export-ready snapshot rather than a raw 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`
+- Clarified that downstream snapshots must exclude Git metadata and `do-not-export` files such as `.mm.md`
+- Removed `REQUIREMENTS.md` from the shared required-documentation contract and aligned the baseline around `README.md`, `ROADMAP.md`, and `TODO.md` in:
+  - `MEMORY.md`
+  - `.mm.md`
+- Reordered the initial onboarding sequence so controlled export happens before downstream checklist completion in:
+  - `README.md`
+  - `INIT.md`
+- Bumped template version to `1.3.1-1.0.0` in `minion-version.md`
+
 ## 2026-04-11

 - Commit hash: pending (next commit)
--- a/INIT.md
+++ b/INIT.md
@@ -14,16 +14,16 @@ SM, and OM discipline, durable evidence, and milestone execution.

 ## Immediate Startup Sequence

-1. Run and complete [docs/operator-onboarding-checklist.md](docs/operator-onboarding-checklist.md) with the Operator.
-2. Finalize project-specific sections in [MEMORY.md](MEMORY.md):
+1. Establish a filtered vendored template snapshot and perform the first controlled export using [docs/downstream-onboarding-playbook.md](docs/downstream-onboarding-playbook.md).
+2. Run and complete [docs/operator-onboarding-checklist.md](docs/operator-onboarding-checklist.md) with the Operator.
+3. Finalize project-specific sections in [MEMORY.md](MEMORY.md):
   - project purpose
   - architecture
   - environments
   - safety constraints
-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).
+4. Open first milestone plan in [minions/plans](minions/plans).
+5. Track decisions and handoffs in the active daily thread under [minions/chat/](minions/chat/).
+6. Keep [ROADMAP.md](ROADMAP.md), [TODO.md](TODO.md), and [CHANGELOG.md](CHANGELOG.md) updated during execution.
 7. Use [docs/downstream-upgrade-playbook.md](docs/downstream-upgrade-playbook.md) for later template updates.

 ## Roles and Handoff
--- a/MEMORY.md
+++ b/MEMORY.md
@@ -51,6 +51,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/`
+- The vendored snapshot should be an export-ready copy of the template, not a full Git clone; exclude `.git/` and `do-not-export` files such as `.mm.md`
 - `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
@@ -74,7 +75,7 @@ This project uses multiple AI agents ("minions") that coordinate through git:

 - Any change to a playbook, role, inventory, or variable file must be reflected in the relevant README.md or docs/ entry
 - Any new feature, module, or workflow must include corresponding documentation before the commit is made
- `README.md`, `TODO.md`, and `REQUIREMENTS.md` must be reviewed and updated when scope, status, or design changes
+- `README.md`, `ROADMAP.md`, and `TODO.md` must be reviewed and updated when scope, status, or design changes
 - AI agents must treat documentation updates as a required part of every task — not optional follow-up
 - If a documented item is removed or renamed, all references across all docs must be updated in the same commit

@@ -90,7 +91,7 @@ This project uses multiple AI agents ("minions") that coordinate through git:
 ## 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.
+- Initial onboarding should start by vendoring an export-ready template snapshot 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.
@@ -99,7 +100,7 @@ This project uses multiple AI agents ("minions") that coordinate through git:
 ## 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/`.
+- Downstream repos should keep the currently approved export-ready 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
--- a/README.md
+++ b/README.md
@@ -30,12 +30,12 @@ This template exists to make multi-agent coordination explicit, durable, and rev

 Use this sequence immediately after creating a downstream project from this template:

-1. Complete [docs/operator-onboarding-checklist.md](docs/operator-onboarding-checklist.md) with the Operator.
-2. Finalize project-specific sections in [MEMORY.md](MEMORY.md).
-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).
+1. Establish a filtered vendored template snapshot and perform the first controlled export using [docs/downstream-onboarding-playbook.md](docs/downstream-onboarding-playbook.md).
+2. Complete [docs/operator-onboarding-checklist.md](docs/operator-onboarding-checklist.md) with the Operator.
+3. Finalize project-specific sections in [MEMORY.md](MEMORY.md).
+4. Open the first milestone plan from [minions/plans](minions/plans).
+5. Create and use the current daily thread in [minions/chat](minions/chat).
+6. Initialize and maintain ROADMAP.md, TODO.md, and CHANGELOG.md.
 7. Use [docs/downstream-upgrade-playbook.md](docs/downstream-upgrade-playbook.md) for later template updates.

 ## Core Files
--- a/docs/collaboration-playbook.md
+++ b/docs/collaboration-playbook.md
@@ -39,7 +39,7 @@ Onboarding should explicitly set:
 Onboarding should use `docs/downstream-onboarding-playbook.md`, not a blind
 repo copy.

- vendor the template snapshot into `.minions-template/`
+- vendor an export-ready template snapshot into `.minions-template/` with `.git/` and `do-not-export` files excluded
 - 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
@@ -49,8 +49,8 @@ repo copy.
 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/`
+- keep the approved export-ready template snapshot in `.minions-template/`
+- stage the incoming export-ready 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
--- a/docs/downstream-onboarding-playbook.md
+++ b/docs/downstream-onboarding-playbook.md
@@ -27,6 +27,14 @@ This gives AI agents a durable provenance model:
 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
@@ -40,7 +48,10 @@ upgrade candidates.

 ## Onboarding Workflow

-1. Copy the template repo into `.minions-template/` unchanged.
+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.
@@ -50,8 +61,8 @@ upgrade candidates.
   - `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.
+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
@@ -94,6 +105,7 @@ upgrade candidates.

 - 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
--- a/docs/downstream-upgrade-playbook.md
+++ b/docs/downstream-upgrade-playbook.md
@@ -25,6 +25,12 @@ 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
@@ -41,9 +47,10 @@ run the onboarding playbook first.

 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/`.
+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:
--- a/docs/export-manifest.md
+++ b/docs/export-manifest.md
@@ -14,8 +14,19 @@ Use this manifest with:
  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
+- `do-not-export`: keep out of downstream live files and out of the vendored
+  `.minions-template/` snapshot unless the Operator explicitly chooses
+  otherwise
+
+## Vendored Snapshot Rule
+
+`.minions-template/` is an export-ready snapshot, not a full clone of the
+template repo.
+
+- exclude `.git/`
+- exclude all `do-not-export` files
+- keep only the files needed to onboard and later upgrade downstream minion
+  workflow

 ## Manifest

--- a/docs/operator-onboarding-checklist.md
+++ b/docs/operator-onboarding-checklist.md
@@ -33,7 +33,7 @@ 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/`)
+- vendored template snapshot initialized (recommended `.minions-template/`; exclude `.git/` and `do-not-export` files)
 - 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
--- a/minion-version.md
+++ b/minion-version.md
@@ -1,22 +1,23 @@
 # Minion Template Version

-Current version: 1.3.0-1.0.0
+Current version: 1.3.1-1.0.0

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

-Example downstream version: `1.3.0-1.0.0`
+Example downstream version: `1.3.1-1.0.0`

 ## Downstream Onboarding Method

- Keep the initial template snapshot in `.minions-template/`.
+- Keep the initial export-ready 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.
+- Exclude `.git/` and `do-not-export` files such as `.mm.md` from the vendored snapshot.
 - 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/`.
+- Keep the currently approved export-ready template snapshot in `.minions-template/`.
+- During upgrade, stage the incoming export-ready 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