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

docs: add architect role and template workflows

Browse Source
This commit is contained in:
deamonkai
2026-04-12 12:25:07 -05:00
parent 64de2660d2
commit e650ec65d1
18 changed files with 626 additions and 53 deletions
Download Patch File Download Diff File Expand all files Collapse all files

37
docs/collaboration-playbook.md
View File

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

101
docs/downstream-onboarding-playbook.md Normal file
View File

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

101
docs/downstream-upgrade-playbook.md Normal file
View File

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

49
docs/export-manifest.md Normal file
View File

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

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

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