**Источник:** этот документ — копия design spec'а из Лидерры (2026-05-10-claude-brain-extraction-design.md) на момент bootstrap brain v1.0. Hard-link для future-reference.
**Главная цель:** выделить «мозг Claude» — переиспользуемый набор правил, хуков, плагинов и визуализаций — из репозитория Лидерры в **независимый артефакт**, чтобы:
1.**Лидерра не страдает.** Текущий код, схема, тесты и нормативка Лидерры остаются на месте без изменений (кроме одного маркер-файла `.brain-version`).
2.**Мозг развивается отдельно.** Эксперименты над хуками, новыми правилами, новыми плагинами идут в песочнице мозга и не ломают релизный пайплайн Лидерры.
3.**Мозг переиспользуется.** Будущие проекты Дмитрия подключают мозг через one-command sync и получают полный стек правил без копипаста.
4.**Версионируется.** Каждая ревизия мозга — теговая, с CHANGELOG, с обратимостью.
**Не цели (явно):**
- Не превращаем мозг в коммерческий продукт (private repo, только для Дмитрия).
- Не делаем мозг universal-for-any-team (правила содержат явные предпочтения Дмитрия — стиль коммуникации, mode 0% паттерн).
- Не автоматизируем продакшен-deploy мозга (sync ручной по команде).
---
## §2. Scope
### §2.1. В scope
**Артефакты, которые переезжают в brain repo (v1.0):**
| Тип | Файл сейчас (Лидерра) | Размер | Назначение |
|---|---|---|---|
| Meta | [CLAUDE.md](../../../../../CLAUDE.md) | 266 строк | Оперативная карта Claude Code |
| Rules | [docs/Pravila_raboty_Claude_v1_1.md](../../Pravila_raboty_Claude_v1_1.md) | 720 строк | 13 продуктовых правил Claude |
- **Не переезжает:** `db/schema.sql`, ТЗ Лидерры, brandbook, handoff, supplier-specs, реализация моделей/views/тестов Лидерры — это **content проекта**, не «мозг».
- **Не переезжает:** memory-файлы (`~/.claude/projects/<liderra-hash>/memory/*.md`) — они per-project per-conversation, не часть мозга.
- **Не переезжает:** `~/.claude/plugins/cache/` — десятки MB бинарников плагинов. Восстанавливаются автоматически из `claude plugin install` после прописывания enables+marketplaces (см. §6.6).
- **Не переезжает:** `~/.claude.json` целиком (581 строк проектных preferences, usageCount, oauthAccount, etc.) — машинно-локальный + user-account-specific. Из него извлекается **только** секция `mcpServers` (как template).
- **Не переезжает:** Лидерра-специфичный MCP `laravel-boost` из `.mcp.json` — его команда `php app/artisan boost:mcp` требует Laravel-приложения в `app/`.
- **Не переезжает:** GITHUB_TOKEN, API_KEY для magic — секреты. Документируются в README.md brain'а как env-vars/interactive prompt.
| CLAUDE.md содержит и универсальные правила, и Liderra-specific tech stack | Целиком в brain как `CLAUDE.md.template`, секции §2 (стек), §6 (фаза), §7 (Boost detail) маркируются как `<!-- PROJECT-SPECIFIC -->` блоки | Чистого разделения нет; маркеры позволяют будущему generator'у фильтровать |
| Pravila содержит cross-refs на CRM_bp-gr_Инструкция_v8_5.md, schema.sql, ТЗ | Целиком в brain как `Pravila.template`; cross-refs остаются как «пример проекта» с явным `<!-- EXAMPLE: liderra -->` | Удалять примеры → теряем context для брайншторминга; помечаем |
| Plugin_stack_rules — на 100% project-agnostic? | Да, 916 строк правил → brain без изменений | Все 16 правил говорят о Vue/Vuetify/Brandbook абстрактно; конкретный Brandbook — content проекта |
| Tooling_v8_3.md упоминает Liderra-специфичный db/schema.sql v8.11 | В brain template; раздел «Текущая фаза проекта» маркируется PROJECT-SPECIFIC | Tooling registry — мозг (структура реестра + 33 слота + матрица конфликтов), но фазовая раскладка — content |
| Visualization HTML содержит 50 узлов с именами реальных хуков мозга | В brain без изменений — она и описывает мозг | Visualization — это визуальное представление brain'а самого |
| `magic` MCP содержит API_KEY = `da9dbfbdd4ad...` в plaintext | В brain как `mcp-user.template.json`с placeholder `<<MAGIC_API_KEY>>`; install.sh при первом запуске prompt'ит и подставляет | API_KEY — секрет; нельзя в repo даже private (gitleaks pre-commit отловит) |
| `.mcp.json` смешивает универсальный (playwright, github, semgrep) и Лидерра-only (laravel-boost) | Разделить на 2 файла: `project-mcp-universal.template.json` в brain + `project-mcp-project-specific.json` (laravel-boost) остаётся в Лидерре | laravel-boost требует Laravel-приложения; новый консьюмер без Laravel не сможет его запустить |
| Plugin marketplaces — отдельный JSON или встроить в `installed_plugins.json`? | Отдельный `marketplaces.json` (формат как `~/.claude/plugins/known_marketplaces.json`) | Сохраняет совместимость с нативным форматом Claude Code; install.sh просто `cp` его в нужное место |
| Plugin pinning через gitCommitSha — обязателен или мягкий? | Жёсткое pinning v1.0: install.sh после `claude plugin install` проверяет фактический SHA против manifest, fail если mismatch | Воспроизводимость = brain v1.0 гарантирует ту же версию superpowers 5.1.0 + SHA `f2cbfbef` на всех консьюмерах |
| 21 | Написать scripts/lib/install-plugins.sh | `claude plugin install` для каждой строки в `plugins-manifest.json`; verify SHA match | shellcheck OK |
| 22 | Написать scripts/lib/setup-secrets.sh | Interactive prompt для `<<MAGIC_API_KEY>>` (или GITHUB_TOKEN env-var hint) | shellcheck OK |
| 24 | Написать .gitignore | Исключить `experiments/*` (кроме `.gitkeep` и `README.md`), `__pycache__`, `*.pyc`, **`*-resolved.json`** (файлы с подставленными секретами после install) | OK |
**Critical:** шаги 4–13 — **копирование/извлечение**, не перемещение. После bootstrap brain artifacts в Лидерре и в `~/.claude/` остаются на месте. Удалять оригиналы **не нужно** для v1.0 — они становятся «installed copy». Sync direction после bootstrap: brain → консьюмер (one-way override).
**Шаг 26 (gitleaks self-scan) — критичный gate:** если в brain repo попал реальный API_KEY (например, забыли применить шаг 12 masking), commit/push не делается до фикса. Это защита от R13 в §9.
### §5.2. Что НЕ делаем при bootstrap
- ❌ Не удаляем CLAUDE.md / Pravila / Tooling / `.mcp.json` из Лидерры — остаются как «текущая installed копия».
- ❌ Не правим `~/.claude/settings.json` / `~/.claude.json` — остаются рабочими; sync произойдёт когда install.sh запустится с `--target=$HOME/.claude`.
- ❌ Не удаляем `~/.claude/hooks/*.py` — работающие; sync их обновит позже.
- ❌ Не делаем `claude plugin uninstall` для существующих плагинов — они уже установлены, brain v1.0 их только pin'ит для воспроизводимости на других машинах.
- ❌ Не пушим API_KEY / GITHUB_TOKEN в repo даже private — gitleaks self-scan (шаг 26) — обязательный gate.
- ❌ Не пушим в GitHub до явного approval от заказчика (шаги 29–30 опциональны на этапе bootstrap).
-`--target=<path>` — куда синкать; **обязательный**. Два режима:
- Если `<path>` содержит `.git/` ИЛИ если в `<path>/docs/` есть Pravila — режим **project-files** (синкается `project-files/*` включая `.mcp.json.template`)
- Если `<path>` = `$HOME/.claude` ИЛИ содержит `hooks/` ИЛИ `settings.json` — режим **user-level-files** (синкается `user-level-files/*` включая plugins/MCP)
- Любой другой `<path>` → exit 1 с пояснением.
-`--version=<tag>` — какую версию brain'а накатывать; **обязательный**.
-`--dry-run` — показать что было бы скопировано, не копировать.
-`--force` — пропустить confirmation prompt и backup'ы (для CI).
-`--with-plugins=yes|no` — устанавливать ли плагины через `claude plugin install`. По умолчанию `yes` для user-level mode, `no` для project-files mode.
-`--with-mcp=yes|no` — копировать ли MCP-конфиги. По умолчанию `yes`.
-`--skip-secrets` — не запускать interactive prompt для API_KEY (для CI или повторного запуска). Файлы остаются с `<<MAGIC_API_KEY>>` placeholder; consumer должен resolve вручную.
**Поведение:**
1. Валидация: brain repo clean (no uncommitted), tag существует, `command -v jq python3 git` — все есть.
5. Для settings-fragment.json (user-level mode): JSON merge с существующим settings.json через `scripts/lib/merge-settings.sh` (заменяет ключи `enabledPlugins` + `permissions` + `hooks`, остальное оставляет).
6.**(user-level mode + --with-mcp=yes)** Merge `mcp-user.template.json` в `~/.claude.json` (ключ `mcpServers`) через `scripts/lib/merge-mcp.sh`. Если placeholder `<<MAGIC_API_KEY>>` всё ещё в файле — запустить `setup-secrets.sh` (если не `--skip-secrets`).
7.**(project mode + --with-mcp=yes)** Если `<target>/.mcp.json` уже существует — `merge-mcp.sh` добавляет только universal-серверы (playwright, github, semgrep), оставляя project-specific (например, laravel-boost в Лидерре). Иначе — `cp .mcp.json.template <target>/.mcp.json`.
2. Tag в `.brain-version` существует в brain repo.
3. Для каждого файла из `manifest.json` соответствующего режима: sha256 файла в `<target>` == ожидаемого sha256 в manifest. **MCP/secrets файлы исключены** — их sha256 отличается после secret resolution.
4. Для user-level mode: settings.json валидный JSON, содержит ожидаемые секции `enabledPlugins.{4 плагина}`, `permissions.allow`, `permissions.deny`, `permissions.ask`, `hooks.{SessionStart,PreToolUse,UserPromptSubmit,PostCompact,Stop}`.
5. Для user-level mode: все 10 hooks исполняемые (`-x`), Python синтаксис OK (`python -m py_compile`).
6.**Plugin check:** для каждого плагина из `plugins-manifest.json` — `claude plugin list` показывает его установленным и enabled.
7.**MCP check:** в `~/.claude.json:mcpServers` есть `magic`; в `<consumer>/.mcp.json` есть playwright/github/semgrep.
8.**`--strict-secrets`:** ни один файл в `<target>` не содержит placeholder'ов `<<*>>` (значит все секреты resolved). По умолчанию OFF — placeholder допустим в `.mcp.json.template` копиях.
**Exit codes:**
- 0 — все ОК
- 1 — `.brain-version` нет или невалидный
- 2 — sha256 mismatch (с указанием файла)
- 3 — settings.json повреждён
- 4 — hook script невалидный
- 5 — плагин из manifest не установлен
- 6 — MCP-сервер из ожидаемых не найден
- 7 — `--strict-secrets` и найден unresolved placeholder
### §6.3. `scripts/lib/merge-settings.sh` — JSON merge для settings.json
**Зачем нужен:**`~/.claude/settings.json` в Лидерра-машине содержит `theme`, `editorMode`, `statusLine` и т.п., что **не часть мозга**. Brain владеет только `enabledPlugins` + `permissions` + `hooks`. При sync нельзя просто `cp` settings — затрётся theme.
**Edge case:** если `<target>/settings.json` не существует → копируется `settings-fragment.json` целиком.
### §6.3a. `scripts/lib/merge-mcp.sh` — JSON merge для MCP-конфигов
**Зачем нужен:** два source'а MCP — user-level (`~/.claude.json:mcpServers`) и project-level (`<repo>/.mcp.json:mcpServers`). Brain владеет subset'ом (magic в user, playwright/github/semgrep в project); консьюмер может иметь свои дополнительные (Лидерра имеет `laravel-boost`).
**Алгоритм (user-level):**
```bash
# Merge: brain MCP-servers поверх consumer's, оставляя дополнительные
**Зачем нужен:** brain хранит template с`<<MAGIC_API_KEY>>` placeholder'ом. Реальный API_KEY — у пользователя в голове / в KeePass / в env.
**Алгоритм:**
1. Сканировать `<target>/.claude.json` на placeholder'ы `<<*>>`.
2. Для каждого — prompt: «Введите значение для `<<MAGIC_API_KEY>>` (или ENTER для пропуска):»
3. Если введено — `sed -i "s|<<MAGIC_API_KEY>>|$INPUT|"`.
4. Если пропущено — оставить placeholder + добавить в `.brain-deferred-secrets.txt` (для последующего напоминания).
**Альтернатива:**`--secret=MAGIC_API_KEY=<value>` через CLI (non-interactive режим для CI).
**Secrets list для v1.0:**
-`<<MAGIC_API_KEY>>` — API_KEY для 21st.dev Magic MCP
-`GITHUB_TOKEN` — НЕ через placeholder, через env-var (документировано в `docs/secrets-and-tokens.md`)
### §6.3c. `scripts/lib/install-plugins.sh` — Claude Code plugin installer
**Зачем нужен:** brain хранит `plugins-manifest.json` (4 плагина с pinned versions). После копирования файлов нужно реально установить плагины через CLI Claude Code.
**Алгоритм:**
```bash
# 1. Add marketplaces from marketplaces.json
for marketplace in $(jq -r 'keys[]' <brain>/user-level-files/marketplaces.json);do
**Зачем нужен:** Лидерра редактирует brain-файлы через плагин `claude-md-management` (правило §5 п.10 текущего CLAUDE.md). Если правка прошла в Лидерре, brain про неё не знает. extract.sh показывает diff и предлагает merge.
**Поведение:**
1. Найти файл в `<source>` по relative path (например, `CLAUDE.md`).
2. Найти соответствующий template в brain (`project-files/CLAUDE.md.template`).
5. Если apply — заменить template содержимым из consumer; не commit'ить (даёт юзеру review).
6. Если merge — открыть в `git mergetool` или fallback `code --diff`.
**Не запускается автоматически** — только по явной команде пользователя.
### §6.5. Идемпотентность install.sh
Запуск `install.sh --target=X --version=Y`**дважды подряд** = no-op после первого (всё уже на месте; backup перезаписывается). Защита от случайного двойного выполнения — через `.brain-version` check на старте: если tag совпадает и sha256 всех файлов уже совпадают — exit 0 с сообщением «уже установлено». Override через `--force`.
**Гарантия:**`.gitignore` исключает `experiments/*` кроме `experiments/README.md` и `experiments/.gitkeep`. Эксперименты commit'ятся, но не уходят в публичный output sync.
### §7.3. Когда промоут из experiments → user-level-files
**Чеклист «зрелости»:**
- [ ] Имеет тесты, тесты проходят
- [ ] Не ломает существующие хуки (запустить `economy-self-check.py` после установки)
- [ ] Описан в `docs/` если меняет поведение
- [ ] manifest.json обновлён (новый sha256)
- [ ] CHANGELOG.md обновлён
- [ ] Локально протестирован на Лидерре в течение ≥1 рабочей сессии без проблем
Только после всех галочек → `git mv experiments/.../hook.py user-level-files/hooks/hook.py` + tag bump.
---
## §8. Границы редактирования (matrix)
| Файл | Где живёт source of truth | Где можно править | Где НЕЛЬЗЯ править |
|---|---|---|---|
| `CLAUDE.md` (в Лидерре) | `claude-brain/project-files/CLAUDE.md.template` | brain repo через `claude-md-management:claude-md-improver` (как сейчас) | прямой Edit в Лидерре |
| **Secrets:** API_KEY для magic, GITHUB_TOKEN | НЕ в brain repo; локально у юзера | env-vars или setup-secrets.sh prompt | brain repo любой ценой (gitleaks gate) |
4.`./scripts/install.sh --target=<liderra> --version=<new-tag>` → синкает в Лидерру
5. Commit в Лидерра: bump `.brain-version`
**Transition strategy:** v1.0 — оба workflow работают (sync пока ручной, claude-md-management всё ещё может править Лидерра-файлы). v1.1+ — добавляется guard-хук, который блокирует Edit на brain-файлах в Лидерре, перенаправляя в brain repo.
---
## §9. Риски и митигации
| # | Риск | Вероятность | Импакт | Митигация |
|---|---|---|---|---|
| R1 | Sync затирает локальные правки в Лидерре, сделанные через claude-md-management до bootstrap | Средняя | Высокий (потеря работы) | install.sh делает backup в `.brain-backup-<timestamp>/` перед любым cp; verify.sh показывает diff между будущим состоянием и текущим в режиме `--dry-run` |
| R2 | Brain дрейфует от Лидерры — extracted templates устаревают, в Лидерре есть новые правки | Высокая (особенно при активной работе через claude-md-management) | Средний | extract.sh для periodic rescue; `verify.sh` показывает «extraneous changes detected» если sha256 mismatch; CI алерт |
| R3 | Hook несовместим с новым consumer проектом (например, тестовый проект где economy-mode не нужен) | Низкая | Средний | install.sh `--target=<X>` поддерживает фильтрацию через `manifest.json` поле `optional: true` (v1.1+); v1.0 — все или ничего |
| R4 | Циркулярная зависимость: brain содержит ссылку на Pravila §12.3 «список skills exclusions», который меняется | Средняя | Низкий | Pravila template параметризуется (`{{SKILL_LIST}}` placeholders, заполняется при install). v1.0 — без параметризации, copy as-is |
| R5 | settings.json merge через jq падает на edge cases (escaped quotes в commands) | Низкая | Высокий (`~/.claude` сломан) | merge-settings.sh делает backup settings.json.bak перед merge; verify.sh запускается обязательно после; на ошибке rollback |
| R6 | GitHub repo CoralMinister/claude-brain не создаётся (PAT expire / 404) | Низкая | Низкий | bootstrap шаги 22–23 опциональны; brain repo работает локально без GitHub до момента готовности |
| R7 | На другой машине bash/jq/python не установлен — install.sh падает | Высокая (если когда-то развернётся не на dev-машине) | Средний | scripts/install.sh в начале делает `command -v jq python3 git || exit 1` с явным сообщением; в README.md — список prereqs |
| R8 | Cyrillic path `c:/моя/проекты/...` ломает install.sh (bash в Windows ≠ POSIX) | Средняя | Высокий | Все скрипты использовать `"$1"` quoted переменные; тестировать на кириллических target из bootstrap |
| R9 | Лидерра-разработчик случайно отредактирует CLAUDE.md в Лидерре, sync затрёт | Высокая (особенно в первые недели после bootstrap) | Средний | v1.1+ — git pre-commit hook в Лидерре, который алертит на изменения brain-файлов с подсказкой «правь в claude-brain»; v1.0 — только документация |
| R10 | Brain repo grows uncontrollably (experiments не чистятся) | Низкая | Низкий | `experiments/` в .gitignore (всё кроме README.md); CI алерт если в commit включён `experiments/*` |
| R11 | Версии brain'а несовместимы (например, hook v1.2 требует Python feature которого нет на machine) | Низкая | Высокий | verify.sh проверяет Python version compatibility (`python --version >= 3.10`); manifest.json содержит min-python-version |
| R12 | Дмитрий начинает терять trust «brain — лишний слой, можно же напрямую» | Средняя (если value не очевиден в первый месяц) | Высокий (откат всей затеи) | v1.0 даёт сразу 1 visible win: возможность экспериментировать без страха за Лидерру; docs/how-to-experiment.md показывает конкретный кейс |
| R13 | API_KEY для `magic` MCP попадает в brain repo как plaintext (масштаб leak: 21st.dev account compromise) | Средняя (легко забыть применить шаг 12 masking) | **Критический** (security incident) | Bootstrap шаг 26 — обязательный gitleaks self-scan перед commit; CI workflow брена запускает gitleaks на каждый push; в `~/.claude.json` reference сейчас уже viewable, при extraction обязательное замещение через jq на `<<MAGIC_API_KEY>>`. README brain'а — explicit warning «никогда не cp без masking» |
| R14 | `claude plugin install` упал — marketplace 404, network down, версия более не существует | Средняя (open-source plugins могут breaking-change) | Высокий (полный stack не работает на новом консьюмере) | install.sh exit code 6 + fallback: список плагинов попадает в `<target>/.brain-pending-plugins.txt`, юзер ставит вручную позже; verify.sh покажет «5 plugins expected, 3 installed»; manifest содержит SHA для воспроизводимости |
| R15 | Project-level MCP конфликтует: Лидерра имеет `laravel-boost`, новый консьюмер без Laravel — install копирует и ломает | Средняя | Средний | `merge-mcp.sh` для project-mode merge'ит только universal-серверы (playwright/github/semgrep) поверх существующих; никогда не удаляет project-specific (laravel-boost остаётся). Новый консьюмер начинает с пустого `.mcp.json` → получает только universal |
| R16 | Plugin SHA pinning не работает — `claude plugin install` не поддерживает `@<sha>` | Средняя (зависит от Claude Code CLI features) | Низкий | install.sh после `claude plugin install <name>@<marketplace>` сравнивает фактический SHA с manifest и логирует warning (не fail). Воспроизводимость достигается на best-effort; v1.1+ может ввести `claude plugin install --pin=<sha>` если CLI поддержит |
| R17 | Marketplace плагин (например, superpowers) обновился между brain v1.0 и v1.1 — старый pin SHA не существует на marketplace | Низкая (marketplace история git — никогда не удаляется) | Средний | manifest хранит и version (`5.1.0`) и SHA. При install — fallback на version pinning если SHA не найден. README документирует marketplace stability |
| R18 | Brain extraction шага 12 (jq masking) затирает API_KEY, но в `~/.claude/backups/` остаётся незамаскированная копия (auto-backup Claude Code) | Низкая | Средний (потенциальный secondary leak) | Bootstrap шаг включает `find $HOME/.claude/backups/ -name "*.json" -newer 2026-05-10 -exec gitleaks detect --source={} \;` — алертит если backup содержит API_KEY; remediation — ротировать API_KEY |
### §9.1. Что НЕ риск, но часто кажется
- ❌ «Brain repo на GitHub утечёт» — repo private; **после применения R13 mitigation** (masking) нет credentials/PII; сами хуки и правила не secrets.
- ❌ «Sync рушит Claude Code сессию» — install.sh не трогает запущенные процессы; settings.json reload — встроенная feature Claude Code, тестировалось при economy hook setup (10.05.2026).
- ❌ «Claude путается какой brain версии» — `.brain-version` файл + verify.sh даёт явный однозначный ответ.
- ❌ «Plugin cache десятки MB — надо хранить в brain» — нет; cache восстанавливается из marketplace через `claude plugin install`. Manifest pinning обеспечивает версию.
- ❌ «GITHUB_TOKEN надо в brain как secret» — нет; это env-var (`${GITHUB_TOKEN}` в `.mcp.json` resolution — runtime Claude Code), документируется в `secrets-and-tokens.md`.
---
## §10. Success criteria (acceptance)
### §10.1. Bootstrap (v1.0) принят, если:
1.**Brain repo существует** в `c:/моя/проекты/claude-brain/`с git history и тегом `brain-v1.0`.
3.**`.brain-version` в Лидерре** содержит `brain-v1.0` и SHA коммита.
4.**install.sh успешно прогоняется**`--dry-run` на Лидерре (показывает «no changes needed» — потому что Лидерра уже содержит исходники).
5.**verify.sh возвращает 0** на Лидерре и на `$HOME/.claude/`.
6.**Лидерра не пострадала:** Pest 545+/547 проходит как до bootstrap (на момент plan'а; экономия hooks отдельным spec'ом отслеживается); git log Лидерры показывает только +1 commit «declare brain v1.0 installed».
7.**Эксперимент проверен:** в `experiments/test-experiment/` создан тестовый файл, commit'нут, верифицировано что он НЕ попадает в Лидерру после sync.
8.**Gitleaks self-scan brain repo passes:** 0 findings (`gitleaks detect --source=c:/моя/проекты/claude-brain` → exit 0); если есть findings — bootstrap не принят до фикса masking.
9.**Plugin pinning corrected:**`manifest.json` содержит `gitCommitSha` для всех 4 плагинов из `installed_plugins.json`; verify.sh на `$HOME/.claude/` подтверждает что все 4 плагина установлены и enabled.
10.**MCP templates корректные:**`mcp-user.template.json` содержит `<<MAGIC_API_KEY>>` placeholder вместо реального API_KEY; `.mcp.json.template` содержит 3 universal-сервера (playwright/github/semgrep) и **НЕ содержит**`laravel-boost`.
1. На второй (тестовой) папке-консьюмере (например `c:/tmp/test-consumer/`) запуск `install.sh --target=/c/tmp/test-consumer --version=brain-v1.0` создаёт ту же структуру brain artifacts.
2.`verify.sh` на тестовой папке возвращает 0.
3.**Plugin install reproduced:** на тестовой папке + чистом `$HOME/.claude/` (или контейнере) — `install.sh --target=$HOME/.claude --version=brain-v1.0 --with-plugins=yes` ставит 4 плагина из marketplaces; `claude plugin list` показывает все 4 enabled.
4.**MCP secret prompt работает:** при первом `install.sh`с`--with-mcp=yes` без `--skip-secrets` — interactive prompt запрашивает MAGIC_API_KEY; после ввода — placeholder в `.claude.json` заменён реальным значением.
5. (Опционально, v1.1+) на полностью чистой Windows-машине без существующего проекта — bootstrap brain'а + install в новый dir даёт рабочий стек.
### §10.3. Brain рабочий (живая верификация), если:
1. Дмитрий просит правку CLAUDE.md → Claude правит template в brain repo → install.sh синкает → правка появляется в Лидерре корректно.
2. Дмитрий просит эксперимент с новым хуком → создаётся в `experiments/` → не задевает Лидерру → промоут после стабилизации → следующий sync обновляет.
3.**Plugin update flow:** superpowers релизит 5.2.0 → Дмитрий правит `plugins-manifest.json` в brain (version + новый SHA) → bump brain v1.1 → install.sh синкает → `claude plugin update superpowers@superpowers-dev` ставит новую версию; old plugin SHA пишется в CHANGELOG.md brain'а.
4.**MCP добавление:** Дмитрий хочет добавить новый MCP-сервер `foo` в стек — правит `mcp-user.template.json` (или `.mcp.json.template`) в brain → bump → install.sh синкает; merge сохраняет уже существующие MCP в `~/.claude.json`.
- **Selective install:** только определённые хуки (например, без `economy-mode.py` для проекта, который не использует mode-режим).
- **Brain registry:** опциональный публичный реестр в `~/.claude/brain-registry.json` где список всех known consumer projects + их brain versions.
### §11.3. Гарантия совместимости
- Brain v1.0 — single consumer (Лидерра); v1.1+ multi-consumer без breaking changes для существующих consumer'ов (`install.sh --version=brain-v1.0` всегда работает как раньше).
---
## §12. Открытые вопросы
| # | Вопрос | Предлагаемый default (если не уточнить) |
|---|---|---|
| Q1 | Создавать ли GitHub repo на этапе bootstrap (шаги 22–23) или отложить? | Отложить; локального brain достаточно для v1.0 acceptance. |
| Q2 | Удалять ли оригиналы brain artifacts из Лидерры после sync? | Нет, v1.0 — оставить как «installed copy». v1.1+ может ввести `--move-mode`. |
| Q3 | Кто пишет meta `CLAUDE.md` brain'а (не template, а meta-описание самого brain repo)? | Claude в bootstrap, на основе этого spec'а. Дмитрий ревьюит. |
| Q5 | Версионирование templates: brain v1.0 содержит Pravila v1.10 — что когда Pravila обновится? | Brain bump (v1.1) поверх template; cross-ref в CHANGELOG.md brain'а указывает на Pravila версию. |
| Q6 | Эксперименты могут использовать install в "test mode" (отдельный target dir для проверки)? | Да; install.sh уже поддерживает любой `<target>`. Spec README.md показывает пример. |
| Q7 | Pre-commit hook в Лидерре, блокирующий правки brain-файлов (R9 mitigation) — в bootstrap или отложить? | Отложить v1.1. v1.0 — только документация в .brain-version comment. |
| Q9 | Backup retention (`.brain-backup-<timestamp>/`) — сколько хранить? | Все, не чистим автоматически; ручное удаление через `find -mtime +30 -delete` если нужно. v1.1+ — keep-last-5 policy. |
| Q10 | Возможно ли откатить sync без brain repo? | Через `.brain-backup-<timestamp>/` — да; `install.sh --rollback` команда v1.1+. v1.0 — ручной cp из backup. |
| Q11 | Где впервые ввести MAGIC_API_KEY при bootstrap? Или сразу его ротировать (старый дискомпрометирован показом в текущей сессии)? | **Ротировать API_KEY на 21st.dev до bootstrap** (текущий показан в этом spec'е выше — формально compromised); новый держать только в KeePass; setup-secrets.sh prompt запрашивает при первом install. |
| Q12 | `laravel-boost` MCP в Лидерре — оставить там в локальном `.mcp.json`, не в brain? | Да, остаётся в Лидерре `.mcp.json`. Когда install.sh синкает universal-MCP — merge-mcp.sh не трогает laravel-boost. В brain documentation добавить как «project-specific MCP example». |
| Q13 | Plugin pinning через `gitCommitSha` — fail или warn при mismatch? | **Warn по умолчанию** (marketplace может обновиться, что норма); `--strict-plugin-sha` flag — fail. Воспроизводимость = best-effort, не absolute (open-source marketplace может удалить commit). |
| Q14 | Где список Claude Code CLI команд для `claude plugin install` / `claude marketplace add` — задокументирован ли? | **Не верифицировано** что CLI Claude Code имеет именно такие команды (или они другие). Перед bootstrap — `claude --help` + `claude plugin --help`; alternative — править файлы напрямую (`installed_plugins.json` + `known_marketplaces.json` + `~/.claude/settings.json:enabledPlugins`) и просить юзера restart Claude Code. |
| Q15 | Project-level `.mcp.json` в новом консьюмере (без существующего файла) — нужно ли создавать его? | Да, install.sh в project-mode копирует `.mcp.json.template` → `<consumer>/.mcp.json` если файла нет. Новый консьюмер получает 3 universal-MCP сразу. |
| Q16 | На какой стадии brain bootstrap пользователь должен ротировать compromised API_KEY? Перед bootstrap или после первого install? | **Перед bootstrap**: чтобы шаг 12 (jq masking) и шаг 26 (gitleaks scan) проверяли уже неважный плейстекст. После — устанавливать новый через setup-secrets.sh prompt. |
| Q17 | `claude plugin install <name>@<marketplace>` — нужен ли подтверждающий prompt от Claude Code (untrusted plugin warning) при первом запуске? | **Не верифицировано** что новый marketplace требует trust dialog. Из памяти `feedback_environment.md` (квирк auto-mode classifier блокировал untrusted plugin install) — вероятно да. install.sh может попросить юзера один раз подтвердить через `/plugin` UI. |
**Принцип:** все Q* перед началом bootstrap — либо ответ от заказчика, либо явный «default OK». В spec фиксируем default — Дмитрий может override любой пункт.
---
## §13. Что НЕ верифицировано (mode 0% honesty)
- ❌ **Не верифицировано** что `jq` установлен на dev-машине Windows. План считает что есть; если нет — install.sh падает с понятной ошибкой (R7 мит). Bootstrap шаг должен включать `command -v jq` check.
- ❌ **Не верифицировано** что bash на Windows (Git Bash) корректно обрабатывает кириллические paths в `cp` и `git`. Был успех в текущей сессии (мы работаем в `c:/моя/проекты/...`), но скрипты с`set -e` могут падать на edge cases. R8 — открытый риск.
- ❌ **Не верифицировано** что `gh repo create` доступна с текущим PAT (fine-grained, scope «repositories: write»). Шаги 22–23 опциональны до подтверждения.
- ❌ **Не верифицировано** что extract.sh на текущий brain template и Лидерра-CLAUDE.md покажет нулевой diff (они должны быть идентичны после bootstrap; перед commit'ом — обязательная проверка через `diff -u`).
- ❌ **Не верифицировано** что после sync hooks в `$HOME/.claude/hooks/` Claude Code их **перечитывает** без рестарта. Из памяти `feedback_environment.md` известно что settings.json reload требует `/hooks` UI или restart; для hook scripts (только содержимое .py) — `os.path` resolve каждый раз, теоретически live-reload работает, но не проверено явно.
- ❌ **Не верифицировано** что текущий `~/.claude/settings.json` имеет именно те `enabledPlugins` + `permissions` + `hooks` секции, которые описаны в реестре v1.86 шапки. Частично проверено в этой сессии — enabledPlugins имеет 4 плагина (lines 22-27); полное описание секций будет в шаге 9 bootstrap'а.
- ❌ **Не верифицировано** что Claude Code CLI имеет команды `claude marketplace add <repo>`, `claude plugin install <name>@<marketplace>`, `claude plugin list`, `claude plugin info --json`. Перед bootstrap — выполнить `claude --help` и `claude plugin --help`; если команд нет, fallback на прямое редактирование JSON-конфигов + restart Claude Code (Q14).
- ❌ **Не верифицировано** что `claude plugin install` поддерживает SHA pinning (`--pin=<sha>` или `<plugin>@<sha>` syntax). Default поведение в spec'е — warn при SHA mismatch (Q13), не fail.
- ❌ **Не верифицировано** что после copying hooks в `$HOME/.claude/hooks/` и обновления settings.json через merge-settings.sh — Claude Code их auto-reload без рестарта IDE. Из памяти `feedback_environment.md` известна потенциальная проблема с watchers (создание новой `.claude/` директории требует `/hooks` UI открыть или restart). install.sh должен предупреждать.
- ❌ **Не верифицировано** что `gitleaks` установлен на dev-машине. Из памяти известно — есть `bin/gitleaks.exe` в Лидерра repo; brain repo должен ссылаться на тот же или иметь свой; bootstrap шаг 26 уточняет: запускать через `bin/gitleaks.exe detect --source=<brain-path>`.
- ❌ **Не верифицировано** что в `~/.claude/backups/` нет копий settings.json с историческим API_KEY (R18 риск). Перед bootstrap — `find $HOME/.claude/backups/ -name "*.json" | xargs gitleaks detect --source` для понимания scope leak'а.
- ❌ **Не верифицировано** что `jq``*` оператор корректно merge'ит nested объекты (`.mcpServers.magic` ≠ `.mcpServers.{magic, playwright}` после merge). На сложных edge cases (вложенные массивы) `jq` может deep-merge или shallow-merge — нужно тестировать на реальном `~/.claude.json` перед finalize merge-mcp.sh.
- ❌ **Не верифицировано** что `claude plugin install` доступен **в текущей VSCode-extension Claude Code** (vs CLI). Из памяти известна квирка «`/plugin` недоступен в VSCode-extension — через ~/.claude/settings.json». Возможно потребуется CLI Claude Code отдельно или править файлы напрямую.
Все эти открытые места — **не блокеры spec'а**; будут проверены во время bootstrap implementation как explicit verification steps в plan'е. Конкретно для Q14/Q17 — первые 2 шага плана: discovery (`claude --help`) перед началом extraction.
- **Будущий plan:** `docs/superpowers/plans/2026-05-10-claude-brain-extraction.md` (создаётся через `superpowers:writing-plans` после approve этого spec'а)
- **Pravila §11** (override §2.2 / §4.5 / §8.4 разрешён только через explicit brainstorming): использовалось при design discussion
- **Plugin_stack_rules R10.1** (claude-md-management в брене инфраструктурный): обоснование почему #33 переезжает в brain
- **CLAUDE.md §5 п.10** (правки CLAUDE.md только через claude-md-management): требует обновления после bootstrap — «правки через brain repo + sync»
- **memory/feedback_superpowers_hard_rule.md**: содержит описание 6-component economy hook architecture — это часть brain'а
---
## §15. Self-review (по brainstorming skill checklist)
| Чек | Статус | Комментарий |
|---|---|---|
| Placeholder scan (TBD/TODO/«fill later») | ✅ | 0 найдено (только placeholder'ы для secrets — `<<MAGIC_API_KEY>>` — это intended design, не TBD) |
| Internal consistency: §3.1 артефакты ↔ §4 структура | ✅ | 3 артефакта (A/B/C) описаны в обеих секциях согласованно; §4 расширена 4 новыми файлами (plugins-manifest, marketplaces, mcp-user.template, .mcp.json.template) |
| Scope check: достаточно ли узок для одного plan'а | ✅ | v1.0 фокус: single consumer (Лидерра), single user-machine; полный stack (правила + хуки + плагины + MCP); multi-project отложен в §11 |
| Ambiguity check #1 | ✅ | §2.3 — маркеры `<!-- PROJECT-SPECIFIC -->`: v1.0 = HTML-комментарии в templates, без обработки |
| Ambiguity check #2 | ✅ | §6.3a merge-mcp.sh — `jq` оператор `*` deep vs shallow merge: помечено в §13 как «не верифицировано», план должен включать тест |
| Ambiguity check #3 | ✅ | §6.1 `--with-plugins` defaults: явно зафиксировано — `yes` для user-level, `no` для project-mode |
| Risks coverage | ✅ | 18 рисков (R1-R18) с явными митигациями; 5 «not-actually-risks» развенчаны. Критический R13 (API_KEY leak) имеет три уровня защиты: masking при extraction + gitleaks self-scan gate + CI scan на push |
| Open questions complete | ✅ | 17 вопросов (Q1-Q17) с предложенными defaults; Q11, Q14, Q17 — explicit «не верифицировано» (помечены в §13) |
| Security: secret handling | ✅ | API_KEY никогда в repo (masking + gitleaks gate + .brain-deferred-secrets для tracking); GITHUB_TOKEN через env-var; ротация compromised key — explicit pre-bootstrap step (Q11, Q16) |
| Scalability: extra MCP servers | ✅ | merge-mcp.sh deep-merge сохраняет существующие MCP в `~/.claude.json`; новые brain MCP добавляются, старые user MCP остаются |
**Self-review итог:** spec готов к user review v2 (расширенный с plugins/MCP/secrets). Все ambiguity-фиксы применены inline. Версия spec'а — extended A (полный охват согласно решению пользователя).
Содержимое для копирования в `~/.claude/` (user-level config Claude Code).
## Файлы
-`hooks/` — 10 Python hook-скриптов
-`settings-fragment.json` — секции `enabledPlugins` + `permissions` + `hooks` для merge в `~/.claude/settings.json`
-`marketplaces.json` — 3 marketplace для `~/.claude/plugins/known_marketplaces.json`
-`plugins-manifest.json` — 4 плагина с pinned versions для `~/.claude/plugins/installed_plugins.json`
-`mcp-user.template.json` — MCP `magic`с placeholder для merge в `~/.claude.json:mcpServers`
## Sync
Не редактировать здесь напрямую. Все правки — в brain repo + `./scripts/install.sh --target=$HOME/.claude --version=...`.
Reference in New Issue
Block a user
Blocking a user prevents them from interacting with repositories, such as opening or commenting on pull requests or issues. Learn more about blocking a user.
Дмитрий