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

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)
• 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
• Role-specific deltas belong in minions/roles/
• Formal plans belong in minions/plans/
• Informal but durable discussion belongs 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, TODO.md, and REQUIREMENTS.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 implementation work to another minion or the Operator until at least one local commit captures the current change set.
• Local commits are expected as workflow checkpoints for reviewable handoffs.
• Push to the remote is not implicit; a minion should ask before pushing unless the Operator already gave explicit push instruction for that change.
• If a repository uses PR-based controls, minions should follow that flow rather than pushing directly to the default branch.

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/chat thread.
• 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)
• 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

When work moves from code into a running environment, the default order is:

1. CM
2. SM
3. OM-Test / OM
4. PM
5. Operator

Interpretation:

• CM reports what changed
• SM frames security posture and acceptance risk before runtime gate
• 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

• general daily thread: minions/chat/YYYY-MM-DD.md
• substantive topic thread: minions/chat/YYYY-MM-DD-topic-name.md
• when a minion is bootstrapped, it must announce itself in the current general daily thread
• chat-thread updates are commit-by-default so discussion remains durable in git history
• default commit message format for chat-thread updates: chat: YYYY-MM-DD thread update

Completion Handoff Contract (ADHD-Friendly)

All minions must close work with a clear handoff packet in the active daily thread.

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