diff --git a/.mm.md b/.mm.md index ec73e6a..994f3f1 100644 --- 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 diff --git a/CHANGELOG.md b/CHANGELOG.md index 80a4ac0..0b74078 100644 --- 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) diff --git a/INIT.md b/INIT.md index 6d6a146..4640050 100644 --- 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 diff --git a/MEMORY.md b/MEMORY.md index b6839ea..2233781 100644 --- 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 `-` (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 diff --git a/README.md b/README.md index dd2d7ed..d33173d 100644 --- 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 diff --git a/docs/collaboration-playbook.md b/docs/collaboration-playbook.md index a29dc35..802a71b 100644 --- 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 diff --git a/docs/downstream-onboarding-playbook.md b/docs/downstream-onboarding-playbook.md index af868e7..c8c5ba7 100644 --- 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 diff --git a/docs/downstream-upgrade-playbook.md b/docs/downstream-upgrade-playbook.md index b822e6a..5466104 100644 --- 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: diff --git a/docs/export-manifest.md b/docs/export-manifest.md index d36535b..af00312 100644 --- 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 diff --git a/docs/operator-onboarding-checklist.md b/docs/operator-onboarding-checklist.md index 9302873..ebd8da0 100644 --- 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 diff --git a/minion-version.md b/minion-version.md index 490f175..5cf5dc7 100644 --- 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: `-` -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