brain/docs/brain-plugin-routing.md

Brain Plugin Routing Rules (v1.1)

Дата: 11.05.2026 Назначение: правила выбора плагина при работе в brain repo (c:/моя/проекты/claude-brain/). Scope: только сам brain repo. Для consumer-проектов (Liderra и будущие) действуют их собственные правила (PSR template, который brain копирует в consumer). Связано:

• CLAUDE.md — оперативная карта brain'а, содержит ссылку сюда
• project-files/docs/Plugin_stack_rules.template.md — PSR для consumer'а; НЕ применяется к brain'у
• docs/superpowers/specs/2026-05-11-brain-plugin-routing-design.md — design spec этого документа

---

§1. Принципы

Brain ≠ consumer. PSR template (916 строк) описывает координацию плагинов в consumer'е c Vue/Vuetify/Forest стеком. Эти правила НЕ применяются к работе в самом brain — у brain нет UI-задач, нет TDD-кода, нет фаз 1-7 UI-фичи. Brain — это «инфраструктурный distributor», и правила выбора плагина здесь другие.

Один путь поиска. Все вопросы про плагины в brain'е (какой использовать, как поставить новый, что отключить) — решаются по этому документу. Если документ не покрывает — добавь сюда строку через bump v1.x, не плоди ad-hoc решения.

Реалистично, без чрезмерности. В brain'е работает один человек + Claude. Не нужны R0-R15 как в PSR. Достаточно: реестр, routing, disabled-in-brain, categorization, install checklist, update procedure.

---

§2. Реестр активных плагинов + Disabled-in-brain

§2.1. Реестр (6 плагинов после Phase 0)

Плагин	Marketplace	Категория	Когда использовать в brain	Когда не использовать
superpowers	obra/superpowers	process	каждая нетривиальная задача (brainstorming, writing-plans, TDD, debugging, verification, code-review)	тривиальная правка опечатки / cross-ref / version-bump
claude-md-management	anthropics/claude-plugins-official	meta	любая правка CLAUDE.md (brain или consumer template); session-learnings через revise-claude-md	правка Pravila/PSR/Tooling template'ов (другой инструмент — прямой Edit + writing-skills pressure если структурная)
skill-creator	anthropics/claude-plugins-official	meta	создание custom skill для brain с verifiable output (codegen, transform, validation)	создание discipline-enforcing скила — там superpowers:writing-skills
claude-code-setup (claude-automation-recommender)	anthropics/claude-plugins-official	meta	анализ «какие плагины/хуки ещё поставить в brain» при росте репо	каждодневная работа
plugin-dev	anthropics/claude-plugins-official	meta	создание нового plugin'а в brain'е (agents/commands/hooks/MCP integration); тест-bed для будущих brain плагинов	каждодневная UI/code работа
hookify	anthropics/claude-plugins-official	meta	создание нового hook'а в brain by analyzing conversation patterns; complement к 10 ручным .py hook'ам в user-level-files/hooks/	каждодневная работа
frontend-design	anthropics/claude-plugins-official	consumer-UI	❌ не использовать в brain'е (см. §2.2)	весь brain
ui-ux-pro-max	nextlevelbuilder/ui-ux-pro-max-skill	consumer-UI	❌ не использовать в brain'е (см. §2.2)	весь brain

§2.2. Disabled-in-brain (soft-rule)

frontend-design и ui-ux-pro-max остаются enabledPlugins: true на user-level — нужны:

1. при работе в Liderra (там UI-задачи, регламентирует PSR R10),
2. как template'ные зависимости для будущих consumer'ов.

Но в самом brain repo они не используются. Модель самостоятельно их игнорирует, не инвокирует Skill tool на их скилы. Технически плагины активны — в brain mental model выключены.

Триггер soft-rule: рабочий путь начинается с c:/моя/проекты/claude-brain/. При этой проверке — FD/UPM «вне scope».

Edge case — структурная правка visualization HTML (project-files/docs/visualizations/hooks-skills-plugins-map.html):

• маленькая правка (узел, цвет, текст) — прямой Edit без FD
• структурная (новая раскладка, новое представление) — открыть новый чат, явно сказать «использую FD для этой правки visualization», и считать FD активным только на этот один файл

---

§3. Routing table

§3.1. Disambiguation overlap'ов

Задача в brain	Default	Допустимый override + триггер	Почему default
Создание custom skill — verifiable output (codegen, transform, validation)	skill-creator	superpowers:writing-skills если discipline-составляющая преобладает	eval-loop с train/test 60/40 + iterative refinement работает на проверяемых outputs
Создание custom skill — discipline-enforcing (TDD-like, review-like, verify-like)	superpowers:writing-skills	skill-creator если output становится явно verifiable (hook generator и т.п.)	RED-GREEN-REFACTOR pressure scenarios + bulletproofing
Создание custom skill — hybrid	superpowers:brainstorming → определить ведущий тип → дальше по строкам выше	—	brainstorming сам решает тип
Правка CLAUDE.md (brain или consumer template)	claude-md-management:claude-md-improver	прямой Edit только для: cross-ref bump, version-bump, опечатка	формально требуется по CLAUDE.md §5 п.10 (template); тривиал-override снимает overkill
Capture session-learnings → CLAUDE.md	claude-md-management:revise-claude-md	—	специально под эту задачу
Правка Pravila/PSR/Tooling template'ов	прямой Edit (template — не CLAUDE.md, claude-md-improver неприменим) + superpowers:writing-skills pressure если структурная	—	улучшитель для не-CLAUDE.md в brain отсутствует
Анализ «что ещё поставить в brain»	claude-code-setup:claude-automation-recommender	ручной анализ если recommender дал «не знаю»	внешняя валидация ручного shortlist'а; уже доказал value (нашёл #17 plugin-dev + #18 hookify)
Создание нового plugin'а для brain (agents/commands/hooks/MCP integration)	plugin-dev	прямое создание .claude-plugin/plugin.json + skills если plugin тривиальный (1 skill, без агентов и hooks)	guided plugin scaffolding с Anthropic best practices
Создание нового hook'а в brain (PreToolUse/PostToolUse/Stop/SessionStart/UserPromptSubmit)	hookify	прямой Edit .py файла в user-level-files/hooks/ если простой port существующего паттерна или hook тривиален	guided hook generation by analyzing conversation patterns
Code review brain-кода (hooks .py, scripts.sh, install.sh)	superpowers:requesting-code-review	/review или /simplify только при явной user-команде	process-discipline + многоаспектный обзор; built-in tools — single-shot
Debug (hook не работает, install.sh fails, MCP не отвечает)	superpowers:systematic-debugging (≥3 гипотезы, falsify каждую)	—	hard-required по economy 0%
Планирование multi-step задачи в brain	superpowers:writing-plans (после brainstorming)	прямой Edit с TodoWrite только для ≤2 шагов	для длинных задач — full spec в docs/superpowers/specs/
Закрытие задачи (commit, tag, push)	superpowers:verification-before-completion	—	hard-rule перед claim 'готово' по economy 0%; economy-verifier hook это проверит
Параллельная работа (независимые исследования)	superpowers:dispatching-parallel-agents	—	один tool
Worktree-изоляция (эксперимент, feature-branch)	superpowers:using-git-worktrees	—	один tool
Завершение feature-branch	superpowers:finishing-a-development-branch	—	один tool
Receive code review	superpowers:receiving-code-review	—	один tool
TDD на код hook'а / скрипта	superpowers:test-driven-development (failing test first)	—	hard-required по economy 0%
«Запутался — какой плагин брать» (meta-question)	прочитать этот документ; если строки нет — спросить + добавить через bump v1.x (см. §6.1)	—	self-referential: правила указывают на самих себя

§3.2. Tie-breakers

1. Несколько строк подходят одновременно — побеждает более конкретная по задаче. Equal confidence → спросить пользователя.
2. Economy mode 0% триггер требует skill X, default говорит Y — побеждает economy 0% (live-override).
3. User написал /skill-name явно — выполнить именно его (live-override на одно действие).

---

§4. Categorization

Решает «куда ставить плагин» и «где какой плагин относится».

§4.1. Категории

Категория	Где ставить	Где НЕ ставить	Признак
meta	brain enabledPlugins + brain plugins-manifest.json (target = user-level)	consumer	работает над plugin/skill/hook инфраструктурой Claude Code
consumer-universal	template install для любого consumer'а через scripts/install.sh (target = consumer)	brain	Claude Code workflow tool, не зависит от стека
consumer-stack-gated	template install только для consumer'а с подходящим стеком	brain + consumer без стека	привязан к Vercel/Supabase/Figma/HuggingFace/Vue+spec
consumer-UI	user-level enabledPlugins (нужен в Liderra) + brain manifest target = user-level+consumer	внутри brain — soft-ignore по §2.2	UI/UX domain plugin
skip	нигде	везде	не подходит по результату анализа

§4.2. Распределение (4 legacy + 17 shortlist Phase 0 + 1 cut = 22 строки)

#	Plugin	Категория	Статус
legacy	superpowers	process	installed brain v1.0
legacy	claude-md-management	meta	installed brain v1.0
legacy	frontend-design	consumer-UI	installed brain v1.0 (но disabled-in-brain §2.2)
legacy	ui-ux-pro-max	consumer-UI	installed brain v1.0 (но disabled-in-brain §2.2)
#4	skill-creator	meta	installed Phase 0 (manual-git-clone-Path2)
#8	claude-code-setup	meta	installed Phase 0 (manual-git-clone-Path2)
#17	plugin-dev	meta	installed brain v1.2 (manual-cp-from-marketplace-Path2)
#18	hookify	meta	installed brain v1.2 (manual-cp-from-marketplace-Path2)
#1	Context7 (MCP)	consumer-universal	shortlist Phase 1
#2	code-review	consumer-universal	shortlist Phase 1
#7	security-guidance	consumer-universal	shortlist Phase 1
#10	pr-review-toolkit	consumer-universal	shortlist Phase 1
#12	telegram	consumer-universal	shortlist Phase 1
#5	feature-dev	consumer-stack-gated	shortlist Phase 2 conditional
#6	figma	consumer-stack-gated (requires Figma)	shortlist Phase 2 conditional
#9	vercel	consumer-stack-gated (requires Vercel)	shortlist Phase 2 conditional
#11	supabase	consumer-stack-gated (requires Supabase)	shortlist Phase 2 conditional
#13	huggingface-skills	consumer-stack-gated (requires HF/ML)	shortlist Phase 2 conditional
#15	data-engineering	consumer-stack-gated (requires DWH/Airflow/dbt)	shortlist Phase 2 conditional
#14	atomic-agents	skip	rejected — Python ML mismatch, community marketplace
#16	pagerduty	skip	rejected — paid enterprise, не используется
#3	code-simplifier	cut (поглощён #10)	excluded из shortlist

§4.3. Правило установки нового (19-го) плагина

1. Определить категорию по признаку в §4.1
2. Если meta → поставить в brain по §5.1, добавить строку в реестр §2.1, добавить строку в §4.2
3. Если consumer-universal → §5.2
4. Если consumer-stack-gated → §5.3
5. Если consumer-UI → §5.4
6. Если skip → §5.5

---

§5. Install checklist (atomic, 6 артефактов)

§5.1. Категория meta — полная установка в brain

Цель: плагин активен в ~/.claude/ И зафиксирован в brain'е как source-of-truth.

#	Действие	Артефакт	Verify
1	Marketplace уже добавлен?	check ~/.claude/plugins/known_marketplaces.json	если новый → 1a
1a	Добавить marketplace	claude marketplace add <repo> или manual edit ~/.claude/plugins/known_marketplaces.json + brain user-level-files/marketplaces.json	обе записи совпадают
2	Установить плагин	На этой машине claude CLI не установлен (Phase 0 forced Path 2) — primary = git clone --depth=1 <repo-url> ~/.claude/plugins/cache/<marketplace>/<name>/<version>. Preferred-future = claude plugin install <name>@<marketplace> после установки CLI	директория есть, SKILL.md/plugin.json present
3	Enable	edit ~/.claude/settings.json → "<name>@<marketplace>": true в enabledPlugins	Skill tool видит скилы в новой сессии
4	User-level manifest	edit ~/.claude/plugins/installed_plugins.json → новый entry со scope, installPath, version, installedAt, lastUpdated, gitCommitSha (или installMethod: "manual-git-clone-Path2")	jq валидируется
5	Brain snapshot 1/3	edit user-level-files/plugins-manifest.json → entry со всеми полями + target (per §4.1) + category	jq валидируется
6	Brain snapshot 2/3	edit user-level-files/marketplaces.json (если шаг 1a)	jq валидируется
7	Brain snapshot 3/3	edit user-level-files/settings-fragment.json → key в enabledPlugins	jq валидируется
8	Обновить routing.md	bump v1.x + строка в §2.1 + строка в §4.2 + строки в §3.1 если плагин решает новый класс задач	документ согласован
9	Verify	в новой сессии: Skill('<name>') отвечает	OK
10	Commit atomic	git add 4 brain-файла + routing.md + commit message feat(brain-plugins): install <name> as meta plugin (v1.x)	1 commit

Pre-conditions: категория meta ✓; marketplace Anthropic-verified ИЛИ explicit user-approve; нет конфликта в §3.1.

§5.2. Категория consumer-universal

Цель: плагин будет распространяться через scripts/install.sh в consumer'ов, но не активен в brain'е.

#	Действие	Артефакт
1	Marketplace в brain (если новый)	user-level-files/marketplaces.json
2	Manifest в brain	user-level-files/plugins-manifest.json со "target": "consumer" + "category": "consumer-universal"
3	Не добавлять в brain settings-fragment.json	—
4	Обновить routing.md	строка в §2.1 (с пометкой target=consumer) + §4.2
5	Bump scripts/install.sh если нужна логика установки в consumer	—
6	Commit atomic	feat(brain-plugins): register <name> for consumer install

Brain runtime не меняется. Плагин не активен в ~/.claude/settings.json brain'а. Если плагин нужен также пользователю — он отдельно edit'ит свой settings.json.

§5.3. Категория consumer-stack-gated

Аналогично §5.2 + шаг 4а: фиксировать в docs/consumer-projects.md для каких стеков подходит.

§5.4. Категория consumer-UI

Подвариант §5.2: установлен на user-level (нужен в Liderra), но в brain'е по §2.2 — игнорируется. Brain manifest target = "user-level+consumer". Brain settings-fragment.json содержит этот плагин (как сейчас FD, UPM).

§5.5. Категория skip

#	Действие	Артефакт
1	Запись причины пропуска	docs/rejected-plugins.md (создаётся при первой такой записи) или раздел «Rejected» в этом документе
2	Ничего больше не трогать	—

---

§6. Update procedure

§6.1. Когда менять документ

Событие	Что обновить
Новый плагин в shortlist / установлен	§2.1 + §4.2 + §3.1 (если новый класс задач) + bump v1.x
Новый класс задачи в brain'е, решающийся неоднозначно	§3.1 + bump v1.x
Старый плагин deprecated / удалён	§2.1 mark «deprecated», §4.2 → skip, §3.1 — заменить default'ы; bump v1.x или v2.0
Marketplace плагина reorganized	§2.1 column + manifest + commit
Solved конфликт routing → tie-breaker	§3.2 + bump v1.x
Изменение категории плагина	§2.1 + §4.2 + install шаги (§5.1↔§5.2) при следующем sync

§6.2. Bump strategy

• v1.x → v1.(x+1) (minor): новая строка в реестре/routing/§4.2; новая tie-breaker; коррекция формулировки.
• v1.x → v2.0 (major): смена структуры разделов; смена принципов; удаление целой категории.

§6.3. Согласованность с другими документами brain'а

При bump этого документа:

• если меняется категория плагина или add'ится новый → обновить user-level-files/plugins-manifest.json, marketplaces.json, settings-fragment.json в том же commit'е (см. §5.1 шаги 5-7).
• если изменения структурные → bump CLAUDE.md brain'а (короткая запись о новой структуре).
• ссылка из CLAUDE.md на этот документ — всегда v1.x+ (forward-compat).

§6.4. Edge case — старая категория не подходит для нового плагина

Если новый плагин не вписывается ни в одну из 5 категорий (meta / consumer-universal / consumer-stack-gated / consumer-UI / skip):

1. Не пытаться «подогнать» под существующую.
2. Сделать superpowers:brainstorming — обдумать что это за класс.
3. Если нужна новая категория — bump v2.0 + явный раздел в changelog почему.

---

§7. Финальная формула + свойства

§7.1. TL;DR

Задача в brain → §3.1 routing-table → найди строку → default или override.
Не нашёл строки → спроси пользователя + добавь строку через bump v1.x (§6.1).
Установка нового плагина → §5 по категории.
В сомнениях про категорию → §4.1 признаки → §6.4 если ни одна не подходит.
При работе в brain repo → frontend-design + ui-ux-pro-max игнорируются (§2.2).
Закрытие задачи → всегда `superpowers:verification-before-completion` перед claim 'готово'.

Применять немедленно: этот документ загружается через CLAUDE.md brain'а; при сомнении про любой плагин — открыть §3.1 первым шагом.

§7.2. Свойства документа

• Полнота: каждая задача brain'а маршрутизируется через §3.1; каждый плагин имеет категорию из §4.1; каждый install имеет процедуру из §5.
• Соразмерность: ~275 строк, в 4× меньше PSR template (916); brain — инфраструктурный distributor, не consumer с UI/TDD/brand.
• Самоподдержка: §6 описывает как обновлять документ при изменениях.
• Независимость: не пересекается с PSR template (тот для consumer'ов) и не дублирует CLAUDE.md (там короткая ссылка сюда).

---

История версий

• v1.1 от 2026-05-11 — Installed brain-meta plugins #17 plugin-dev + #18 hookify. Added 2 rows в §2.1 (реестр), 2 rows в §3.1 routing-table (новые классы задач: «создание plugin'а», «создание hook'а»), 2 status updates в §4.2 (#17 + #18 → installed brain v1.2).
• v1.0 от 2026-05-11 — Initial release. Resolves 8 sources of ambiguity (К1-К8) from design spec. 5 категорий плагинов, 17 routing-rows + 3 tie-breakers, 5 install подпроцедур, update procedure. Implements decisions D1-D12 design spec'а.