memory-bank-skill 3.0.0rc1__tar.gz

memory_bank_skill-3.0.0rc1/.gitignore

@@ -0,0 +1,15 @@
+.installed-manifest.json
+*.backup.*
+.DS_Store
+.env
+*.env
+*.pem
+*.key
+*.secret
+__pycache__/
+*.pyc
+.coverage
+htmlcov/
+.pytest_cache/
+.ruff_cache/
+.memory-bank/codebase/.cache/

memory_bank_skill-3.0.0rc1/CHANGELOG.md

@@ -0,0 +1,197 @@
+# Changelog
+
+Все значимые изменения документируются здесь. Формат — [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), версионирование — [SemVer](https://semver.org/spec/v2.0.0.html).
+
+## [3.0.0-rc1] — 2026-04-20
+
+### Repository moved
+
+Этот skill переехал в новый публичный репозиторий: **[`fockus/skill-memory-bank`](https://github.com/fockus/skill-memory-bank)**. Старое имя `claude-skill-memory-bank` отражало только один из 8 поддерживаемых клиентов и стало misleading.
+
+**Migration guide:** [docs/repo-migration.md](docs/repo-migration.md).
+
+Historical releases (`v1.x`, `v2.0.0`, `v2.1.0`, `v2.2.0`) остаются доступны в старом репозитории. `v3.0.0` и далее публикуются в новом.
+
+### Added
+
+- **Stage 8 — Cross-agent adapters** (7 clients beyond Claude Code): Cursor (CC-compat hooks), Windsurf (Cascade), Cline (`.clinerules/hooks/`), Kilo (+ git-hooks fallback), OpenCode (TS plugin с `experimental.session.compacting`), Codex (experimental hooks), Pi Code (dual-mode). See `docs/cross-agent-setup.md`.
+- **`adapters/_lib_agents_md.sh`** — refcount-based shared `AGENTS.md` ownership via `.mb-agents-owners.json`. Enables safe coexistence of OpenCode / Codex / Pi installs.
+- **`adapters/git-hooks-fallback.sh`** — universal `.git/hooks/` installer (post-commit auto-capture, pre-commit `<private>` warnings, chain pattern preserves user hooks).
+- **`install.sh --clients <list>`** — non-interactive multi-client install. Valid: `claude-code, cursor, windsurf, cline, kilo, opencode, pi, codex`.
+- **`docs/cross-agent-setup.md`** — complete per-client cheatsheet + hook capability matrix + troubleshooting FAQ.
+- **`docs/repo-migration.md`** — upgrade instructions for existing users.
+
+### Changed
+
+- Repository name: `claude-skill-memory-bank` → `skill-memory-bank`.
+- Install target directory: `~/.claude/skills/skill-memory-bank/` (was `claude-skill-memory-bank/`).
+- `mb-upgrade.sh` tracks new origin URL.
+
+### Tests
+
+- **340+/340+ bats + e2e green** (+90 adapter bats, +10 install-clients e2e over v2.2.0).
+
+---
+
+## [2.2.0] — 2026-04-20
+
+Knowledge-reach release: cold-start через JSONL-импорт, code graph для 6 языков, tags normalization через controlled vocabulary.
+
+### Added
+
+- **`/mb import --project <path> [--since] [--apply]`** (`scripts/mb-import.py`) — bootstrap Memory Bank из Claude Code транскриптов (`~/.claude/projects/<slug>/*.jsonl`). Извлекает daily-grouped `progress.md` секции и arch-discussion notes (≥3 consecutive assistant messages >1K chars). Dedup SHA256(timestamp + first 500 chars), resume через `.import-state.json`. PII auto-wrap (email + API-key → `<private>`) интегрирован с v2.1 Stage 3. `--dry-run` default.
+- **`/mb graph [--apply] [src_root]`** (`scripts/mb-codegraph.py`) — code graph для Python (stdlib `ast`, always-on) + Go / JavaScript / TypeScript / Rust / Java (через tree-sitter, opt-in). Nodes = module/function/class, edges = import/call/inherit. Output: `codebase/graph.json` (JSON Lines, grep/jq friendly) + `codebase/god-nodes.md` (top-20 by degree). SHA256 incremental cache per-file. `HAS_TREE_SITTER` флаг обеспечивает graceful degrade без grammars. Skipped dirs: `.venv`, `node_modules`, `__pycache__`, `.git`, `target`, `dist`, `build`.
+- **`/mb tags [--apply] [--auto-merge]`** (`scripts/mb-tags-normalize.sh`) — Levenshtein-based synonym detection + merge через controlled vocabulary. Distance ≤2 detection, ≤1 для `--auto-merge`. Vocabulary в `.memory-bank/tags-vocabulary.md` (user-editable) → fallback на `references/tags-vocabulary.md` (35 default tags). Exit 2 если найдены unknown tags (drift signal).
+- **`references/tags-vocabulary.md`** — template с 35 default тегами (Core: arch/auth/bug/perf/refactor/test/...; Process: debug/review/post-mortem/adr/spike; Workflow: blocked/todo/wip/imported/discussion).
+- **`mb-index-json.py`** — авто-kebab-case для тегов: `FooBar → foo-bar`, `AUTH → auth`, `someThing → some-thing`. Dedup preserving order. Source files не трогаются — только index.
+
+### Changed
+
+- **`mb-codegraph.py`** — Python-only v1 расширен tree-sitter adapter для 5 новых языков. Same node/edge schema. Lazy parser loading per language via `_TS_PARSERS` cache.
+- **`commands/mb.md`** — секции `/mb import`, `/mb graph`, `/mb tags` с полными примерами, dogfood-outputs, ограничениями.
+- **`install.sh`** — печатает hint для tree-sitter extras.
+
+### Tests
+
+- pytest: **96** (было 44 после v2.1) — +17 test_import, +21 test_codegraph (Python), +14 test_codegraph_ts (tree-sitter).
+- bats: **208** (было 194) — +14 test_tags_normalize.
+- shellcheck: 0 warnings. ruff: all passed.
+
+### Gate v2.2 — passed ✅
+
+1. ✅ `/mb import` на реальном JSONL (2573 events) — **0.127s** (target ≤30s).
+2. ✅ `mb-codegraph.py` на `scripts/` — **0.068s** для 60 nodes + 487 edges (target ≤30s).
+3. ✅ Tags normalization: `sqlite_vec → sqlite-vec` auto-merged distance=1, 2 notes rewritten. Unknown tag → exit 2 drift signal works.
+4. ✅ Full regression: 96 pytest + 208 bats + ruff + shellcheck clean.
+5. ✅ VERSION 2.2.0, CHANGELOG updated.
+
+### ADR pivots
+
+- **ADR-006 обновлён (Stage 6.5):** изначально tree-sitter был deferred opt-in. После feedback пользователя ("часто работаю на Node/Go") — реализовано в v2.2, с graceful degrade при отсутствии grammars. Python path остался zero-dep. См. BACKLOG (Stage 6.5 shipped entry).
+
+### Deferred to v3.x backlog
+
+- Haiku-powered compression для `/mb import` summaries (сейчас deterministic first+last chars).
+- Debug-session detection в `/mb import` для `lessons.md`.
+- Type inference в `/mb graph` (edges сейчас name-based, не различают модули с одноимёнными функциями).
+- tree-sitter grammars для C/C++/Ruby/PHP/Kotlin/Swift (добавить по запросу через `_TS_LANG_CONFIG`).
+
+## [2.1.0] — 2026-04-20
+
+Hardening release: auto-capture при забытом `/mb done`, detection drift без AI, защита PII в заметках, status-based decay для старых планов и заметок.
+
+### Added
+
+- **Auto-capture SessionEnd hook** (`hooks/session-end-autosave.sh`) — если сессия закрылась без `/mb done`, hook добавляет placeholder-запись в `progress.md`. Lock-файл `.memory-bank/.session-lock` пишется командой `/mb done` → hook видит свежий lock (<1h) и пропускает auto-capture. `MB_AUTO_CAPTURE` env: `auto` (default) / `strict` / `off`. Concurrent-safe через `.auto-lock` (30s TTL). Идемпотентен по session_id.
+- **Drift checkers без AI** (`scripts/mb-drift.sh`) — 8 deterministic checkers (path, staleness, script_coverage, dependency, cross_file, index_sync, command, frontmatter). Output: `drift_check_<name>=ok|warn|skip` + `drift_warnings=N`. Exit 0 если 0 warnings, 1 иначе. `agents/mb-doctor.md` Step 0 = `mb-drift.sh` → LLM call только если `drift_warnings > 0`. Экономит AI-токены.
+- **PII markers `<private>...</private>`** в notes — содержимое блоков не попадает в `index.json` (summary + tags filtered), при `mb-search` заменяется на `[REDACTED]` (inline) или `[REDACTED match in private block]` (multi-line). Unclosed `<private>` fail-safe: хвост до EOF считается приватным. Entries получают `has_private: bool` флаг. `--show-private` требует `MB_SHOW_PRIVATE=1` env (double-confirmation). `hooks/file-change-log.sh` warnит при Write/Edit `.md` файла с `<private>` блоком.
+- **Compaction decay `/mb compact`** (`scripts/mb-compact.sh`) — status-based archival: требует **age > threshold AND done-signal**. Active планы (not done) **НЕ архивируются** даже >180d — warning only. Done-signal (OR): файл физически в `plans/done/`, ИЛИ метка `✅`/`[x]` в `checklist.md`, ИЛИ упоминание как "завершён|done|closed|shipped" в `progress.md`/`STATUS.md`. Notes — `importance: low` + mtime >90d + нет референсов в core файлах. `--dry-run` (default) reasoning only, `--apply` выполняет + touch `.last-compact`. Entries из `notes/archive/` получают `archived: bool` флаг. `mb-search --include-archived` — opt-in для поиска в архиве.
+
+### Changed
+
+- **`agents/mb-doctor.md`** — Step 0 теперь вызов `mb-drift.sh`; LLM-шаги (1-4) выполняются только при drift_warnings > 0 или `doctor-full`.
+- **`scripts/mb-index-json.py`** — парсер `<private>` блоков, `has_private: bool` + `archived: bool` fields в entry schema.
+- **`scripts/mb-search.sh`** — span-aware Python filter для REDACTED replacement. `--show-private` + `--include-archived` флаги.
+- **`settings/hooks.json`** — добавлен SessionEnd event для auto-capture.
+- **`commands/mb.md`** — `/mb done` пишет `.session-lock`. Секция `/mb compact` с полной status-based логикой и примерами.
+- **`SKILL.md`** — секции "Private content" и "Auto-capture".
+- **`references/metadata.md`** — schema extended с `has_private` + `archived` fields.
+
+### Tests
+
+- bats: **194** (20 test_compact + 4 test_search_archived + 5 test_search_private + 20 test_drift + 12 test_auto_capture + регрессии).
+- pytest: **44** (7 PII + 2 archived + регрессии).
+- e2e: 18 install/uninstall (включая SessionEnd hook roundtrip).
+- shellcheck: 0 warnings (SC1091 info expected для `source _lib.sh`).
+- ruff: all passed.
+
+### Gate v2.1 — passed ✅
+
+1. ✅ Auto-capture end-to-end: симулированный SessionEnd → `progress.md` обновлён без `/mb done`.
+2. ✅ `mb-drift.sh` на broken fixture: 7 warnings из 8 categories (≥5 target).
+3. ✅ PII security smoke: `TOP-SECRET-LEAK-CHECK-GATE21` внутри `<private>` → **0 matches** в `index.json`.
+4. ✅ `/mb compact` dogfood: живой banks чистый (0 candidates), artificial 150d done-plan → archive, 150d active-plan → не archive (safety works).
+5. ✅ CI matrix `[macos, ubuntu]` × (bats + e2e + pytest) green.
+
+### Deferred to backlog
+
+- LLM upgrade для auto-capture (сейчас append-only, детали дочитывает `/mb start` из JSONL).
+- `/mb done` weekly prompt для compaction check.
+- Pre-commit drift hook как отдельный file (YAGNI, документирован в `references/templates.md`).
+
+## [2.0.0] — 2026-04-19
+
+Крупный рефакторинг: skill становится language-agnostic, tested, CI-covered, integrated с экосистемой Claude Code. Три концепта под одной крышей: **Memory Bank + RULES + dev toolkit**.
+
+### Added
+
+- **Language detection (12 стеков)**: Python, Go, Rust, Node/TypeScript, Java, Kotlin, Swift, C/C++, Ruby, PHP, C#, Elixir. `scripts/mb-metrics.sh` выдаёт key=value метрики для любого из них.
+- **Override для проектных метрик**: `.memory-bank/metrics.sh` (приоритет 1 над auto-detect).
+- **`scripts/_lib.sh`** — общие утилиты (workspace resolver, slug, collision-safe filename, detect_stack/test/lint/src_glob). 7 функций, 36 bats-тестов.
+- **`scripts/mb-plan-sync.sh`** и **`scripts/mb-plan-done.sh`** — автоматизация консистентности plan↔checklist↔plan.md через маркеры `<!-- mb-stage:N -->`.
+- **`scripts/mb-upgrade.sh`** — `/mb upgrade` для самообновления skill из GitHub (git fetch → prompt → ff-only pull + re-install).
+- **`scripts/mb-index-json.py`** — прагматичный index для `notes/` (frontmatter) + `lessons.md` (H3 маркеры). Atomic write. PyYAML opt-in с fallback.
+- **`mb-search --tag <tag>`** — фильтрация по тегам через `index.json`.
+- **`/mb init [--minimal|--full]`** — единая инициализация. `--full` (default) = `.memory-bank/` + `RULES.md` copy + auto-detect стека + `CLAUDE.md` + optional `.planning/` symlink.
+- **`/mb map [focus]`** — сканирование кодовой базы и генерация `.memory-bank/codebase/{STACK,ARCHITECTURE,CONVENTIONS,CONCERNS}.md`.
+- **`/mb context --deep`** — полный codebase-контент (default = 1-line summary).
+- **Правила Frontend (FSD)** и **Mobile (iOS + Android)** в `rules/RULES.md` и `rules/CLAUDE-GLOBAL.md`.
+- **`MB_ALLOW_NO_VERIFY=1`** — bypass для `--no-verify` в `block-dangerous.sh`.
+- **Log rotation** для `file-change-log.sh`: >10 MB → `.log.1 → .log.2 → .log.3`.
+- **GitHub Actions** `.github/workflows/test.yml`: matrix `[ubuntu-latest, macos-latest]` × (bats + e2e + pytest) + lint job (shellcheck + ruff).
+- **148 bats-тестов** (unit + e2e + hooks + search-tag), **35 pytest-тестов**, **94% total coverage**.
+
+### Changed
+
+- **`codebase-mapper` → `mb-codebase-mapper`** (MB-native): output path `.planning/codebase/` → `.memory-bank/codebase/`; 770 строк → 316 (−59%); 6 шаблонов → 4 (STACK, ARCHITECTURE, CONVENTIONS, CONCERNS), каждый ≤70 строк.
+- **`/mb update` и `mb-doctor`** больше не хардкодят `pytest`/`ruff`/`src/taskloom/` — используют `mb-metrics.sh`.
+- **`SKILL.md` frontmatter** — `user-invocable: false` (невалидное поле) заменено на `name: memory-bank` с описанием three-in-one concept.
+- **`Task(...)` → `Agent(subagent_type=...)`** во всех skill-файлах. Grep-проверка: 0 вхождений `Task(`.
+- **`mb-doctor`** чинит рассинхроны приоритетно через `mb-plan-sync.sh`/`mb-plan-done.sh`, Edit — только для семантических проблем.
+- **`install.sh`** — всегда пишет `# [MEMORY-BANK-SKILL]` маркер при создании нового `CLAUDE.md` (раньше — только при merge в существующий).
+- **`mb-manager actualize`** — вызывает `mb-index-json.py` вместо ручного Write на `index.json`.
+- **`file-change-log.sh`** — убран `pass\s*$` из placeholder-regex (false-positive); placeholder-поиск теперь вне Python docstrings.
+- **`install.sh` banner**: `19 dev commands` → `18 dev commands` (после слияния init-команд).
+
+### Deprecated
+
+- (нет — все deprecations полные в этом релизе; см. Removed)
+
+### Removed
+
+- **`/mb:setup-project`** — слит в `/mb init --full`. Команда `commands/setup-project.md` удалена.
+- **Orphan-агент `codebase-mapper`** — заменён на `mb-codebase-mapper`.
+- **Хардкод `pytest -q` / `ruff check src/`** в `commands/mb.md` и `agents/mb-doctor.md`.
+- **Все `Task(...)` вызовы** в skill-файлах (осталось 0).
+
+### Fixed
+
+- **E2E-found bug #1**: `install.sh` не добавлял маркер `[MEMORY-BANK-SKILL]` при создании **нового** `CLAUDE.md`. Результат: `uninstall.sh` не находил секцию для очистки.
+- **E2E-found bug #2**: `uninstall.sh` использовал GNU-only флаг `realpath -m`. На macOS BSD realpath падал. Fix: манифест хранит абсолютные пути, `realpath` не нужен.
+- **Node src_glob**: brace-pattern `*.{ts,tsx,js,jsx}` заменён на space-separated для portable grep.
+- **mb-note.sh**: коллизия имени (две заметки в одну минуту) теперь → `_2/_3` суффикс (было: `exit 1`).
+- **file-change-log false-positives**: bare `pass` в Python, TODO внутри docstring.
+- **shellcheck SC1003** в awk-блоке hook'а — переписан через `index()` без nested single-quote escapes.
+
+### Security
+
+- **`block-dangerous.sh`** обновлён с `MB_ALLOW_NO_VERIFY=1` explicit-opt-in override — раньше `--no-verify` блокировался наглухо без safe-escape.
+- **secrets-detection** в `file-change-log.sh` продолжает работать (`password|secret|api_key|token|private_key` в source-коде).
+
+### Infrastructure
+
+- **Dogfooding**: сам skill использует `.memory-bank/` в своём репозитории. План рефактора v2 лежит в `.memory-bank/plans/`, сессии закрываются через `/mb done`.
+- **VERSION marker**: `2.0.0-dev` → `2.0.0` пишется install.sh в `~/.claude/skills/memory-bank/VERSION`.
+- **CI-зелёный** на macOS + Ubuntu, 0 shellcheck warnings, ruff all passed.
+
+---
+
+## [1.0.0] — 2025-10-XX (pre-refactor baseline)
+
+- Initial Memory Bank skill: `.memory-bank/` structure, `/mb` roadmap-команда, 4 агента, 2 hooks, 19 commands.
+- Python-first: хардкод `pytest`, `ruff`, `src/taskloom/`.
+- Orphan-артефакты от GSD: `codebase-mapper`, `.planning/`.
+- 0 автоматических тестов.
+
+[2.0.0]: https://github.com/fockus/claude-skill-memory-bank/releases/tag/v2.0.0
+[1.0.0]: https://github.com/fockus/claude-skill-memory-bank/releases/tag/v1.0.0

memory_bank_skill-3.0.0rc1/PKG-INFO

@@ -0,0 +1,363 @@
+Metadata-Version: 2.4
+Name: memory-bank-skill
+Version: 3.0.0rc1
+Summary: Universal long-term project memory + dev toolkit for AI coding clients (Claude Code, Cursor, Windsurf, Cline, Kilo, OpenCode, Codex, Pi Code)
+Project-URL: Homepage, https://github.com/fockus/skill-memory-bank
+Project-URL: Repository, https://github.com/fockus/skill-memory-bank
+Project-URL: Issues, https://github.com/fockus/skill-memory-bank/issues
+Project-URL: Changelog, https://github.com/fockus/skill-memory-bank/blob/main/CHANGELOG.md
+Author-email: Anton Ivanov <ruzaliasib1705@gmail.com>
+License-Expression: MIT
+Keywords: ai-coding,claude-code,cursor,dev-tools,llm-memory,memory-bank
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development
+Classifier: Topic :: Software Development :: Documentation
+Requires-Python: >=3.11
+Provides-Extra: codegraph
+Requires-Dist: tree-sitter-go>=0.21; extra == 'codegraph'
+Requires-Dist: tree-sitter-java>=0.21; extra == 'codegraph'
+Requires-Dist: tree-sitter-javascript>=0.21; extra == 'codegraph'
+Requires-Dist: tree-sitter-python>=0.21; extra == 'codegraph'
+Requires-Dist: tree-sitter-rust>=0.21; extra == 'codegraph'
+Requires-Dist: tree-sitter-typescript>=0.21; extra == 'codegraph'
+Requires-Dist: tree-sitter>=0.21; extra == 'codegraph'
+Provides-Extra: dev
+Requires-Dist: pytest-cov>=4; extra == 'dev'
+Requires-Dist: pytest>=7; extra == 'dev'
+Requires-Dist: ruff>=0.5; extra == 'dev'
+Provides-Extra: yaml
+Requires-Dist: pyyaml>=6.0; extra == 'yaml'
+Description-Content-Type: text/markdown
+
+# memory-bank-skill
+
+[![test](https://github.com/fockus/skill-memory-bank/actions/workflows/test.yml/badge.svg)](https://github.com/fockus/skill-memory-bank/actions/workflows/test.yml)
+[![PyPI](https://img.shields.io/pypi/v/memory-bank-skill?color=blue)](https://pypi.org/project/memory-bank-skill/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
+
+**Long-term project memory + dev toolkit for 8 AI coding agents.** Your AI remembers the project between sessions, follows the same engineering rules, and picks up exactly where you left off.
+
+Works with: **Claude Code · Cursor · Windsurf · Cline · Kilo · OpenCode · Codex · Pi Code**.
+
+---
+
+## The problem it solves
+
+Every new AI coding session is amnesia. You re-explain the project, re-state the plan, re-list what's done. Rules get forgotten. Architecture drifts. Context compaction erases whatever the agent finally learned.
+
+**memory-bank-skill** fixes this by making AI memory a first-class citizen — a simple `.memory-bank/` directory inside your project that the agent reads at the start of every session and updates as it works.
+
+```
+.memory-bank/
+├── STATUS.md          ← where we are, what's next
+├── checklist.md       ← current tasks (✅ / ⬜)
+├── plan.md            ← priorities, direction
+├── RESEARCH.md        ← hypotheses, experiments
+├── progress.md        ← work log (append-only)
+├── lessons.md         ← mistakes not to repeat
+├── notes/             ← knowledge (5-15 line snippets)
+├── plans/             ← detailed plans per feature/fix
+└── reports/           ← analysis, post-mortems
+```
+
+This directory lives alongside your code (commit it, share it with your team, or `.gitignore` it — your call).
+
+---
+
+## Install
+
+Pick one:
+
+### Option 1: pipx (recommended, cross-platform)
+
+```bash
+pipx install memory-bank-skill           # stable
+# or, for the latest release candidate:
+pipx install --pip-args='--pre' memory-bank-skill
+
+memory-bank install                      # global install for Claude Code
+```
+
+**Requires:** Python 3.11+, `pipx`, `jq`.
+
+### Option 2: Homebrew (macOS / Linuxbrew)
+
+```bash
+brew tap fockus/tap
+brew install memory-bank
+memory-bank install
+```
+
+### Option 3: git clone (developers)
+
+```bash
+git clone https://github.com/fockus/skill-memory-bank.git ~/.claude/skills/skill-memory-bank
+cd ~/.claude/skills/skill-memory-bank
+./install.sh
+```
+
+### Add cross-agent support (Cursor, Windsurf, OpenCode, etc.)
+
+```bash
+# From inside your project directory:
+memory-bank install --clients claude-code,cursor,windsurf
+```
+
+Supported client names: `claude-code`, `cursor`, `windsurf`, `cline`, `kilo`, `opencode`, `pi`, `codex`.
+
+Full per-client details: [docs/cross-agent-setup.md](docs/cross-agent-setup.md).
+
+---
+
+## 5-minute quick start
+
+1. **Install** (see above).
+
+2. **Open your project** in your AI agent (Claude Code, Cursor, etc.) and run:
+
+   ```
+   /mb init
+   ```
+
+   This creates `.memory-bank/` with all the files above, detects your stack, and generates a `CLAUDE.md` (or equivalent) pointing the agent at the memory bank.
+
+3. **Every session starts with:**
+
+   ```
+   /mb start
+   ```
+
+   The agent loads `STATUS.md`, `checklist.md`, `plan.md`, `RESEARCH.md` — it knows exactly what you were working on and what comes next.
+
+4. **As you work:** the agent updates `checklist.md` (⬜ → ✅) whenever tasks finish.
+
+5. **Every session ends with:**
+
+   ```
+   /mb done
+   ```
+
+   This appends a session entry to `progress.md`, updates `STATUS.md` if needed, writes a knowledge note if something interesting was learned.
+
+That's it. Rinse and repeat.
+
+---
+
+## What you get
+
+### 1. Persistent project memory
+
+Across sessions, compaction events, and even across AI agents — the project state survives. Switch from Claude Code to Cursor mid-project and the new agent catches up by reading `.memory-bank/`.
+
+### 2. Engineering rules applied automatically
+
+Installs `~/.claude/RULES.md` (or equivalent per client) with:
+
+- **TDD** — tests before implementation
+- **Clean Architecture** (backend) — Infrastructure → Application → Domain, never the reverse
+- **Feature-Sliced Design** (frontend) — `app → pages → widgets → features → entities → shared`
+- **Mobile** (iOS/Android) — UDF + Clean layers, SwiftUI+Observation / Compose+StateFlow
+- **SOLID** — SRP (≤300 LOC / class), ISP (≤5 methods / interface), DIP (constructor injection)
+- **Testing Trophy** — integration > unit > e2e; mock only external services
+- **Coverage** targets — 85% overall, 95% core, 70% infrastructure
+
+The agent reads these rules at session start and follows them without you having to remind it.
+
+### 3. 18 dev-workflow commands
+
+| Command | Purpose |
+|---------|---------|
+| `/mb start` | Load full project context |
+| `/mb done` | End-of-session actualize + progress note |
+| `/mb verify` | Check that implementation matches the plan |
+| `/mb plan <type> <topic>` | Create a detailed plan (feature / fix / refactor / experiment) with DoD criteria |
+| `/mb search <query>` | Search across the memory bank |
+| `/mb note <topic>` | Quick knowledge note |
+| `/mb tasks` | Show pending work |
+| `/mb update` | Refresh core files without closing the session |
+| `/commit` | Conventional-commit message with context |
+| `/review` | Full code review (security + perf + quality) |
+| `/test` | Run tests with coverage analysis |
+| `/plan` | Implementation plan generator |
+| `/refactor` | Guided refactoring |
+| `/pr` | Create pull request with description |
+| `/adr` | Architecture Decision Record template |
+| `/contract` | Contract-first workflow (Protocol/ABC → tests → impl) |
+| `/security-review` | Security audit pass |
+| `/api-contract` | API contract validation |
+| `/db-migration` | Safe migration planning |
+| `/observability` | Logging/metrics/tracing review |
+| `/doc` | Generate documentation |
+| `/changelog` | CHANGELOG update |
+| `/catchup` | Summarize recent changes |
+
+### 4. Cross-agent portability
+
+One `.memory-bank/` directory, 8 AI clients:
+
+| Client | Native hooks | Adapter output |
+|--------|--------------|----------------|
+| **Claude Code** | Full lifecycle | `~/.claude/settings.json` + `hooks/` |
+| **Cursor 1.7+** | ✅ (Claude-Code-compatible format) | `.cursor/rules/*.mdc` + `.cursor/hooks.json` |
+| **Windsurf** | ✅ Cascade Hooks | `.windsurf/rules/*.md` + `.windsurf/hooks.json` |
+| **Cline** | ✅ `.clinerules/hooks/*.sh` | `.clinerules/memory-bank.md` + `hooks/` |
+| **Kilo** | ❌ (fallback to git hooks) | `.kilocode/rules/` + `.git/hooks/` |
+| **OpenCode** | ✅ TypeScript plugins | `AGENTS.md` + `opencode.json` + TS plugin |
+| **Codex** (OpenAI) | ✅ Experimental | `AGENTS.md` + `.codex/config.toml` + `hooks.json` |
+| **Pi Code** | Dual-mode (skill / AGENTS.md) | `~/.pi/skills/memory-bank/` or `AGENTS.md` |
+
+`AGENTS.md` is shared across OpenCode, Codex, Pi — ownership is refcount-tracked, so uninstalling one client doesn't break the others.
+
+---
+
+## Usage examples
+
+### Starting a new feature
+
+```
+You: /mb plan feature user-auth
+
+Agent: [creates .memory-bank/plans/2026-04-20_feature_user-auth.md with DoD,
+        test plan, stage breakdown, dependencies]
+
+You: Now implement stage 1.
+
+Agent: [reads plan, writes failing tests first (TDD), then implementation,
+        runs tests, updates checklist ⬜ → ✅]
+
+You: /mb verify
+
+Agent: [plan-verifier agent checks that implementation matches plan DoD]
+
+You: /mb done
+
+Agent: [appends session summary to progress.md, updates STATUS.md if needed]
+```
+
+### Jumping into an existing project
+
+```bash
+cd some-legacy-project/
+memory-bank install --clients cursor   # adds .cursor/ adapter
+
+# In Cursor:
+/mb init --full                         # auto-detect stack, generate CLAUDE.md
+/mb start                               # load everything
+```
+
+### Sharing state with your team
+
+`.memory-bank/` is just markdown. Commit it. Your colleague clones the repo, runs `/mb start`, and has the full project context without asking you a single question.
+
+---
+
+## CLI reference
+
+After `pipx install memory-bank-skill`:
+
+```bash
+memory-bank install [--clients <list>] [--project-root <path>]
+memory-bank uninstall
+memory-bank init                    # prints /mb init hint
+memory-bank version
+memory-bank self-update             # prints `pipx upgrade ...`
+memory-bank doctor                  # resolves bundle, platform info
+memory-bank --help
+```
+
+Flags:
+- `--clients <list>` — comma-separated. Valid: `claude-code, cursor, windsurf, cline, kilo, opencode, pi, codex`. Default: `claude-code` only.
+- `--project-root <path>` — where to place client-specific adapters. Default: current directory.
+
+---
+
+## Environment variables
+
+| Variable | Purpose | Default |
+|----------|---------|---------|
+| `MB_AUTO_CAPTURE` | SessionEnd auto-capture mode: `auto` / `strict` / `off` | `auto` |
+| `MB_COMPACT_REMIND` | Weekly `/mb compact` reminder: `auto` / `off` | `auto` |
+| `MB_PI_MODE` | Pi adapter mode: `agents-md` / `skill` | `agents-md` |
+| `MB_SKILL_BUNDLE` | Override bundle path (dev / testing) | auto-detected |
+| `MB_SKIP_DEPS_CHECK` | Skip preflight dep check in `install.sh` | `0` |
+
+---
+
+## Platform support
+
+| OS | Status |
+|----|--------|
+| macOS | ✅ Full |
+| Linux | ✅ Full |
+| Windows | ⚠️ WSL only (bash required) |
+
+Running native Windows prints a WSL hint and exits. Use WSL: `wsl --install`, then install from inside WSL.
+
+---
+
+## FAQ
+
+**Q: Do I need to commit `.memory-bank/` to git?**
+A: Recommended if working in a team — that's how state is shared. Solo project: optional. Either way works.
+
+**Q: Does this replace Claude Code's built-in memory?**
+A: No — complementary. Native memory is per-user, cross-project (preferences, style). `.memory-bank/` is per-project, team-shared (status, plans, decisions). Both load simultaneously.
+
+**Q: Will it work on private repositories?**
+A: Yes. Everything is local. No data sent anywhere unless your AI agent itself calls external APIs (that's unchanged).
+
+**Q: What if my team uses different AI agents?**
+A: That's the whole point. Install per-client: `memory-bank install --clients cursor,windsurf,claude-code`. One memory bank, everyone reads it.
+
+**Q: Cursor hooks are experimental / Codex hooks are experimental — is that a problem?**
+A: Partial — where native hooks don't exist or aren't stable, we ship graceful fallbacks (git hooks for Kilo; `AGENTS.md` fallback for Pi). See [docs/cross-agent-setup.md](docs/cross-agent-setup.md) for specifics.
+
+**Q: My existing `AGENTS.md` / `.cursor/hooks.json` — will this overwrite them?**
+A: No. Adapters use a marker pattern (`<!-- memory-bank:start/end -->` for MD files, `_mb_owned: true` for JSON hooks) and merge idempotently. User content is preserved; uninstall only removes MB-owned sections.
+
+**Q: How do I upgrade?**
+A: `pipx upgrade memory-bank-skill` or `brew upgrade memory-bank`. Git-clone install: `cd ~/.claude/skills/skill-memory-bank && git pull && ./install.sh`.
+
+**Q: I want to remove everything.**
+A: `memory-bank uninstall` removes global install. Per-project adapters: `adapters/<client>.sh uninstall <project-dir>` (or drop the `.memory-bank/`, `.cursor/`, etc. directories manually).
+
+**Q: Is this production-ready?**
+A: Current version is a release candidate (`3.0.0-rc1`). Daily used on real projects. 461 automated tests green (bats + pytest). Stable API; rc only because we want 1-2 weeks of real-world usage before the stable tag.
+
+---
+
+## Documentation
+
+- **[Cross-agent setup](docs/cross-agent-setup.md)** — per-client cheatsheet + hook capability matrix
+- **[Install guide](docs/install.md)** — pipx / Homebrew / git-clone with troubleshooting
+- **[Repository migration](docs/repo-migration.md)** — for users upgrading from `claude-skill-memory-bank`
+- **[Release process](docs/release-process.md)** — PyPI OIDC setup + tag workflow
+- **[CHANGELOG](CHANGELOG.md)** — version history
+
+---
+
+## Contributing
+
+1. Fork & clone.
+2. `./install.sh && /mb init` in the repo itself (this skill uses itself — meta but works).
+3. Write tests first (TDD). `bats tests/bats/ tests/e2e/` + `python3 -m pytest tests/pytest/`.
+4. Follow the rules in `rules/RULES.md` (the same ones the skill enforces on users).
+5. Open a PR. CI runs on Python 3.11 + 3.12 × ubuntu + macos.
+
+## License
+
+MIT. See [LICENSE](LICENSE).
+
+## Links
+
+- **Repo:** https://github.com/fockus/skill-memory-bank
+- **PyPI:** https://pypi.org/project/memory-bank-skill/
+- **Homebrew tap:** https://github.com/fockus/homebrew-tap
+- **Issues:** https://github.com/fockus/skill-memory-bank/issues