# Memory Bank

> Agent-agnostic long-term project memory through `.memory-bank/` + RULES (TDD/SOLID/Clean Architecture/FSD/Mobile) + dev-toolkit commands. Use when working in a project with a `.memory-bank/` directory or when the user explicitly asks for memory-bank workflow, code rules, or dev-toolkit commands.

- Skill: `fockus/memory-bank` (Agent Skill, multi-file: 16 files)
- Install (CLI): `npx skillmds@latest add fockus/memory-bank`
- Raw SKILL.md: https://api.skillmd.com/api/skills/fockus/memory-bank/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: fockus (https://skillmd.com/u/fockus)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/fockus/memory-bank

---


# Memory Bank Skill

Three-in-one skill for code agents:

1. **Memory Bank** — long-term project memory through `.memory-bank/` (`STATUS`, `plan`, `checklist`, `RESEARCH`, `BACKLOG`, `progress`, `lessons`, `notes/`, `plans/`, `experiments/`, `reports/`, `codebase/`).
2. **RULES** — global engineering rules: TDD, Clean Architecture (backend), FSD (frontend), Mobile (iOS/Android UDF), SOLID, Testing Trophy.
3. **Dev toolkit** — 33 commands: `/mb`, `/start`, `/done`, `/plan`, `/brief`, `/discuss`, `/groom`, `/sdd`, `/work`, `/drive`, `/config`, `/pipeline`, `/profile`, `/commit`, `/pr`, `/review`, `/test`, `/refactor`, `/doc`, `/changelog`, `/catchup`, `/adr`, `/contract`, `/security-review`, `/api-contract`, `/db-migration`, `/observability`, `/roadmap-sync`, `/traceability-gen`, `/analyze-task`, `/flow`, `/goal`, `/agree`.

> **Design contract.** Memory Bank rests on one inviolable promise — *agents remember* — and a stack of fully configurable, token-economical layers above it. Default behaviour never changes without explicit opt-in; user customisations survive upgrades; expensive paths are off by default. See [`references/design-principles.md`](references/design-principles.md) for the full contract.

Supported host model:
- **Claude Code / OpenCode** — native command surface + global install.
- **Cursor** — native full support: global skill alias (`~/.cursor/skills/memory-bank/`), global hooks (`~/.cursor/hooks.json`), global slash commands (`~/.cursor/commands/`), `~/.cursor/AGENTS.md` with managed section, plus a paste-ready file for Settings → Rules → User Rules. Project-level `.cursor/` adapter remains available as an add-on via `--clients cursor`.
- **Codex** — global skill discovery + `AGENTS.md` hints + project-level `.codex/` adapter; no separate native slash-command surface.
- **Other code agents** — via adapters, `AGENTS.md`, local hooks/configs, or direct CLI/script usage.

---

## Development flow — stages a code agent should expect

Work in a Memory Bank project follows this order. Depth scales with task complexity — every stage except development itself can be skipped for trivial work; review and judge are **opt-in**.

| # | Stage | Command | Notes |
|---|-------|---------|-------|
| 1 | **Interview** | `/mb discuss <topic>` (alias `/mb ask_me`) | Grilling interview → decisions + EARS-validated requirements draft in `context/<topic>.md` |
| 2 | **Spec or plan** | `/mb sdd <topic>` · `/mb plan <type> <topic>` | Pick by complexity: feature/multi-task → spec triple (`specs/<topic>/requirements+design+tasks.md`, executable `<!-- mb-task:N -->`); smaller bounded change → plan (`plans/*.md`, `<!-- mb-stage:N -->`); trivial fix → no artifact (rules still apply) |
| 3 | **Development** | `/mb work <target>` | Executes spec tasks / plan stages one by one through an implement → verify loop with role subagents (TDD, contract-first) |
| 4 | **Verification** | `/mb verify` | plan-verifier audits diff vs plan/spec DoD; **mandatory before `/mb done`** when work followed a plan/spec |
| 5 | **Review** *(optional)* | `/mb work <target> --review` | Reviewer verdict (subagent ensemble or external codex) + severity gate; off by default |
| 6 | **Judge** *(optional)* | `/mb work <target> --judge` | `mb-judge` decides GO / GO_WITH_BACKLOG / NO_GO and terminates the review loop |
| 7 | **Close** | `/mb done` | Actualize bank: progress append, checklist/status update |

**Grooming (any stage).** `/mb groom <topic>` (also `grooming`) runs a critical grooming session outside the fixed order — for a raw idea, a task that already has a spec, or a decision worth revisiting. Unlike `/mb discuss`, the goal is not a spec: the agent challenges necessity and approach, proposes its own solutions, covers white spots; the summary lands in `context/<topic>-groom.md`, confirmed decisions go to `agreements.md` / backlog (ADR/Ideas), and the session ends with proposed next steps (e.g. `/mb sdd`).

**Pipeline.** The whole chain can be encoded in `<bank>/pipeline.yaml` as a named workflow (steps, per-role `model`/`thinking`, severity gates, protected paths, budget). When present, `/mb work` resolves it automatically (`mb-workflow.sh`) and follows the configured steps — e.g. governed `implement → verify → review → judge → fix → done` — without per-run flags. Manage with `/mb pipeline` / `/mb config`; validate with `/mb config validate`. Defaults never change without opt-in: no pipeline and no flags = simple implement → verify.

**Command index — all `/mb` subcommands** (know these exist; suggest them to the user when relevant; details per subcommand → `commands/mb.md` or `/mb help <sub>`):

- **Session & context:** `context` (default, empty arg) · `start` · `done` · `update` · `tasks` · `note <topic>` · `index`
- **Requirements & decisions:** `discuss <topic>` (alias `ask_me`) · `groom <topic>` (alias `grooming`) · `sdd <topic>` · `openspec <import|list|status|sync>` · `plan <type> <topic>` · `idea <title>` · `idea-promote <I-NNN>` · `adr <title>` · `agree <sub>` · `goal`
- **Execution:** `work [target]` · `verify` · `config <sub>` · `pipeline <sub>` · `flow <route>` · `analyze-task`
- **Codebase intelligence & memory:** `map [focus]` · `graph` · `wiki` · `research <query>` · `search <query>` · `recall <query>` · `recap <sid>` · `conflicts` · `consolidate` · `tags`
- **Setup & maintenance:** `init` · `install` · `profile <sub>` · `doctor` · `compact` · `migrate-structure` · `import` · `upgrade` · `deps` · `statusline` · `help [sub]`

Beyond `/mb`, the toolkit ships standalone commands (see the list in the intro above): `/commit`, `/pr`, `/review`, `/test`, `/refactor`, `/doc`, `/changelog`, `/catchup`, `/contract`, `/security-review`, `/api-contract`, `/db-migration`, `/observability`, `/roadmap-sync`, `/traceability-gen`.

---

## Quick start

```bash
# Storage modes — pick one per project:
/mb init                                      # local mode (default) — bank in repo (.memory-bank/)
/mb init --storage=local                      # explicit local mode — same as above
/mb init --storage=global --agent=claude-code # global mode — bank in ~/.claude/memory-bank/...
                                              # (personal, NOT committed to the repo)
# Rules-only mode: no /mb init at all — [MEMORY BANK: ABSENT] state;
# /mb lifecycle stays inactive; all TDD/SOLID/Clean Architecture/DRY/KISS/YAGNI rules still apply.

# Initialization flags
/mb init --full          # same as /mb init (stack auto-detect + CLAUDE.md generation)
/mb init --minimal       # only the .memory-bank/ structure

# Session flow (basic)
/mb start                # load context
# ... work, checklist.md updates as tasks complete ...
/mb verify               # verify plan alignment (if there was a plan)
/mb done                 # actualize + note + progress

# Unified SDD flow (spec-driven features)
/mb discuss <topic>      # EARS-validated requirements → context/<topic>.md
/mb sdd <topic>          # spec triple: requirements / design / tasks.md (executable)
# specs/<topic>/tasks.md is a first-class executable artifact with <!-- mb-task:N --> markers,
# NOT a scaffold — each block is resolved by /mb work <topic> as a work item.
# requirements.md may add an optional `## Scenarios` layer: <!-- mb-scenario:N --> blocks
# (### Scenario: + **Covers:** REQ-x + GIVEN/WHEN/THEN). They become a test-plan
# (mb-scenario-extract.py) that /mb plan links and /mb work turns into one real test
# per scenario in the project's stack. Enforce coverage with
# `mb-spec-validate.sh --require-scenarios`; off by default (EARS-only specs stay valid).
/mb work <topic>         # execute spec tasks one by one (reads <!-- mb-task:N --> blocks)
/mb verify               # verify against spec + plan
/mb done                 # actualize + progress
```

# Personalize rules for your stack (optional):
/mb profile init --scope=project --role=backend --stack=go --architecture=microservices --delivery=contract-first
# or user-global (works even without a project Memory Bank):
/mb profile init --scope=user --role=frontend --stack=typescript

If the host does not support native slash commands, use:
- `commands/mb.md` as the workflow entrypoint;
- the `memory-bank ...` CLI for install/init/doctor flows;
- bundled scripts and agent prompts from this skill bundle.

---

## Workspace resolution — agent-agnostic storage

Memory Bank resolves its active bank through `scripts/_lib.sh::mb_resolve_path`. The precedence is fixed and explicit:

1. **Explicit argument** — `mb-*.sh <mb_path>` always wins.
2. **`MB_PATH` env override** — for ad-hoc redirection in shell sessions.
3. **Local mode** — `<project>/.memory-bank/` (default of `/mb init`, team-shared, committable).
4. **Global mode** — registered in `<agent_config>/memory-bank/registry.json`. Requires `--storage=global --agent=<name>` on init (or `$MB_AGENT` env). Per supported agent:
   - `claude-code` → `$HOME/.claude/memory-bank/projects/<id>/.memory-bank`
   - `cursor` → `$HOME/.cursor/memory-bank/projects/<id>/.memory-bank`
   - `codex` → `$HOME/.codex/memory-bank/projects/<id>/.memory-bank`
   - `opencode` → `$HOME/.config/opencode/memory-bank/projects/<id>/.memory-bank`
   - `pi` → `$HOME/.pi/agent/memory-bank/projects/<id>/.memory-bank`
   - `windsurf`/`cline`/`kilo` → analogous under the respective config dir
5. **Legacy `.claude-workspace`** — kept for backward compatibility (`storage: external` + `project_id: <id>` → `~/.claude/workspaces/<id>/.memory-bank`). New projects should use `--storage=global` instead.
6. **Fallback** — relative `.memory-bank` (compat with existing scripts).

### Active-state semantics

- `[MEMORY BANK: ACTIVE]` — when the resolver returns an **existing** bank (local or registered global).
- `[MEMORY BANK: ABSENT]` — when no bank exists for the current project. Surface this and **stop** the Memory Bank lifecycle — do **not** silently initialize.
- `[MEMORY BANK: INITIALIZED]` — only after a successful explicit `/mb init`.

### Rules-only mode

A project may intentionally have no Memory Bank (`[MEMORY BANK: ABSENT]`). In that case:

- `/mb` lifecycle commands stay inactive until the user explicitly runs `/mb init`.
- The **engineering rules baseline still applies**: TDD, SOLID, Clean Architecture / FSD, DRY/KISS/YAGNI, Testing Trophy, protected files, no placeholders, verification before completion. Global skill installation never auto-enables Memory Bank state.

When invoking MB Manager or scripts, always pass the resolved `mb_path`.

---

## Tools — shell scripts

All scripts live in `scripts/` next to this `SKILL.md`. In global installs, the bundle is typically available through host aliases:
- Claude Code: `~/.claude/skills/memory-bank/`
- Codex: `~/.codex/skills/memory-bank/`
- Cursor: `~/.cursor/skills/memory-bank/`

Scripts work with `.memory-bank/` in the current directory or through the `mb_path` argument.

### GraphRAG-lite retrieval routing

`code_context is the default` for ambiguous code-understanding questions such as "where is the logic for X?" or "find similar implementation". Exact structural questions route directly to graph tools: "who calls/imports/defines X?" → `graph_neighbors`, "reverse deps" or change impact → `graph_impact`, and "what tests cover this file/symbol?" → `graph_tests`. User explicitly asks "semantic search" → `search_code` because explicit tool intent wins.

Fail open: missing graph, stale graph, missing semantic provider, or unavailable native extension must not block the agent. Use `scripts/mb-graph-query.py` and `scripts/mb-code-context.py` as the universal CLI fallback; Pi and OpenCode may expose native tool wrappers, while Claude Code, Codex, and generic AGENTS.md agents can call the scripts directly.

| Script | Purpose |
|--------|---------|
| `_lib.sh` | Shared helpers sourced by other scripts |
| `mb-context.sh [--deep]` | Build context from core files (`STATUS` + `plan` + `checklist` + `RESEARCH` + codebase summary). `--deep` shows full codebase docs |
| `mb-statusline.py [--install]` | Claude Code statusline showing context-window fill `%` (`used/limit`, 1M-aware) + model · branch · project. Reads the status JSON on stdin; `--install` wires it into `~/.claude/settings.json` (backup, no clobber) |
| `mb-search.sh <q> [--tag t]` | Keyword search across the memory bank. `--tag` filters via `index.json` |
| `mb-note.sh <topic>` | Create `notes/YYYY-MM-DD_HH-MM_<topic>.md`. Collision-safe (`_2` / `_3`) |
| `mb-plan.sh <type> <topic>` | Create `plans/YYYY-MM-DD_<type>_<topic>.md` with `<!-- mb-stage:N -->` markers |
| `mb-plan-sync.sh <plan>` | Synchronize a plan ↔ checklist + roadmap + status (idempotent) |
| `mb-plan-done.sh <plan>` | Close a plan: `⬜→✅` + move to `plans/done/` |
| `mb-idea.sh <title> [HIGH\|MED\|LOW]` | Capture a new idea in `backlog.md` with monotonic `I-NNN` |
| `mb-idea-promote.sh <I-NNN>` | Promote an idea (I-NNN) into an active plan |
| `mb-adr.sh <title>` | Capture an Architecture Decision Record in `backlog.md` (ADR-NNN) |
| `mb-init-bank.sh` | Deterministic, locale-aware `.memory-bank/` scaffolder |
| `mb-config.sh` | Memory Bank config resolver + locale auto-detector |
| `mb-metrics.sh [--run]` | Language-agnostic metrics (12 stacks). `--run` captures `test_status=pass\|fail` |
| `mb-index.sh` | Registry of all entries (core + notes/plans/experiments/reports) |
| `mb-index-json.py` | Build `index.json` (frontmatter notes + lessons headings). Atomic write |
| `mb-drift.sh` | 8 deterministic drift checkers (path, staleness, script coverage, dependency, cross-file, index sync, command, frontmatter) |
| `mb-progress-chain.sh` | `--rebuild-tail` / `--verify` the `progress.md` append-only hash chain (`index.json:progress_chain`); CRITICAL drift on tamper (handoff-v2) |
| `mb-rules-check.sh` | Deterministic rules enforcement (SRP / Clean Architecture / TDD delta) |
| `mb_rules_check_lib.sh` | Shared helper library for `mb-rules-check.sh` |
| `mb_rules_check_profile.sh` | Profile resolution and output emitters for `mb-rules-check.sh` |
| `mb_rules_check_baseline.sh` | Baseline SRP / Clean Architecture / TDD checks for `mb-rules-check.sh` |
| `mb_rules_check_stack.sh` | Stack-aware and FSD checks for `mb-rules-check.sh` |
| `mb-done-gates.sh` | Mandatory `/mb done` gate set (tests + rules + placeholder scan); `--force --reason` records a NOTE in `progress.md` (handoff-v2) |
| `mb-test-run.sh` | Structured test runner with per-stack output parsing → strict JSON |
| `mb-deps-check.sh [--install-hints]` | Preflight dependency checker (python3, jq, git + optional tree-sitter, networkx) |
| `mb-checklist-prune.sh [--apply]` | Collapse completed sections in `checklist.md` to one-liners (≤120-line cap). **Rule: `checklist.md` = open TODO only; commit hashes / test counts / closeouts go to `progress.md`.** Opt-in SessionEnd autoprune when it exceeds the cap via `MB_CHECKLIST_AUTOPRUNE=on` (`hooks/mb-checklist-autoprune.sh`) |
| `mb-compact.sh [--apply]` | Status-based compaction decay — archive old done plans + low-importance notes |
| `mb-handoff.sh` | Handoff capsule manager — `--actualize` / `--read` / `--rotate` a ≤1500-byte session capsule under `handoff/` (handoff-v2) |
| `mb-tags-normalize.sh [--apply]` | Levenshtein-based tag synonym detection + merge across `notes/` |
| `mb-roadmap-sync.sh` | Regenerate `roadmap.md` autosync block from `plans/*.md` frontmatter |
| `mb-traceability-gen.sh` | Regenerate `traceability.md` from specs + plans + tests |
| `mb-ears-validate.sh <file>` | Validate REQ bullets against the 5 EARS patterns |
| `mb-req-next-id.sh` | Emit the next monotonic `REQ-NNN` identifier |
| `mb-sdd.sh <topic>` | Create a Kiro-style spec triple under `specs/<topic>/` (requirements / design / tasks). Scaffolds an optional `## Scenarios` (GIVEN/WHEN/THEN) section |
| `mb-scenario-extract.py <file>` | Extract `<!-- mb-scenario:N -->` GIVEN/WHEN/THEN blocks → normalized test-plan (JSON Lines: covers + steps + stable `test_id`). `--validate` checks present scenarios are well-formed. Opt-in layer; absent scenarios → empty/no-op |
| `mb_work_items.py` | Shared parser for plan stages (`<!-- mb-stage:N -->`) and spec tasks (`<!-- mb-task:N -->`); CLI emits JSON Lines |
| `mb_req_id.py` | Shared REQ-ID grammar (single source of truth) used by traceability / spec-validate / ears-validate. Supports prefixed schemes (`REQ-RS-008`), distinguishes a definition from a mid-line mention, expands `REQ-RS-002/003` slash-shorthand, and maps pytest identifiers (`req_rs_008`) onto canonical ids |
| `mb-spec-validate.sh <topic\|spec-dir\|spec-file>` | Validate spec triple integrity (EARS, parseable tasks, per-task Covers/DoD/Testing, no REQ orphans). Present GIVEN/WHEN/THEN scenarios are structure-checked; `--require-scenarios` (opt-in) enforces ≥1 scenario per REQ; `--require-tests` (opt-in) enforces ≥1 covering test per REQ (scans `<repo>/tests`, `<mb>/tests`, or `MB_TEST_ROOTS`). `--json` mode for structured output |
| `mb-spec-tasks-migrate.sh <topic\|tasks-file> [--apply\|--dry-run]` | Migrate legacy `## N. ...` tasks to `<!-- mb-task:N -->` format. Dry-run default, --apply writes backup before changes, idempotent |
| `mb-pipeline.sh` | Manage the project's `pipeline.yaml` (spec §9) |
| `mb-pipeline-validate.sh` | Structural validation for `pipeline.yaml` (spec §9) |
| `mb-work-resolve.sh` | Resolve `<target>` arg into a plan/spec path (spec §8.2) |
| `mb-work-range.sh` | Emit per-stage indices (plan mode) or per-sprint paths |
| `mb-work-plan.sh` | Emit per-stage execution plan as JSON Lines (spec §8) |
| `mb-work-budget.sh` | Token budget tracker for `/mb work --budget` |
| `mb-work-protected-check.sh` | Match files against `pipeline.yaml:protected_paths` |
| `mb-work-review-parse.sh` | Validate reviewer output for `/mb work` review-loop |
| `mb-work-severity-gate.sh` | Apply `pipeline.yaml:severity_gate` to review counts |
| `mb-work-trend.sh` | Review-cycle trend: weighted score (10×blocker + 3×major + 1×minor) vs the previous cycle → `improving` / `stagnant` / `regressing` / `null` (work-loop-v2 G2) |
| `mb-work-pivot.sh` | Decide `refine` / `pivot_in_role` / `pivot_via_architect` from the trend + cycle count, instead of grinding the same fix (`pivot_after_cycles`, `pivot_escalate_to_architect_on`) |
| `mb-work-contract.sh` | Per-stage "what done means" contract under `<bank>/contracts/<topic>_stage-<N>.md` — `create` / `read` / `validate` / `path`; the reviewer can judge against it |
| `mb-workflow.sh` | Resolve the active workflow + per-step `model`/`thinking` config from `pipeline.yaml` for `/mb work` |
| `mb-drive.sh` | Autonomous goal-driven loop: `next` reads goal-acceptance + the firewall + work-state + budget and emits exactly one action (`implement` / `repair` / `pivot` / `stop_*`). Stateless, fail-closed — `stop_success` requires a green firewall AND 100% acceptance (REQ-DR-014) |
| `mb-drive-stop.sh` | Drive-loop stop telemetry + per-run drive state: `arm` marks a drive live (arms the Stop-hook resume-gate), `record --reason\|--action` writes the stop reason once into the `mb-flow` fence, `progress.md`, and the run's state slot (REQ-DR-033/034) |
| `mb-work-state.sh` | Durable `/mb work` loop-state + `max_cycles` enforcement; optional per-run isolation/claim under `MB_WORK_PARALLEL` |
| `mb-work-slots.sh` | Sourced helper: per-run state/budget/drive slot-path resolution + source→run claim index (gated behind `MB_WORK_PARALLEL`) |
| `mb-work-checkbox.sh` | Deterministic DoD-checkbox flip, gated on the run's work-state phase (single-writer for `checklist.md`) |
| `mb-work-diff.sh` | Baseline-scoped diff for a `/mb work` run — feeds verify/review with the stage's own changes only |
| `mb-work-progress-append.sh` | Locked, atomic, append-only writer for `<bank>/progress.md` (safe under concurrent runs) |
| `mb-work-codex-preflight.sh` | Fail-safe codex CLI availability/auth health-check before a cross-model review wave |
| `mb-session-doctor.sh` | Diagnose session-memory subsystem health (unsummarized sessions, missing index/adapters, legacy stubs) |
| `mb-agent-caps.sh` | Capability-aware dispatch: resolve CLI transport (pi/opencode/codex/claude-agent) + concrete model per role by probing CLI presence and model availability |
| `mb-reviewer-resolve.sh` | Pick the active reviewer agent name |
| `mb-review.sh` | Review orchestrator entry point: deterministic 5-section payload assembly (diff + calibration examples + test evidence + auto-findings), model-agnostic, `--emit-payload`/`--input` |
| `mb-review-cache.sh` | Touched-file test-evidence cache: `compute_touched_sha` + TTL HIT/MISS resolution under `.memory-bank/tmp/` |
| `mb-review-examples.sh` | Layered calibration-example loader: project-over-skill precedence by `example_id`, fence-aware parser, per-category rotation, path-traversal/symlink-safe; renders the `## Calibration examples` payload section |
| `mb-session-spend.sh` | Session token-spend tracker (sprint context guard) |
| `mb-session-recent-rebuild.sh` | Regenerate `session/_recent.md` from `session/*.md` (keeps newest `MB_RECENT_KEEP`; deterministic, idempotent) |
| `mb-recap.sh <sid>` | `/mb recap`: reconstruct a full `progress.md` entry from `session/<sid>*.md` via one Haiku call, replacing that session's auto-capture stub idempotently (`recapped` frontmatter). Missing session → exit non-zero, no writes; real entry already present → refuse |
| `mb-conflicts.sh [--judge] [--threshold N]` | `/mb conflicts`: report memory entries with high lexical overlap **and** opposing/replacement assertions (en+ru markers) as conflict candidates — `$0` pass (token-set Jaccard > `N`, default 0.3) over `notes/` + `lessons.md` + recent `progress.md`, zero LLM calls. `--judge` confirms/rejects each pair via one Sonnet call + prints a suggested `[SUPERSEDED: YYYY-MM-DD -> <ref>]` marker. PRINT-ONLY — never writes to any bank file |
| `mb-consolidate.sh [--apply] [--days N]` | `/mb consolidate`: fold sessions older than `N` days (default 30) that cluster by shared files / lexical overlap into 5–15 line `notes/` candidates, archive those session files VERBATIM → `session/archive/`, and move their contiguous auto-capture progress STUBS VERBATIM → `progress-archive.md`. Zero LLM calls. Dry-run is the DEFAULT (writes nothing — bank byte-identical); `--apply` performs it. Real progress entries are immutable and never move |
| `mb-auto-commit.sh` | Opt-in auto-commit of `.memory-bank/` after `/mb done` (`MB_AUTO_COMMIT=1` or `--force`) — 4 safety gates, MB-only staging, never pushes |
| `mb-freshness.sh [--porcelain\|--stop-nudge\|--banner]` | Deterministic MB-vs-code drift alarm (`behind`/`dirty`); drift-gated Stop nudge + SessionStart banner (`MB_DRIFT_WARN_COMMITS`/`MB_DRIFT_WARN_DIRTY_LINES`, opt-out `MB_FRESHNESS_BANNER=off`). See `docs/concepts/session-memory.md` for the auto-commit recipe |
| `mb-migrate-v2.sh` | One-shot v1 → v2 migrator for `.memory-bank/` |
| `mb-migrate-structure.sh` | One-shot v3.0 → v3.1 structure migrator for `.memory-bank/` |
| `mb-import.py` | Claude Code JSONL → Memory Bank bootstrap importer |
| `mb-openspec.sh` | Thin dispatcher for the OpenSpec import adapter: `import\|list\|status\|sync` → `mb-openspec.py` |
| `mb-openspec.py` | One-way OpenSpec `changes/<id>/` → MB spec triple `specs/<topic>/` import + drift-aware `list`/`status`/`sync` (opt-in `--normalize` LLM slot layer) |
| `mb_openspec_model.py` | Dataclasses shared by the OpenSpec adapter's parser/converter |
| `mb_openspec_parse.py` | Read-only OpenSpec change parser (`parse_change`, `compute_source_hash`) |
| `mb_openspec_convert.py` | Deterministic OpenSpec → MB spec-triple converter (anchors, EARS classify, re-import anchor reuse) |
| `mb_openspec_normalize.py` | Opt-in `--normalize` LLM slot layer + source-hash cache for the OpenSpec adapter (fail-open) |
| `mb-agree.sh` | Single writer for the running list of agreements (`agreements.md`): `add\|defer\|reject\|question\|resolve\|list\|sync` + managed-block sync |
| `mb-codegraph.py` | Code graph orchestrator. Extractors in `memory_bank_skill/`: `codegraph_python` (stdlib `ast`), `codegraph_treesitter` (multi-language, opt-in), `codegraph_analytics` (communities/cohesion/betweenness, optional networkx), `codegraph_cochange` (git co-change edges via opt-in `--cochange`) |
| `mb-graph-query.py` | Query `codebase/graph.json`: `neighbors`, `impact`, `tests`, `explain`, `summary` with JSON/markdown output |
| `mb_graph_query_core.py` | Core graph loading, matching and payload builders for `mb-graph-query.py` |
| `mb_graph_query_render.py` | Markdown summary renderers for graph-query output |
| `mb-code-context.py` | GraphRAG-lite evidence pack: optional semantic candidates + graph expansion + text/read fallback |
| `mb_code_context_core.py` | Core evidence-pack orchestration for `mb-code-context.py` |
| `mb-semantic-search.py` | Semantic code search over `graph.json` (+ wiki): `--backend auto` (embeddings when `sentence-transformers` installed, else pure-Python BM25 — the $0 zero-dep base), `--source-only`, disk cache in `.index/codesearch/`. Modules in `memory_bank_skill/`: `semantic_search`, `semantic_embeddings`, `codegraph_loader` |
| `mb-wiki.py` | `/mb wiki` engine (deterministic prep): `plan`/`packs`/`write-article`/`merge-edges`/`index`. LLM articles + surprising-connection edges via host subagents. Modules: `wiki_evidence`, `wiki_store` |
| `mb-context-slim.py` | Slim a full agent prompt on stdin → terse version on stdout |
| `mb-cost-report.py [--project <dir>] [--since N] [--json]` | `/mb cost` engine: mine Claude Code transcripts (`~/.claude/projects/<slug>/`) into per-session, per-subagent-role and per-work-item (`mb-work-state.sh init` → `mb-work-checkbox.sh flip`) cost. Parsing in `memory_bank_skill/cost_report.py` |
| `mb-upgrade.sh [--check\|--force]` | Self-update the skill from GitHub |
| `mb-version-check.sh [--force]` | Is a newer release out? Compares local `VERSION` against the latest GitHub Release (PyPI JSON as fallback), cached with a TTL. Prints strict JSON (`current`/`latest`/`update_available`/`flavor`/`upgrade_command`/`checked_at`/`source`). Always fail-open — exit 0, silent, never blocks a session. Off: `MB_UPDATE_CHECK=off` |
| `mb-profile.sh` | Rule profile manager: `init`, `show`, `path`, `validate`, `set` — user/project scopes |
| `mb-diff-scope.sh` | L5 diff-scope backstop: compare changed files against an allowed glob scope and report out-of-scope changes (exits 0, JSON report; ADR-4) |
| `mb-fanout.sh` | Stateless fan-out helper: run N branch prompts concurrently via background jobs, capture JSON results, and aggregate into one object — exit-code authority for failed branches (REQ-DF-084) |
| `mb-flow-branch-sink.sh` | Per-branch result sinks with write-once discipline for `<!-- mb-flow -->` fence: each parallel branch writes to its own `.mb-flow/branch-<i>.json` to prevent races (ADR-9) |
| `mb-flow-route.sh` | Deterministic route resolver: apply route-floor rules (REQ-DF-022) to an LLM-proposed or user-supplied route and write the resolved `route:` into the `<!-- mb-flow -->` fence in status.md |
| `mb-flow-sync.sh` | Regenerate the `<!-- mb-flow -->` runtime fence in status.md: emit route, phase, checks, gate, last-verify-sha, stall-count, and stop-reason fields (REQ-DF-030/031/032, REQ-DR-033) |
| `mb-flow-verify.sh` | THE firewall fan-out: run route-relevant check runners, normalize verdicts via `mb-work-severity-gate.sh`, and exit 0/1/2 — the sole exit-code authority of the dynamic-flow firewall (ADR-3) |
| `mb-goal-acceptance.sh` | L5 goal-acceptance aggregator: parse `## Acceptance criteria` checkboxes in goal.md and report whether every criterion is satisfied (exits 0, JSON report; REQ-DF-042) |
| `mb-goal-validate.sh` | Validate a goal.md before a Dynamic Flow run: enforce required sections, acceptance-criteria items, and field completeness — fail-loud exit 1 on malformed goals (REQ-DF-004) |
| `mb-lint-run.sh` | L5 lint runner: auto-detect project stack via `mb-metrics.sh`, map to linter (ruff/shellcheck), run it, and report findings (exits 0, JSON report; ADR-3; unknown stack = SKIP) |
| `mb-no-todo.sh` | L5 residual-placeholder runner: scan target files for TODO/FIXME/HACK markers, reusing `mb_rules_check_lib.sh::scan_placeholders` patterns and exemptions (exits 0, JSON report; REQ-DF-042) |
| `mb-session-prune.sh` | Archive contentless session stubs out of `<bank>/session/` into `session/archive/stubs/`; dry-run is the default, `--apply` performs the move. Also flags/repairs bloated files (`>MB_SESSION_BLOAT_BYTES`) with post-`## Summary` bullets |
| `mb-session-repair.sh [--apply] <file>` | Repair a session file corrupted by the legacy append-after-`## Summary` bug: move turn-bullets back into `## Live log`, reset `summarized=false`, re-cap over-long bullets, keep a `archive/pre-repair/` backup. Dry-run default, idempotent, fail-safe |
| `mb-settings-ensure-timeout.py` | Surgically ensure the SessionEnd `mb-session-end.sh` hook command carries a per-command `timeout` so the Haiku summarizer is not SIGKILLed before writing `## Summary` |
| `mb-subinvoke-resolve.sh` | Resolve the per-agent shell sub-invoke command template for the active agent (mirrors `mb-reviewer-resolve.sh`); used by `mb-fanout.sh` to bake `--cmd` when the operator does not supply one (REQ-DF-082) |
| `mb-brief.sh` | Deterministic helper behind `/mb brief`: `create` (topic + candidate + `--input` documents), `context`, `accept` — the file effects of the brief stage live in a script, not a prompt |
| `mb-brief-validate.sh` | Structural validator for a brief one-pager — section order, required fields, single-page budget |
| `mb_brief_candidate.py` | Candidate inspection for `mb-brief.sh` (contract C6 steps 4–5) |
| `mb-glossary.sh` | Atomic upsert of a single `<term> — <definition>` line in `<bank>/glossary.md`; term and definition are read from files, so no quoting loss (REQ-017) |
| `mb-estimate-check.sh` | Deterministic size-estimate validator: the `/mb discuss` context estimate and the spec-triple / candidate budget gate. No LLM, no PyYAML |
| `mb-estimate-lib.sh` | Sourced parsers for `mb-estimate-check.sh` (context-file and spec/candidate estimates). Not a standalone entry point |
| `mb-interview-artifact-check.sh` | Deterministic structural validator for `/mb discuss` interview artifacts — `plan`, `--require-closed`, `--print-digest`. No LLM |
| `mb-interview-artifact-write.sh` | Deterministic writer for `/mb discuss` file effects: atomic publish, and byte-identity of a rejected target is a script-proven fact rather than a prompt promise |
| `mb-secret-scan.sh` | Canonical secret-scan dispatcher (`transcript` and `brief-input` policies); patterns are single-sourced from `mb-import.py`, never a second regex set |
| `mb-sdd-candidate.sh` | Candidate lifecycle for `/mb sdd` generation: the seam separating a GENERATED `tasks.md` from an ACCEPTED one (`<bank>/tmp/sdd/<topic>/tasks.candidate.md`) |
| `mb-sdd-self-check.sh` | Deterministic executor of the C8 generation self-check battery over a published draft triple, so `commands/sdd.md` decides draft→ready by exit code, not prompt judgement. Pure checker — writes nothing |
| `mb-sdd-self-check-eval.sh` | Sourced half of the C8a battery: how ONE `**Eval:**` declaration is classified in a given phase (`--phase generation` requires red, `--phase done` requires green) |
| `mb-sdd-review-result.sh` | Executable owner of the spec-review exit codes: validation, the append-only record, and 0/1/2 — `commands/sdd.md` owns only the model dispatch |
| `mb_sdd_judge_journal.py` | Judge / override / status half of the spec-review journal (append-only, symlink-safe) |
| `mb-sdd-layers-render.py` | Deterministic renderer for the test-layer tasks and the `## Quality DoD` block |
| `mb-quality-dod.sh` | Render the one canonical `## Quality DoD` block; the orchestrator runs it ONCE per item and hands the same file to implementer, reviewer, and judge |
| `mb_quality_dod.py` | The `## Quality DoD` renderer core — one renderer, three receivers |
| `mb-rules-resolve.sh` | Resolve the rule sources a spec is judged against — `discovery` and `validation` modes behind one JSON contract |
| `mb_rules_resolve.py` | Rule-source resolution core for `mb-rules-resolve.sh` |
| `mb-contract-gate.sh` | Execute a spec's Contract-checkers registry (the fenced ```json``` block of the `**Layer:** contract` task) |
| `mb_contract_gate.py` | Runner for the Contract-checkers registry |
| `mb_contract_registry.py` | The Contract-checkers registry — one reader, one schema, two consumers |
| `mb-work-state-eval.sh` | Sourced eval-first layer for `mb-work-state.sh`: the red→green Eval gate. Not a standalone entry point |
| `mb-work-state-lib.sh` | Sourced helpers for `mb-work-state.sh` that shell out to external tooling (pipeline YAML, uuid). Not a standalone entry point |
| `mb_work_eval_proof.py` | Canonical eval-proof payload for the `mb-work-state` red→green gate |
| `mb_work_plan_wrapper.py` | Wrapper-plan resolution for `mb-work-plan.sh` (`linked_spec` / `<!-- mb-stage:N -->`) |
| `mb-backlog-state.sh` | Backlog state machine, hierarchy, and briefs: `transition <I-NNN> <STATE>`, `annotate --brief --parent` |
| `mb_backlog_state_engine.py` | Backlog parser + state engine behind the backlog scripts |
| `mb_backlog_validate.py` | Backlog metadata validation: the brief gate (REQ-007) + single-line safety |
| `mb_roadmap_group.py` | Group-section rendering + progress aggregation for `mb-roadmap-sync.sh` |
| `mb_roadmap_order.py` | Pure ICE-component parsing + priority ordering for `mb-roadmap-sync.sh` |
| `mb_roadmap_plans.py` | Plan-frontmatter parsing + collection for `mb-roadmap-sync.sh` |
| `mb_roadmap_render.py` | Fence handling, bootstrap transfer, and atomic publish for `mb-roadmap-sync.sh` |
| `mb_spec_validate_v2.py` | v2 / C8 battery gates for `mb-spec-validate.sh` |
| `mb_spec_validate_tasks.py` | Per-task structural checks 3–6 for `mb-spec-validate.sh` |
| `mb_spec_validate_structural.py` | Scope classification + structural Eval grammar (REQ-049) |
| `mb_spec_validate_scope_eval.py` | I-174 gate: a task's `**Eval:**` must actually run the test files its `**Scope:**` claims |
| `mb_spec_validate_layers.py` | Test-layer gates C3/C4 and the Contract-checkers schema |
| `mb_spec_validate_graph.py` | `blocked_by` dependency-graph gates (REQ-052 / C8.5) |
| `mb_pipeline_validate_core.py` | Pipeline config validation core for `mb-pipeline-validate.sh` |
| `mb_pipeline_validate_blocks.py` | Per-block pipeline validators (budget … named-pipeline metadata) |
| `mb_pipeline_minimal_yaml.py` | PyYAML-optional minimal loader for `pipeline.yaml` — the zero-dep base |
| `mb_fs_atomic.py` | One atomic file-publish primitive, shared by every writer |

---

## Agents — subagents (sonnet)

| Agent | When to invoke | Prompt |
|-------|----------------|--------|
| `mb-manager` | `/mb context`, `search`, `note`, `tasks`, `done`, `update`, PreCompact hook | `agents/mb-manager.md` |
| `mb-doctor` | `/mb doctor` — memory-bank inconsistencies (use `mb-plan-sync.sh` first, only edit for semantic drift) | `agents/mb-doctor.md` |
| `mb-codebase-mapper` | `/mb map [focus]` — scan the codebase → `.memory-bank/codebase/{STACK,ARCHITECTURE,CONVENTIONS,CONCERNS}.md` | `agents/mb-codebase-mapper.md` |
| `plan-verifier` | `/mb verify` — required before `/mb done` when work followed a plan. Uses `**Baseline commit:**` from plan header for `git diff`, delegates tests to `mb-test-runner`, enforces RULES.md via `mb-rules-enforcer` | `agents/plan-verifier.md` |
| `mb-rules-enforcer` | `/review`, `/commit`, `/pr`, `plan-verifier` step 3.6 — runs `mb-rules-check.sh` (solid/srp, clean_arch/direction, tdd/delta) + LLM ISP/DRY judgment. Returns strict JSON + summary | `agents/mb-rules-enforcer.md` |
| `mb-test-runner` | `/test`, `plan-verifier` step 3.5 — runs `mb-test-run.sh`, correlates failures with session diff. Returns JSON `{stack, tests_pass, tests_total, failures[], coverage, duration_ms}` | `agents/mb-test-runner.md` |
| `mb-reviewer` | `/mb work` legacy single-reviewer fallback — reads stage diff + `pipeline.yaml:review_rubric`, emits structured JSON verdict | `agents/mb-reviewer.md` |
| `mb-reviewer-logic` | `/mb work` governed review ensemble — correctness / logic aspect reviewer with scoped context | `agents/mb-reviewer-logic.md` |
| `mb-reviewer-tests` | `/mb work` governed review ensemble — test-coverage / quality-of-tests aspect reviewer | `agents/mb-reviewer-tests.md` |
| `mb-reviewer-quality` | `/mb work` governed review ensemble — code-quality / maintainability aspect reviewer | `agents/mb-reviewer-quality.md` |
| `mb-reviewer-security` | `/mb work` governed review ensemble — security aspect reviewer | `agents/mb-reviewer-security.md` |
| `mb-reviewer-scalability` | `/mb work` governed review ensemble — performance / scalability aspect reviewer | `agents/mb-reviewer-scalability.md` |
| `mb-reviewer-lead` | `/mb work` governed review — synthesizes aspect reports, verifies previous master report closure, separates blockers from backlog | `agents/mb-reviewer-lead.md` |
| `mb-judge` | `/mb work` governed final gate — decides GO / GO_WITH_BACKLOG / NO_GO from plan, verifier, lead-review, and evidence | `agents/mb-judge.md` |
| `mb-engineering-core` | **[partial — not dispatched directly]** Prepended by `/mb work` ahead of every dev-role agent below. Carries the shared discipline: TDD, Contract-First, Clean Architecture, production-wiring, evidence-before-claims (Iron Law), escalation, STATUS contract, anti-rationalization. Excluded from the `~/.claude/agents/` registry via `partial: true` frontmatter. | `agents/mb-engineering-core.md` |
| `mb-tooling-core` | **[partial — not dispatched directly]** Prepended by `/mb work` alongside `mb-engineering-core`. Carries the graph-first, fail-open code-understanding routing (`code_context` / `graph_neighbors` / `graph_impact` / `graph_tests` / `search_code` / `recall`). Optional indexes degrade to `Grep`/`Read`. Excluded from the registry via `partial: true`. | `agents/mb-tooling-core.md` |
| `mb-developer` | `/mb work` — generic implementer when no specialist role matches. Discipline from `mb-engineering-core` + DoD-driven implementation | `agents/mb-developer.md` |
| `mb-architect` | `/mb work` — architecture / ADR / system-design specialist. Domain modelling, interface definition, refactoring strategy | `agents/mb-architect.md` |
| `mb-backend` | `/mb work` — APIs, services, database, async/concurrency, server-side business logic | `agents/mb-backend.md` |
| `mb-frontend` | `/mb work` — React/Vue/Svelte/Solid components, browser UI, accessibility, responsive layouts | `agents/mb-frontend.md` |
| `mb-ios` | `/mb work` — SwiftUI/UIKit, Combine, async/await, Apple platform conventions | `agents/mb-ios.md` |
| `mb-android` | `/mb work` — Jetpack Compose, Kotlin coroutines, Hilt/DI, Room, Material3 | `agents/mb-android.md` |
| `mb-devops` | `/mb work` — CI/CD, Docker, Kubernetes, Terraform, observability, release engineering | `agents/mb-devops.md` |
| `mb-qa` | `/mb work` — test design, coverage strategy, edge-case enumeration, flake elimination, contract tests | `agents/mb-qa.md` |
| `mb-analyst` | `/mb work` — data / analytics / metrics: SQL, dashboards, cohorts, ETL pipelines, instrumentation | `agents/mb-analyst.md` |
| `mb-research` | `/mb research` (and broad `/mb work` research steps) — graph-first, multi-source research over codebase + project memory + library docs + GitHub prior-art + open web; read-only (no Write/Edit), returns `file:line` / source-grounded conclusions, degrades to `Grep` when indexes are absent | `agents/mb-research.md` |
| `mb-researcher` | `/mb work` governed research role (wired in `pipeline.default.yaml`) — ecosystem research, implementation reconnaissance, source comparisons, technical due diligence, and evidence-backed option matrices before planning or implementati

…(truncated)