From dbd80e97153738ca2000ababc49c19a7f883196d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=D0=94=D0=BC=D0=B8=D1=82=D1=80=D0=B8=D0=B9?= Date: Mon, 11 May 2026 13:39:50 +0300 Subject: [PATCH] docs(brain-plugin-routing): design spec for plugin selection rules MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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) --- .../2026-05-11-brain-plugin-routing-design.md | 261 ++++++++++++++++++ 1 file changed, 261 insertions(+) create mode 100644 docs/superpowers/specs/2026-05-11-brain-plugin-routing-design.md diff --git a/docs/superpowers/specs/2026-05-11-brain-plugin-routing-design.md b/docs/superpowers/specs/2026-05-11-brain-plugin-routing-design.md new file mode 100644 index 0000000..6881d34 --- /dev/null +++ b/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 ~/.claude/plugins/cache///`; preferred-future = `claude plugin install @` после установки 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.*