brain/docs/superpowers/specs/2026-05-11-brain-plugin-routing-design.md

Brain Plugin Routing Rules — Design Spec

Дата: 2026-05-11 Статус: Draft → review заказчика Автор: Claude (под economy mode 0%) Связано:

• docs/brain-v2-phase-0-final.md — Phase 0 финальный отчёт, источник Hybrid-решения skill-creator vs writing-skills
• CLAUDE.md — основная карта brain'а (получит ссылку на этот документ при implementation)
• project-files/docs/Plugin_stack_rules.template.md — PSR для consumer'а (Liderra), не применяется к brain'у
• Memory: project_brain_v2_phase0.md — shortlist 17

---

§1. Цель и проблема

§1.1. Проблема

В brain repo (c:/моя/проекты/claude-brain/) сейчас активны 6 плагинов (4 brain v1.0 baseline + 2 мета Phase 0). При выборе какой плагин использовать для конкретной задачи в brain'е возникает запутанность. Зафиксированы 8 источников запутанности:

• К1. У brain нет собственных правил выбора плагина. PSR template (916 строк) — правила для consumer'а с Vue/Vuetify/Forest стеком, в brain'е неприменимы. CLAUDE.md brain'а (40 строк) plugin-правил не содержит.
• К2. В enabledPlugins brain'а активны frontend-design + ui-ux-pro-max — UI-плагины, не нужные в brain'е. Skill tool показывает их скилы, отвлекая attention.
• К3. Phase 0 install (skill-creator + claude-code-setup) выполнен Path 2 (manual git clone) — нативный workflow /plugin install сломан, drift между фактическим состоянием и brain'ской source-of-truth.
• К4. Overlap'ы между плагинами без правил «какой когда»: skill-creator vs writing-skills, claude-md-improver vs прямой Edit, code-review (community) vs /review vs requesting-code-review, security-guidance vs /security-review vs Semgrep, claude-code-setup vs ручной анализ.
• К5. 17 плагинов shortlist'а Phase 0 не имеют категоризации «куда ставить» — каждый install ad-hoc.
• К6. Нет механизма live-override / disabled-in-brain.
• К7. Установка одного плагина = 6 артефактов (cache, settings.json, installed_plugins.json, brain plugins-manifest.json, marketplaces.json, settings-fragment.json) — нет atomic-checklist'а, шаги 4-6 при Path 2 пропускаются.
• К8. Категория плагина (meta / UI / process / domain) нигде не маркирована.

§1.2. Цель

Создать docs/brain-plugin-routing.md v1.0 — нормативный документ, который:

1. Заменяет ad-hoc решения routing'ом по реестру (К4)
2. Категоризирует плагины и определяет где какой ставить (К5, К8)
3. Маркирует disabled-in-brain через soft-rule (К2)
4. Описывает atomic install checklist (К3, К7)
5. Описывает update procedure при добавлении нового плагина (К1, К6)

Размер: ~250 строк, в 4× меньше PSR template.

§1.3. Принципы

• Brain ≠ consumer. Правила brain'а отличаются от PSR template'а consumer'а.
• Один путь поиска. Все вопросы про плагины в brain'е решаются по этому документу.
• Реалистично, без чрезмерности. Нет R0-R15 как в PSR; достаточно: реестр + routing + disabled + categorization + install + update.

---

§2. Scope

§2.1. В scope

• Создание docs/brain-plugin-routing.md v1.0
• Обновление CLAUDE.md brain'а — добавление 5-7 строк ссылки на новый документ
• Возможно: новое опциональное поле target в plugins-manifest.json schema (см. §5)
• Возможно: новый раздел в docs/rejected-plugins.md для категории skip
• Возможно: новый файл docs/consumer-projects.md дополняется для consumer-stack-gated плагинов (если потребуется)

§2.2. Вне scope

• Не меняем PSR template (project-files/docs/Plugin_stack_rules.template.md) — это template для consumer'а, brain не управляет consumer-правилами через этот документ
• Не меняем CLAUDE.md template (project-files/CLAUDE.md.template) — это для consumer'а
• Не меняем настройки плагинов на user-level (~/.claude/settings.json) — это runtime, brain копирует через settings-fragment.json
• Не пишем правила установки PSR-аналогов для brain'а (Tooling/Pravila для brain'а) — отложено, brain пока не требует
• Не автоматизируем install через скрипт на этом этапе — checklist в документе достаточен; автоматизация — отдельная задача

---

§3. Архитектура документа

docs/brain-plugin-routing.md будет иметь 7 разделов:

#	Раздел	Назначение	Размер
1	Шапка + Принципы	основа документа, scope, отделение от PSR	~30 строк
2	Реестр активных плагинов + Disabled-in-brain	таблица 6 плагинов + soft-rule для FD/UPM	~40 строк
3	Routing table	17 строк task→plugin disambiguation + tie-breakers	~50 строк
4	Categorization shortlist 17	5 категорий + распределение всех известных плагинов	~50 строк
5	Install checklist	5 подразделов по категориям (meta/consumer-universal/stack-gated/UI/skip)	~60 строк
6	Update procedure	когда менять, bump strategy, согласованность	~25 строк
7	Финальная формула + Свойства	TL;DR и meta	~20 строк

Итого: ~275 строк (target 250 ± 25).

§3.1. Раздел 1 — Шапка + Принципы

Содержит:

• Дата, версия v1.0, scope (только brain repo)
• Связи: CLAUDE.md (ссылка сюда), PSR template (НЕ применяется к brain'у)
• 3 принципа: «Brain ≠ consumer», «Один путь поиска», «Реалистично, без чрезмерности»

§3.2. Раздел 2 — Реестр + Disabled-in-brain

Реестр 2.1 — таблица 6 плагинов:

• superpowers → process
• claude-md-management → meta
• skill-creator → meta
• claude-code-setup → meta
• frontend-design → consumer-UI
• ui-ux-pro-max → consumer-UI

Колонки: плагин, marketplace, категория, когда использовать в brain, когда не использовать.

Disabled-in-brain 2.2 — soft-rule:

• FD/UPM остаются enabledPlugins: true на user-level
• При работе в brain repo (триггер: pwd начинается с c:/моя/проекты/claude-brain/) — модель самостоятельно игнорирует FD/UPM, не инвокирует их Skill tool'ом
• Edge case структурной правки visualization HTML: разрешено «открыть новый чат и явно использовать FD»; маленькие правки — прямой Edit без FD

§3.3. Раздел 3 — Routing table (К4)

Таблица 17 строк × 4 колонки (Задача / Default / Override+Триггер / Почему default). Покрывает:

1. Создание custom skill — verifiable output → skill-creator
2. Создание custom skill — discipline-enforcing → superpowers:writing-skills
3. Создание custom skill — hybrid → superpowers:brainstorming → определение типа
4. Правка CLAUDE.md → claude-md-management:claude-md-improver (override: тривиал → прямой Edit)
5. Capture session-learnings → revise-claude-md
6. Правка Pravila/PSR/Tooling template'ов → прямой Edit + writing-skills pressure если структурная
7. Анализ «что ещё поставить» → claude-code-setup:claude-automation-recommender
8. Code review → superpowers:requesting-code-review (override: /review, /simplify по live-команде)
9. Debug → superpowers:systematic-debugging (≥3 гипотезы)
10. Планирование multi-step → superpowers:writing-plans (после brainstorming)
11. Закрытие задачи → superpowers:verification-before-completion
12. Параллельная работа → superpowers:dispatching-parallel-agents
13. Worktree-изоляция → superpowers:using-git-worktrees
14. Завершение feature-branch → superpowers:finishing-a-development-branch
15. Receive code review → superpowers:receiving-code-review
16. TDD на код → superpowers:test-driven-development
17. «Запутался — какой брать» → читать этот документ; если нет строки — спросить + добавить через bump

Tie-breakers (3 строки):

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

§3.4. Раздел 4 — Categorization (К5, К8)

4.1. Категории (5 штук):

• meta — для самого brain
• consumer-universal — универсально для любого consumer'а
• consumer-stack-gated — стек-зависимое
• consumer-UI — UI plugin (legacy + future)
• skip — не подходит

4.2. Распределение — таблица из 22 строк: 4 legacy brain v1.0 + 17 shortlist Phase 0 + 1 cut (#3, поглощён #10):

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

4.3. Правило установки нового плагина — категоризируй по 4.1 → install по §5 соответствующей подсекции.

§3.5. Раздел 5 — Install checklist (К3, К7)

5 подразделов:

• 5.1. meta — 10 шагов: marketplace add, plugin install (на этой машине claude CLI не установлен (см. Phase 0 final.md Path 2), поэтому primary = git clone --depth=1 <repo-url> ~/.claude/plugins/cache/<marketplace>/<name>/<version>; preferred-future = claude plugin install <name>@<marketplace> после установки CLI), enable settings.json, manifest entry, brain plugins-manifest, brain marketplaces, brain settings-fragment, обновить routing.md, verify в новой сессии, atomic commit
• 5.2. consumer-universal — 6 шагов: marketplace, brain manifest со target: "consumer", не добавлять в brain settings-fragment, обновить routing.md, bump install.sh, commit
• 5.3. consumer-stack-gated — как 5.2 + фиксация в docs/consumer-projects.md подходящих стеков
• 5.4. consumer-UI — sub-case 5.2 с target: "user-level + consumer", в brain settings-fragment содержится (как сейчас FD/UPM)
• 5.5. skip — запись в docs/rejected-plugins.md с причиной

Изменение схемы: plugins-manifest.json получает опциональное поле target (default "user-level" для backwards compat).

§3.6. Раздел 6 — Update procedure

6.1. События триггерящие обновление документа. 6.2. Bump strategy: minor (новая строка), major (смена структуры/принципов). 6.3. Согласованность с другими документами brain'а (manifest/marketplaces/settings-fragment обновляются в том же commit'е). 6.4. Edge case — старая категория не подходит → brainstorming → новая категория → bump v2.0.

§3.7. Раздел 7 — Финальная формула

Задача в brain → routing-table §3 → найди строку → default или override.
Не нашёл → спроси + добавь через bump §6.1.
Установка → §5 по категории.
В сомнениях категории → §4.1 признаки → §6.4 если ни одна не подходит.
В brain repo → FD + UPM игнорируются (§2.2).

Свойства: полнота, соразмерность, самоподдержка, независимость от PSR/CLAUDE.md template'ов.

---

§4. Decisions log

Зафиксированные решения с источниками:

#	Решение	Обоснование
D1	Отдельный документ docs/brain-plugin-routing.md (Approach A), не expansion CLAUDE.md (Approach C), не port PSR (Approach B)	brainstorming: средний вес, separable, не разрастает CLAUDE.md, не imitate Liderra
D2	Disabled-in-brain — soft-rule, не physical disable через settings.local.json	пользователь: «игнорирует»
D3	Install checklist — в brain-plugin-routing.md отдельным разделом, не в отдельном installing-a-plugin.md	пользователь: «а» (вариант a)
D4	5 категорий: meta / consumer-universal / consumer-stack-gated / consumer-UI / skip	self-discovered при ревью раздела 4 — consumer-UI была в реестре 2.1 но отсутствовала в 4.1
D5	Новое поле target в plugins-manifest.json — opt-in (default "user-level")	дефолт: backwards compat с 4 текущими entries
D6	Bump strategy — semver minor/major	дефолт: соответствует PSR (v1.0 → v1.1 minor); calendar-version используется отдельно для .brain-version всего репо
D7	Documemt full coverage без сокращений (~275 строк target)	дефолт: пользователь не попросил сокращать
D8	Override-flag для overlap'а skill-creator vs writing-skills — задача-тип признак (verifiable output vs discipline-enforcing), hybrid → brainstorming	источник: Phase 0 final.md решение
D9	Поле target в plugins-manifest.json — string ENUM: "user-level", "consumer", "user-level+consumer". Default при отсутствии = "user-level" (для backwards compat с 4 текущими entries)	self-discovered при self-review §3.5 5.4 — consumer-UI требует композитного значения; ENUM проще массива для validation в jq
D10	docs/rejected-plugins.md — отложить создание до 19-го плагина с категорией skip; atomic-agents + pagerduty (Phase 0 rejected) пока упомянуты в §4.2 brain-plugin-routing.md как skip со ссылкой на Phase 0 final.md	дефолт пользователя «делай сам»; KISS — не плодить пустой документ
D11	.brain-version bump v1.0 → v1.1 при коммите brain-plugin-routing.md v1.0 + CLAUDE.md update (атомарный bump)	дефолт пользователя «делай сам»; согласовано с CHANGELOG.md как «v1.1 — added brain plugin routing rules»
D12	Тестирование документа v1.0 — review only; pressure-scenarios через superpowers:writing-skills отложены до проявления реальной нестабильности правил при использовании	дефолт пользователя «делай сам»; новый документ — не код, RED-GREEN-REFACTOR неприменим напрямую; review достаточен для нормативного markdown'а

---

§5. Изменения в репозитории

При implementation создаются/правятся:

Артефакт	Действие	Размер
docs/brain-plugin-routing.md	CREATE	~275 строк
CLAUDE.md (brain root)	UPDATE	+5-7 строк (ссылка на новый документ + 1-2 строки sumary)
user-level-files/plugins-manifest.json	UPDATE	добавить optional target поле в существующие entries (default "user-level" где нет нового маркетплейс'а; "meta" для skill-creator + claude-code-setup которые сейчас отсутствуют в файле)
user-level-files/settings-fragment.json	UPDATE	добавить skill-creator + claude-code-setup в enabledPlugins (как сейчас в ~/.claude/settings.json после Phase 0)
user-level-files/marketplaces.json	NO CHANGE	claude-plugins-official уже есть (skill-creator/claude-code-setup из того же marketplace)
docs/rejected-plugins.md	CREATE (optional)	~10 строк, для atomic-agents + pagerduty
docs/superpowers/specs/2026-05-11-brain-plugin-routing-design.md	CREATE (этот файл)	—

---

§6. Открытые вопросы — закрыты дефолтами «делай сам»

• Q1 → D10: docs/rejected-plugins.md отложен до 19-го skip плагина
• Q2 → D11: .brain-version v1.0 → v1.1 атомарно с этим коммитом
• Q3 → D12: review-only тестирование для v1.0; pressure-scenarios отложены

---

§7. Свойства spec'а

• Полнота: §1 проблема + §2 scope + §3 архитектура документа (7 разделов с под-структурой) + §4 decisions log (8 решений) + §5 changeset + §6 открытые вопросы.
• Внутренняя согласованность: D1-D9 не противоречат, §3 совпадает с обсуждавшимися разделами в brainstorming, §5 changeset покрывает все артефакты в §2 in-scope.
• Без placeholders: проверено self-review (см. ниже).
• Scope чёткий: §2.2 явно перечисляет out-of-scope.

---

Конец Design Spec.