fockus Memory Bank Skill
Three-in-one skill for code agents:
- Memory Bank — long-term project memory through
.memory-bank/(STATUS,plan,checklist,RESEARCH,BACKLOG,progress,lessons,notes/,plans/,experiments/,reports/,codebase/). - RULES — global engineering rules: TDD, Clean Architecture (backend), FSD (frontend), Mobile (iOS/Android UDF), SOLID, Testing Trophy.
- 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.mdfor 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.mdwith 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.mdhints + 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>(aliasask_me) ·groom <topic>(aliasgrooming) ·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
# 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.mdas 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:
- Explicit argument —
mb-*.sh <mb_path>always wins. MB_PATHenv override — for ad-hoc redirection in shell sessions.- Local mode —
<project>/.memory-bank/(default of/mb init, team-shared, committable). - Global mode — registered in
<agent_config>/memory-bank/registry.json. Requires--storage=global --agent=<name>on init (or$MB_AGENTenv). Per supported agent:claude-code→$HOME/.claude/memory-bank/projects/<id>/.memory-bankcursor→$HOME/.cursor/memory-bank/projects/<id>/.memory-bankcodex→$HOME/.codex/memory-bank/projects/<id>/.memory-bankopencode→$HOME/.config/opencode/memory-bank/projects/<id>/.memory-bankpi→$HOME/.pi/agent/memory-bank/projects/<id>/.memory-bankwindsurf/cline/kilo→ analogous under the respective config dir
- Legacy
.claude-workspace— kept for backward compatibility (storage: external+project_id: <id>→~/.claude/workspaces/<id>/.memory-bank). New projects should use--storage=globalinstead. - 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:
/mblifecycle 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)