# 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 made durable in owned mail packets the
  same day, and `PM` should receive enough context to publish a same-day chat
  summary

## 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:

```text
DECISION:
RATIONALE:
ACTION NEEDED:
```

Optional sections:

- `RISK:`
- `SECURITY:`
- `BLOCKER:`
- `DEADLINE:`

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

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