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](../CLAUDE.md) — оперативная карта brain'а, содержит ссылку сюда
- [project-files/docs/Plugin_stack_rules.template.md](../project-files/docs/Plugin_stack_rules.template.md) — PSR для consumer'а; **НЕ применяется** к brain'у
- [docs/superpowers/specs/2026-05-11-brain-plugin-routing-design.md](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)](../project-files/CLAUDE.md.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](superpowers/specs/2026-05-11-brain-plugin-routing-design.md). 5 категорий плагинов, 17 routing-rows + 3 tie-breakers, 5 install подпроцедур, update procedure. Implements decisions D1-D12 design spec'а.