docs(brain-plugin-routing): design spec for plugin selection rules

Brainstorming output for resolving 8 sources of ambiguity (К1-К8) when
selecting a plugin while working inside brain repo. Approach A chosen
(separate docs/brain-plugin-routing.md ~275 lines). Decisions D1-D12
locked. Implementation deferred to writing-plans skill.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

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

@@ -0,0 +1,261 @@
+# Brain Plugin Routing Rules — Design Spec
+
+**Дата:** 2026-05-11
+**Статус:** Draft → review заказчика
+**Автор:** Claude (под economy mode 0%)
+**Связано:**
+- [docs/brain-v2-phase-0-final.md](../../brain-v2-phase-0-final.md) — Phase 0 финальный отчёт, источник Hybrid-решения skill-creator vs writing-skills
+- [CLAUDE.md](../../../CLAUDE.md) — основная карта brain'а (получит ссылку на этот документ при implementation)
+- [project-files/docs/Plugin_stack_rules.template.md](../../../project-files/docs/Plugin_stack_rules.template.md) — PSR для consumer'а (Liderra), **не применяется** к brain'у
+- Memory: [project_brain_v2_phase0.md](../../../../../Users/Administrator/.claude/projects/c--------------claude-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.*