memory-bank

Files (200)

• .coveragerc
• pages.yml · .github/workflows/
• publish.yml · .github/workflows/
• test.yml · .github/workflows/
• .gitignore
• .mb-config · .memory-bank/
• BACKLOG.md · .memory-bank/.migration-backup-20260422-174417/
• RESEARCH.md · .memory-bank/.migration-backup-20260422-174417/
• STATUS.md · .memory-bank/.migration-backup-20260422-174417/
• plan.md · .memory-bank/.migration-backup-20260422-174417/
• BACKLOG.md · .memory-bank/.pre-migrate-20260421-163107/
• BACKLOG.md · .memory-bank/.pre-migrate/20260421_091115/
• STATUS.md · .memory-bank/.pre-migrate/20260421_091115/
• checklist.md · .memory-bank/.pre-migrate/20260421_091115/
• plan.md · .memory-bank/.pre-migrate/20260421_091115/
• COORDINATION.md · .memory-bank/
• RULES.md · .memory-bank/
• adr.md · .memory-bank/
• agreements.md · .memory-bank/
• backlog.md · .memory-bank/
• checklist.md · .memory-bank/
• ARCHITECTURE.md · .memory-bank/codebase/
• CONCERNS.md · .memory-bank/codebase/
• CONVENTIONS.md · .memory-bank/codebase/
• STACK.md · .memory-bank/codebase/
• god-nodes.md · .memory-bank/codebase/
• graph.json · .memory-bank/codebase/
• adapter-parity.md · .memory-bank/context/
• agreements.md · .memory-bank/context/
• composable-work-pipeline.md · .memory-bank/context/
• drive-autopilot-interview.md · .memory-bank/context/
• drive-autopilot.md · .memory-bank/context/
• mb-donor-evolution.md · .memory-bank/context/
• openspec-adapter.md · .memory-bank/context/
• pi-native-integration.md · .memory-bank/context/
• quality-track.md · .memory-bank/context/
• sdd-openspec-parity.md · .memory-bank/context/
• sdd-vision-pipeline-interview.md · .memory-bank/context/
• sdd-vision-pipeline.md · .memory-bank/context/
• svp-adapt-escalation-interview.md · .memory-bank/context/
• svp-adapt-escalation.md · .memory-bank/context/
• svp-brief-interview.md · .memory-bank/context/
• svp-brief.md · .memory-bank/context/
• svp-contract-test-loop-interview.md · .memory-bank/context/
• svp-contract-test-loop.md · .memory-bank/context/
• svp-docs-wiki-interview.md · .memory-bank/context/
• svp-docs-wiki.md · .memory-bank/context/
• svp-interview-upgrade-interview.md · .memory-bank/context/
• svp-interview-upgrade.md · .memory-bank/context/
• svp-parallel-engine-interview.md · .memory-bank/context/
• svp-parallel-engine.md · .memory-bank/context/
• svp-roadmap-backlog-db-interview.md · .memory-bank/context/
• svp-roadmap-backlog-db.md · .memory-bank/context/
• svp-sdd-core-interview.md · .memory-bank/context/
• svp-sdd-core.md · .memory-bank/context/
• svp-spec-review-loop.md · .memory-bank/context/
• tier1-graph-memory.md · .memory-bank/context/
• glossary.md · .memory-bank/
• goal.md · .memory-bank/
• index.json · .memory-bank/
• …and 140 more

SKILL.md (first lines)

# Memory Bank Skill

Three-in-one skill for code agents:

1. **Memory Bank** — long-term project memory through `.memory-bank/` (`status.md`, `checklist.md`, `roadmap.md`, `research.md`, `backlog.md`, `adr.md`, `progress.md`, `lessons.md`, `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** — 36 commands: `/mb`, `/start`, `/done`, `/plan`, `/brief`, `/discuss`, `/groom`, `/sdd`, `/work`, `/drive`, `/team`, `/qa`, `/config`, `/pipeline`, `/profile`, `/rules`, `/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.

Details live in one-level reference files read on demand — see [References](#references) at the end.

---

## 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 askme`) | 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 |
| 6a | **QA** *(optional)* | `/mb qa run` | Walk the md acceptance scenarios in `<bank>/qa/test_cases/` in a real browser (Playwright MCP) on the live stand; after a stand update, before close |
| 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 `askme`) · `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>` · `rules <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`.

> **Plan hierarchy:** Phase → Sprint → Stage. See `references/templates.md` § *Plan decomposition* for size thresholds, terminology, and when to use which level. Cyrillic «Этап / Спринт / Фаза» — legacy alias, allowed only in `plans/done/*.md`.

---

## Task routing

Before starting, size the task — trivial / small / standard / large / extra — and match plan, tests, docs and checks to the tier: [`references/effort-tiers.md`](references/effort-tiers.md). An explicit user request beats the estimate. Independent tasks go to parallel subagents. Plan coarse; decompose only when stuck (ADaPT).

## 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-agent paths: [`references/structure.md`](references/structure.md) § Global storage paths.
5. **Legacy `.claude-workspace`** — old pointer mode, see [`references/structure.md`](references/structure.md) § Old patterns.
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.
Set `SKILL_DIR` to the absolute directory containing the loaded `SKILL.md` (or `MB_SKILLS_ROOT`)
in the same shell invocation as each command; on Codex this is normally its skill alias above.
Use `SKILL_DIR="${MB_SKILLS_ROOT:-${SKILL_DIR:?Set SKILL_DIR from the loaded skill path}}"` after binding that path.

### 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. Optional dependencies (tree-sitter, networkx, fastembed) are not assumed installed: `bash "$SKILL_DIR"/scripts/mb-deps-check.sh --install-hints` prints the exact install command. Use `bash "$SKILL_DIR"/scripts/mb-graph.sh who-calls|impact|tests <Symbol>` / `search "<query>"` / `status` 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.

**Entry points agents call** (full grouped table incl. internal libraries → [`references/scripts.md`](references/scripts.md)):

- `mb-context.sh [--deep]` — load bank context (status, checklist, active plan, codebase summary)
- `mb-graph.sh who-calls|impact|tests <Symbol>` / `search "<query>"` / `status` — graph + semantic code search front door
- `mb-search.sh <q> [--tag t]` — keyword search across the bank
- `/mb recall <query>` (`hooks/mb-recall.sh`) — hybrid semantic + lexical recall (RRF) over sessions, notes, agreements, progress
- `mb-plan.sh <type> <topic>` / `mb-plan-sync.sh <plan>` — create a plan with `<!-- mb-stage:N -->` markers, sync it to checklist/roadmap
- `mb-spec-validate.sh <topic>` — validate a spec triple (EARS, executable `<!-- mb-task:N -->` tasks, REQ coverage)
- `mb-workflow.sh` / `mb-work-resolve.sh` / `mb-work-plan.sh` — resolve the `/mb work` workflow, target, and per-item JSON plan
- `mb-agree.sh add|question|list …` — single writer for `agreements.md`
- `mb-coord.sh active` / `append` — read/write the cross-session board without loading it
- `mb-idea.sh` / `mb-adr.sh` — capture an idea (`I-NNN`) in `backlog.md` or an ADR (`ADR-NNN`) in `adr.md`
- `mb-profile.sh` — rule profiles (`init`, `show`, `validate`, `set`)
- `mb-drift.sh` / `mb-done-gates.sh` — deterministic drift checkers; mandatory `/mb done` gates

---

## Quick start

```bash
# Storage modes — pick one per project:
/mb init                                      # local mode (default) — bank in repo (.memory-bank/)

From fockus/skill-memory-bank, MIT.