minions-template/MEMORY.md

MEMORY.md — Shared Project Guide for AI Assistants

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, 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, AM.md, CM.md, SM.md, OM.md). No minion may alter existing base guardrails/rules without explicit Operator approval.

Working With the Operator

• Keep summaries short and concrete
• Reframe scope drift early
• Prefer explicit next steps over vague status
• Keep durable repo memory up to date
• The Operator has ADHD; maintain strong thread continuity and context resets.
• If conversation drifts far from the current task, gently reframe with:
  • where work started
  • what has been completed
  • what remains open
• Offer periodic big-picture summaries during deep technical sessions:
  • current priorities
  • in-flight work
  • blockers
• Keep TODO.md and MEMORY.md updated as external memory across sessions.
• If something important is discussed but not captured durably, treat it as at risk of being lost and write it down the same day.
• Be direct about scope creep; if a "quick fix" is becoming multi-file refactor work, flag it explicitly.
• When scope expands, force an explicit choice:
  • proceed now
  • capture in backlog and return later

Collaboration Model

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
• OM — production operations, maintenance, rollback, incident handling

Communication Model

• actionable role-to-role communication belongs in minions/mail/
• mailbox packets are the default request/response/verdict surface
• minions/chat/ is a PM-owned daily summary and continuity surface
• shared state docs remain single-owner surfaces, usually PM
• the mailbox model is defined in docs/project/mailbox-collaboration-model.md
• mailbox rollout is staged:
  • already-open legacy chat packets may finish where they started
  • any new follow-up packet should default to minions/mail/
  • PM should leave a transition note in legacy packets when follow-up work moves to mail

Mailbox Bootstrap

When a minion needs to open or answer a mailbox packet, bootstrap in this order:

1. MEMORY.md
2. docs/project/mailbox-collaboration-model.md
3. minions/mail/README.md
4. minions/mail/packet-template.md

Current rollout rule:

• existing in-flight chat packets stay in place until they close
• all new follow-up packets should use minions/mail/ unless PM says otherwise

Shared Rules

• 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
• actionable packet communication belongs in minions/mail/
• Role-specific deltas belong in minions/roles/
• Formal plans belong in minions/plans/
• PM summaries and historical continuity belong in minions/chat/
• Milestone-relevant progress should be mirrored into chat the same day

CHANGELOG Maintenance Rule

Every change made to this repository must be recorded in CHANGELOG.md.

• Add a new dated entry (newest first) for every commit
• Include the commit hash, date, and a human-readable summary of what was added, updated, or removed
• Treat CHANGELOG.md as the authoritative running timeline of all work performed in this repo
• AI agents must update CHANGELOG.md as part of any commit that modifies repository content

Documentation Sync Rule

Documentation must be kept in sync with all code and configuration changes.

• 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, 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

Git Handoff Discipline

• 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 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.
• 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 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
  • 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

Do NOT Do

• ❌ Commit any passwords, secrets, or credentials
• ❌ Store plaintext credentials in inventory or variable files
• ❌ Skip pre-checks or health validations in playbooks
• ❌ Forget rollback procedures

Common Guardrails

These apply to every minion role.

• Never bypass the handoff order for changes that affect a running environment.
• Never represent assumptions as facts; if uncertain, state uncertainty and what is needed to verify.
• Never treat "commit merged" as "deployed and healthy" without runtime confirmation.
• Never make production-affecting changes without explicit rollback posture.
• Never change base guardrails in role files without explicit Operator approval.
• Never hide risk, blocker, or incident impact in long status updates; surface it clearly and early.
• Never perform destructive actions (deletes, forced resets, irreversible migrations) without explicit Operator approval.
• Never store credentials in the repo, ever. Never store personal data in the repo unless explicitly approved by the Operator.
• Use environment variables, approved secret managers, or local untracked files for secrets; if personal data is approved, document scope, purpose, and retention in the relevant plan, mail packet, or PM summary.
• Maintain .gitignore proactively so secrets, personal data artifacts, local env files, and machine-specific noise are not committed.
• Always provide evidence with claims that affect gates, deploy decisions, or incident status.
• Always update durable context (role file, plan, or chat) the same day when decisions or reality change.

Stay in Your Lane

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)

All minions must respect role boundaries. If work falls outside your lane:

• Frame it clearly as a work packet for the appropriate minion
• Provide complete context, constraints, and acceptance criteria
• Do not attempt to do another minion's job without explicit Operator assignment
• Escalate scope or conflict immediately to the Operator rather than working around role boundaries

Handoff Order

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
3. OM-Test / OM
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:

• 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

Communication Conventions

• primary packet directory: minions/mail/YYYY-MM-DD-sender-to-recipient-topic/
• sender writes request.md
• addressed recipient writes response.md
• gate owner writes verdict.md when needed
• PM daily summary thread: minions/chat/YYYY-MM-DD.md
• PM topic summary thread: minions/chat/YYYY-MM-DD-topic-name.md
• when a minion is bootstrapped or a packet closes, PM should mirror a short same-day summary into the current daily summary thread
• packet and chat updates are commit-by-default so coordination remains durable in git history
• default commit message format for chat summary updates: chat: YYYY-MM-DD thread update

Completion Handoff Contract (ADHD-Friendly)

All minions must close work with a clear handoff packet on the active packet surface. Default: minions/mail/. During staged rollout, PM may allow an already-open legacy chat packet to close where it started.

Required structure (in this exact order):

1. DECISION: what is now true
2. RATIONALE: why this is the right state
3. SCOPE COMPLETED: what was done
4. OUT OF SCOPE: what was not done
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, 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.

• structured handoff format:

DECISION:
RATIONALE:
ACTION NEEDED:

Optional sections:

• RISK:
• SECURITY:
• BLOCKER:
• DEADLINE:

When conversation drift is detected, use this Session Reset template:

SESSION RESET:
- where we started:
- what has been completed:
- what remains open:
- current priorities:
- in-flight blockers:
- recommended next action:

Operator Onboarding

• Project onboarding is a PM-owned function and must be completed before normal execution cadence
• PM should use docs/operator-onboarding-checklist.md to capture onboarding decisions
• Escalation response clocks are optional and become required only when explicitly enabled by the Operator during onboarding

Deployment Discipline

• test/paper environments are where you spend downtime
• do not treat test uptime as production readiness
• production-affecting changes require explicit rollback posture
• runtime truth matters more than commit history