Molloy-Home/minions-template
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: refine downstream onboarding workflow

Browse Source
This commit is contained in:
deamonkai
2026-04-12 13:56:28 -05:00
parent e650ec65d1
commit 7dd35f3975
11 changed files with 93 additions and 32 deletions
Download Patch File Download Diff File Expand all files Collapse all files

7
.mm.md
View File

@@ -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 - `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 - 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 - 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

22
CHANGELOG.md
View File

@@ -2,6 +2,28 @@
All notable changes to this repository are tracked here. 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 ## 2026-04-11
- Commit hash: pending (next commit) - Commit hash: pending (next commit)

12
INIT.md
View File

@@ -14,16 +14,16 @@ SM, and OM discipline, durable evidence, and milestone execution.
## Immediate Startup Sequence ## Immediate Startup Sequence
1. Run and complete [docs/operator-onboarding-checklist.md](docs/operator-onboarding-checklist.md) with the Operator. 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. Finalize project-specific sections in [MEMORY.md](MEMORY.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 - project purpose
- architecture - architecture
- environments - environments
- safety constraints - safety constraints
3. Open first milestone plan in [minions/plans](minions/plans). 4. 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. 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. 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. 7. Use [docs/downstream-upgrade-playbook.md](docs/downstream-upgrade-playbook.md) for later template updates.
## Roles and Handoff ## Roles and Handoff

7
MEMORY.md
View File

@@ -51,6 +51,7 @@ This project uses multiple AI agents ("minions") that coordinate through git:
- Shared truth belongs in `MEMORY.md` - 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`) - 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/` - 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 - `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 - `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 - `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 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 - 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 - 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 - 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 ## Downstream Onboarding Discipline
- `PM` owns initial downstream onboarding unless the Operator explicitly assigns another owner. - `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. - 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. - 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. - `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 ## Downstream Upgrade Discipline
- `PM` owns downstream template upgrades unless the Operator explicitly assigns another owner. - `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: - During upgrade, stage the incoming template in a temporary sibling path such as `.minions-template.next/` so PM can compare:
- current vendored template - current vendored template
- incoming template - incoming template

12
README.md
View File

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

6
docs/collaboration-playbook.md
View File

@@ -39,7 +39,7 @@ Onboarding should explicitly set:
Onboarding should use `docs/downstream-onboarding-playbook.md`, not a blind Onboarding should use `docs/downstream-onboarding-playbook.md`, not a blind
repo copy. 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` - 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` - 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 - 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. Use `PM` as the default owner for downstream template upgrades.
- onboarding should establish `.minions-template/` first; upgrades depend on that baseline - onboarding should establish `.minions-template/` first; upgrades depend on that baseline
- keep the approved template snapshot in `.minions-template/` - keep the approved export-ready template snapshot in `.minions-template/`
- stage the incoming template in a temporary path such as `.minions-template.next/` - 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 - 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 - 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 - update the downstream base template version only after the live files and vendored snapshot both match the approved upgrade

18
docs/downstream-onboarding-playbook.md
View File

@@ -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 Do not stage onboarding from `.minions-template.next/`; that path is for later
upgrade candidates. 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 ## Ownership
- `PM` owns the onboarding export packet and Operator-facing checklist - `PM` owns the onboarding export packet and Operator-facing checklist
@@ -40,7 +48,10 @@ upgrade candidates.
## Onboarding Workflow ## 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. 2. Review `docs/export-manifest.md` before exporting any live files.
3. Export `template-replace` files from `.minions-template/` into the live 3. Export `template-replace` files from `.minions-template/` into the live
downstream repo. downstream repo.
@@ -50,8 +61,8 @@ upgrade candidates.
- `MEMORY.md` - `MEMORY.md`
- `docs/operator-onboarding-checklist.md` - `docs/operator-onboarding-checklist.md`
- `minion-version.md` - `minion-version.md`
5. Do not export `do-not-export` files such as `.mm.md` unless the Operator 5. Do not export `do-not-export` files, and do not keep them in the vendored
explicitly wants them downstream. snapshot, unless the Operator explicitly wants them downstream.
6. Treat downstream-owned files as project surfaces, not template clones: 6. Treat downstream-owned files as project surfaces, not template clones:
- project `README.md` - project `README.md`
- live plans - live plans
@@ -94,6 +105,7 @@ upgrade candidates.
- template version being onboarded - template version being onboarded
- vendored snapshot path - vendored snapshot path
- confirmation that `.git/` and `do-not-export` files were excluded from the vendored snapshot
- files exported directly from template - files exported directly from template
- files manually merged for downstream use - files manually merged for downstream use
- files intentionally left downstream-owned - files intentionally left downstream-owned

13
docs/downstream-upgrade-playbook.md
View File

@@ -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, version before attempting a larger template jump. If the repo is truly new,
run the onboarding playbook first. 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 ## Ownership
- `PM` owns the upgrade packet, merge order, and Operator-facing decision - `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 1. Confirm the downstream repo's current base-template version in
`minion-version.md`. `minion-version.md`.
2. Stage the current approved template snapshot in `.minions-template/` if it is 2. Stage the current approved export-ready template snapshot in
not already present. `.minions-template/` if it is not already present.
3. Import the incoming template version into `.minions-template.next/`. 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 4. Diff `.minions-template/` against `.minions-template.next/` to see what the
template changed. template changed.
5. Use `docs/export-manifest.md` to classify each affected live file as: 5. Use `docs/export-manifest.md` to classify each affected live file as:

15
docs/export-manifest.md
View File

@@ -14,8 +14,19 @@ Use this manifest with:
consciously reapply any intentional downstream divergence consciously reapply any intentional downstream divergence
- `manual-merge`: always review and merge with downstream state - `manual-merge`: always review and merge with downstream state
- `downstream-owned`: do not overwrite during template upgrades - `downstream-owned`: do not overwrite during template upgrades
- `do-not-export`: keep in the template repo only unless the Operator explicitly - `do-not-export`: keep out of downstream live files and out of the vendored
chooses otherwise `.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 ## Manifest

2
docs/operator-onboarding-checklist.md
View File

@@ -33,7 +33,7 @@ Date: YYYY-MM-DD
- `CHANGELOG.md` initialized and owner set - `CHANGELOG.md` initialized and owner set
- `ROADMAP.md` initialized and owner set - `ROADMAP.md` initialized and owner set
- `TODO.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` - initial downstream export completed using `docs/downstream-onboarding-playbook.md`
- downstream template-upgrade owner confirmed (default `PM`) - downstream template-upgrade owner confirmed (default `PM`)
- `minion-version.md` reviewed and downstream version format confirmed - `minion-version.md` reviewed and downstream version format confirmed

11
minion-version.md
View File

@@ -1,22 +1,23 @@
# Minion Template Version # 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>` 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 ## 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. - 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. - 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. - Commit the vendored snapshot and exported live files together so later upgrades have a stable comparison base.
## Downstream Upgrade Method ## Downstream Upgrade Method
- Keep the currently approved template snapshot in `.minions-template/`. - Keep the currently approved export-ready template snapshot in `.minions-template/`.
- During upgrade, stage the incoming template in a temporary path such as `.minions-template.next/`. - 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. - `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: - 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 - old vendored template