From 917ef337b2ba522d655c4f74d8cbdf8290c5d37b 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 01:05:10 +0300 Subject: [PATCH] docs: brain meta documentation + manifest.json - CLAUDE.md (brain repo meta) - README.md (root quick start) - CHANGELOG.md (brain-v1.0 release notes) - manifest.json (sha256 + min-python + required tools) - docs/architecture.md (copy of Liderra spec) - docs/how-to-use-brain.md - docs/how-to-experiment.md - docs/secrets-and-tokens.md - docs/consumer-projects.md - user-level-files/README.md - project-files/README.md Co-Authored-By: Claude Opus 4.7 (1M context) --- CHANGELOG.md | 38 ++ CLAUDE.md | 37 ++ README.md | 47 +++ docs/architecture.md | 778 +++++++++++++++++++++++++++++++++++++ docs/consumer-projects.md | 20 + docs/how-to-experiment.md | 42 ++ docs/how-to-use-brain.md | 42 ++ docs/secrets-and-tokens.md | 55 +++ manifest.json | 32 ++ project-files/README.md | 17 + user-level-files/README.md | 15 + 11 files changed, 1123 insertions(+) create mode 100644 CHANGELOG.md create mode 100644 CLAUDE.md create mode 100644 README.md create mode 100644 docs/architecture.md create mode 100644 docs/consumer-projects.md create mode 100644 docs/how-to-experiment.md create mode 100644 docs/how-to-use-brain.md create mode 100644 docs/secrets-and-tokens.md create mode 100644 manifest.json create mode 100644 project-files/README.md create mode 100644 user-level-files/README.md diff --git a/CHANGELOG.md b/CHANGELOG.md new file mode 100644 index 0000000..538e79e --- /dev/null +++ b/CHANGELOG.md @@ -0,0 +1,38 @@ +# Changelog + +## brain-v1.0 — 2026-05-11 (planned) + +### Extracted artifacts + +**project-files/** (для consumer-репозиториев): +- CLAUDE.md.template (Лидерра v1.86, 266 строк) +- docs/Pravila_raboty_Claude.template.md (v1.10, 720 строк) +- docs/Plugin_stack_rules.template.md (v1.7, 916 строк) +- docs/Tooling.template.md (v1.15, 613 строк) +- docs/CHANGELOG_claude_md.template.md +- docs/visualizations/hooks-skills-plugins-map.html (3122 строки) +- .mcp.json.template (playwright + github + semgrep; laravel-boost dropped — project-specific) + +**user-level-files/** (для `~/.claude/`): +- 10 hook-скриптов (skill-marker, skill-check, economy-mode×4, economy-state-guard×2, economy-postcompact, economy-verifier, economy-self-check×2) +- settings-fragment.json (enabledPlugins + permissions + hooks) +- marketplaces.json (3 marketplace: anthropics/claude-plugins-official, obra/superpowers, nextlevelbuilder/ui-ux-pro-max-skill) +- plugins-manifest.json (4 плагина с pinned gitCommitSha) +- mcp-user.template.json (magic с `<>` placeholder) + +**scripts/** (sync tooling): +- install.sh — orchestrator (project/user mode + plugins + MCP) +- verify.sh — sha256 integrity + Python syntax +- extract.sh — reverse sync (consumer → brain) +- lib/common.sh, merge-settings.sh, merge-mcp.sh, setup-secrets.sh, install-plugins.sh + +### Security + +- API_KEY (21st.dev) masking при extraction (placeholder + interactive prompt) +- gitleaks self-scan — обязательный gate перед первым commit'ом +- CI workflow с gitleaks на каждый push + +### Known limitations + +- Plugin SHA pinning через `claude plugin install` — best-effort (warn on mismatch, не fail) +- На VSCode-extension Claude Code команды `claude plugin install` могут быть недоступны — fallback на прямое редактирование JSON diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..360dc99 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,37 @@ +# CLAUDE.md — Brain Repository + +**Что это:** независимый репозиторий «мозга Claude» — переиспользуемого набора правил, хуков, плагинов и MCP-серверов для консьюмер-проектов (Лидерра и будущие). + +**Версия:** brain-v1.0 от 11.05.2026 + +--- + +## Что лежит в этом репозитории + +- `project-files/` — копируется в consumer-проекты (CLAUDE.md.template, Pravila, Tooling, Plugin_stack_rules, .mcp.json.template, visualization) +- `user-level-files/` — копируется в `~/.claude/` (10 hooks, settings-fragment, marketplaces, plugins-manifest, mcp-user.template) +- `scripts/` — инструменты sync (install.sh, verify.sh, extract.sh + 4 lib helper'а) +- `experiments/` — песочница, не синкается +- `docs/` — документация brain'а самого (architecture, how-to-use, how-to-experiment, secrets, consumer-projects) + +## Когда использовать какой скрипт + +- **install.sh** — синкать brain в consumer (Лидерра или новый проект) или в `~/.claude/` +- **verify.sh** — проверить целостность после install +- **extract.sh** — обратный rescue если consumer'е сделали правку и она потерялась бы при следующем install + +## Источник истины + +- Архитектура: [docs/architecture.md](docs/architecture.md) (копия из spec'а Лидерры на момент bootstrap) +- Spec на момент создания: `c:/моя/проекты/портал crm/Документация/docs/superpowers/specs/2026-05-10-claude-brain-extraction-design.md` + +## Что НЕ редактировать прямо в этом репо + +- Скопированные template'ы — это installed copies brain v1.0. Когда хочется править — править здесь, делать bump и rerun install.sh в Лидерре. +- Plugin/MCP конфиги — bump через update manifest, не редактирование cache. + +## Безопасность + +- API_KEY никогда в repo (используется placeholder `<>`) +- gitleaks scan — CI workflow на каждый push +- Подробности: [docs/secrets-and-tokens.md](docs/secrets-and-tokens.md) diff --git a/README.md b/README.md new file mode 100644 index 0000000..131cfe6 --- /dev/null +++ b/README.md @@ -0,0 +1,47 @@ +# Claude Brain + +Переиспользуемый «мозг Claude» — правила, хуки, плагины и MCP-серверы — для подключения к проектам. + +## Quick start + +### Установить мозг в новый или существующий consumer-проект + +```bash +cd c:/моя/проекты/claude-brain +./scripts/install.sh --target=/path/to/my-project --version=brain-v1.0 +``` + +### Установить мозг в `~/.claude/` (user-level хуки + плагины + MCP) + +```bash +cd c:/моя/проекты/claude-brain +./scripts/install.sh --target=$HOME/.claude --version=brain-v1.0 +``` + +При первом запуске будет prompt для `MAGIC_API_KEY` (21st.dev). Используй `--skip-secrets` для CI. + +### Проверить целостность + +```bash +./scripts/verify.sh --target=/path/to/my-project +``` + +## Структура + +См. [CLAUDE.md](CLAUDE.md) для деталей. + +## Документация + +- [docs/architecture.md](docs/architecture.md) — архитектура brain'а +- [docs/how-to-use-brain.md](docs/how-to-use-brain.md) — workflow использования +- [docs/how-to-experiment.md](docs/how-to-experiment.md) — песочница experiments/ +- [docs/secrets-and-tokens.md](docs/secrets-and-tokens.md) — управление секретами +- [docs/consumer-projects.md](docs/consumer-projects.md) — список known consumer projects + +## Prerequisites + +- `git` ≥2.x +- `jq` ≥1.6 +- `python3` ≥3.10 +- `bash` (Git Bash на Windows работает) +- Optional: `gh` (для GitHub repo create), `gitleaks` (CI), `claude` CLI (для plugin install) diff --git a/docs/architecture.md b/docs/architecture.md new file mode 100644 index 0000000..536b809 --- /dev/null +++ b/docs/architecture.md @@ -0,0 +1,778 @@ +# Design Spec — Claude Brain Extraction + +**Источник:** этот документ — копия design spec'а из Лидерры (2026-05-10-claude-brain-extraction-design.md) на момент bootstrap brain v1.0. Hard-link для future-reference. + +**Дата:** 2026-05-10 (поздний вечер) / 2026-05-11 (создание spec) +**Автор:** Claude Code (под mode 0%) +**Статус:** Draft → ожидает review заказчика +**Связано:** [feedback_superpowers_hard_rule.md](../../../../.claude/projects/c---------------------crm-------------/memory/feedback_superpowers_hard_rule.md), [project_state.md](../../../../.claude/projects/c---------------------crm-------------/memory/project_state.md) + +--- + +## §1. Цели + +**Главная цель:** выделить «мозг 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 | +| Rules | [docs/Plugin_stack_rules_v1.md](../../Plugin_stack_rules_v1.md) | 916 строк | 16 правил координации плагинов | +| Tooling | [docs/Tooling_v8_3.md](../../Tooling_v8_3.md) | 613 строк | Реестр 33 инструментов | +| Changelog | [docs/CHANGELOG_claude_md.md](../../CHANGELOG_claude_md.md) | n/a | История правок CLAUDE.md | +| Viz | [docs/visualizations/hooks-skills-plugins-map.html](../../visualizations/hooks-skills-plugins-map.html) | 3122 строки | Интерактивная карта мозга | +| Hook | `~/.claude/hooks/skill-marker.py` | 710 B | PreToolUse:Skill marker | +| Hook | `~/.claude/hooks/skill-check.py` | 2521 B | §12 reminder | +| Hook | `~/.claude/hooks/economy-mode.py` | 15081 B | UserPromptSubmit parser «экономия N%» | +| Hook | `~/.claude/hooks/economy-mode-test.py` | 6882 B | Тесты парсера | +| Hook | `~/.claude/hooks/economy-self-check.py` | 2191 B | SessionStart infrastructure-check | +| Hook | `~/.claude/hooks/economy-self-check-test.py` | 4244 B | Тесты self-check | +| Hook | `~/.claude/hooks/economy-state-guard.py` | 3872 B | PreToolUse in-turn state-guard | +| Hook | `~/.claude/hooks/economy-state-guard-test.py` | 3597 B | Тесты state-guard | +| Hook | `~/.claude/hooks/economy-postcompact.py` | 2138 B | PostCompact re-inject | +| Hook | `~/.claude/hooks/economy-verifier.py` | 1329 B | Stop wrapper для agent verifier | +| Config | `~/.claude/settings.json` (фрагмент) | 145 строк | `enabledPlugins` + `permissions` + `hooks` (без `theme`, без paths-специфики) | +| **Plugins** | `~/.claude/settings.json:22-27` (enabledPlugins) | 6 строк | 4 включённых плагина: superpowers, claude-md-management, frontend-design, ui-ux-pro-max | +| **Marketplaces** | `~/.claude/plugins/known_marketplaces.json` | 26 строк | 3 источника: anthropics/claude-plugins-official, obra/superpowers, nextlevelbuilder/ui-ux-pro-max-skill | +| **Plugin manifest** | `~/.claude/plugins/installed_plugins.json` | 45 строк | Pinned versions + gitCommitSha для 4 плагинов (для воспроизводимости) | +| **MCP user** | `~/.claude.json:535-548` (mcpServers) | 14 строк | `magic` (21st.dev) — в brain как **template с placeholder'ом для API_KEY** | +| **MCP project (universal)** | [`.mcp.json`](../../../.mcp.json) (playwright, github, semgrep) | ~17 строк из 28 | Универсальные MCP — переезжают в brain как `project-mcp-universal.template.json` | +| **MCP project (Лидерра)** | [`.mcp.json`](../../../.mcp.json) (`laravel-boost`) | ~5 строк из 28 | Лидерра-only (зависит от `app/artisan boost:mcp`) — **остаётся в Лидерре**, не в brain | + +**Итого в brain v1.0:** 6 markdown/html artifacts (~5637 строк) + 10 Python hook-скриптов (~42 KB) + 1 settings-фрагмент (3 секции) + 3 plugin/marketplace manifest файла + 2 MCP template файла (user-level + project-level-universal). + +### §2.2. Вне scope + +- **Не переезжает:** `db/schema.sql`, ТЗ Лидерры, brandbook, handoff, supplier-specs, реализация моделей/views/тестов Лидерры — это **content проекта**, не «мозг». +- **Не переезжает:** memory-файлы (`~/.claude/projects//memory/*.md`) — они per-project per-conversation, не часть мозга. +- **Не переезжает:** `~/.claude/plugins/cache/` — десятки MB бинарников плагинов. Восстанавливаются автоматически из `claude plugin install` после прописывания enables+marketplaces (см. §6.6). +- **Не переезжает:** `~/.claude/sessions/`, `~/.claude/shell-snapshots/`, `~/.claude/telemetry/`, `~/.claude/file-history/`, `~/.claude/ide/`, `~/.claude/.last-cleanup`, `~/.claude/backups/`, `~/.claude/.credentials.json` — runtime-данные машины, не «мозг». +- **Не переезжает:** `~/.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 Code GUI (theme, editorMode, statusLine) — машинно-локальное предпочтение. +- **Не переезжает:** ТЗ рекламного лендинга, supplier integration plan — content Лидерры. + +### §2.3. Спорные кейсы (зафиксированные решения) + +| Кейс | Решение v1.0 | Обоснование | +|---|---|---| +| CLAUDE.md содержит и универсальные правила, и Liderra-specific tech stack | Целиком в brain как `CLAUDE.md.template`, секции §2 (стек), §6 (фаза), §7 (Boost detail) маркируются как `` блоки | Чистого разделения нет; маркеры позволяют будущему generator'у фильтровать | +| Pravila содержит cross-refs на CRM_bp-gr_Инструкция_v8_5.md, schema.sql, ТЗ | Целиком в brain как `Pravila.template`; cross-refs остаются как «пример проекта» с явным `` | Удалять примеры → теряем 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 `<>`; 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` на всех консьюмерах | + +--- + +## §3. Архитектура + +### §3.1. Три физических артефакта + +``` +┌───────────────────────────────────────────────────────────────┐ +│ АРТЕФАКТ A: claude-brain repo (новый, отдельный) │ +│ Путь: c:/моя/проекты/claude-brain/ │ +│ GitHub: CoralMinister/claude-brain (private) │ +│ Роль: Source of truth для всех brain artifacts │ +│ Edit: Только в этом репозитории (sandbox-friendly) │ +└───────────────────────────────────────────────────────────────┘ + │ + │ install.sh --target= --version= + ▼ +┌───────────────────────────────────────────────────────────────┐ +│ АРТЕФАКТ B: consumer-проект (например, Лидерра) │ +│ Путь: c:/моя/проекты/портал crm/Документация/ │ +│ GitHub: CoralMinister/lidpotok (private, существующий) │ +│ Роль: Потребитель мозга через sync │ +│ Edit: Brain-файлы НЕ редактируются вручную здесь; │ +│ правки = редактируй в brain repo → sync │ +│ Маркер: .brain-version (содержит tag + SHA brain'а) │ +└───────────────────────────────────────────────────────────────┘ + │ + │ scripts/install.sh --target=$HOME/.claude + ▼ +┌───────────────────────────────────────────────────────────────┐ +│ АРТЕФАКТ C: ~/.claude/ (user-level config) │ +│ Путь: C:/Users/Administrator/.claude/ │ +│ Роль: Где живут хуки и settings.json при runtime │ +│ Edit: sync из brain repo (через install.sh) │ +│ Маркер: ~/.claude/.brain-version │ +└───────────────────────────────────────────────────────────────┘ +``` + +### §3.2. Поток данных + +**Развитие мозга (нормальный цикл):** + +``` +1. Дмитрий редактирует в claude-brain/ (через VSCode + Claude) +2. Эксперимент в claude-brain/experiments/ (не релизится) +3. Когда стабилизировалось → промоут в claude-brain/project-files/ или user-level-files/ +4. git commit + git tag brain-vX.Y +5. (опционально) git push CoralMinister/claude-brain +6. В Лидерре: cd c:/моя/проекты/claude-brain && ./scripts/install.sh --target=/c/моя/проекты/портал\ crm/Документация --version=brain-vX.Y +7. Лидерра получает обновлённые brain artifacts; .brain-version обновляется +8. В Лидерре: git commit -m "chore: bump brain to vX.Y (SHA abc1234)" +``` + +**Песочница (эксперимент, не задевающий Лидерру):** + +``` +1. Дмитрий: cd c:/моя/проекты/claude-brain +2. git checkout -b experiment/new-hook +3. Создаёт/правит в claude-brain/experiments/new-hook.py +4. Тестирует через временный symlink или прямой запуск +5. Если ОК → промоут в user-level-files/hooks/new-hook.py + bump version +6. Если плохо → git branch -D experiment/new-hook (без следов в Лидерре) +``` + +**Обратное извлечение (rescue из Лидерры):** + +``` +Если brain artifact был ошибочно отредактирован в Лидерре через claude-md-management: +1. cd c:/моя/проекты/claude-brain +2. ./scripts/extract.sh --source=/c/моя/проекты/портал\ crm/Документация --file=CLAUDE.md +3. Скрипт делает diff между текущим brain CLAUDE.md.template и Лидерра-CLAUDE.md +4. Показывает diff, спрашивает: применить? merge? reject? +5. После применения — bump brain version, commit +``` + +### §3.3. Маркер `.brain-version` (контракт) + +**Формат:** plain text, 2 строки + +``` +brain-v1.0 +sha: 8a1f2c3d4e5b6789abcdef0123456789abcdef01 +``` + +**Где живёт:** +- В consumer-проекте: `/.brain-version` +- В user-level: `$HOME/.claude/.brain-version` + +**Контракт:** +- Скрипт `install.sh` пишет файл атомарно (tmp + mv). +- Скрипт `verify.sh` проверяет соответствие: ожидаемый tag/SHA = фактический. +- Lefthook hook (опционально, v1.1+) в Лидерре: при commit с изменёнными brain-файлами — fail если `.brain-version` не bumped. + +--- + +## §4. Структура brain repo + +``` +c:/моя/проекты/claude-brain/ +├── README.md # Что это, как использовать +├── CLAUDE.md # Meta — описание brain'а для самого Claude +├── manifest.json # version, list of artifacts, hash sums +├── CHANGELOG.md # История версий brain'а +├── .brain-version # self-marker (для verify) +│ +├── project-files/ # → копируется в / +│ ├── CLAUDE.md.template +│ ├── .mcp.json.template # project-mcp-universal: playwright + github + semgrep +│ ├── docs/ +│ │ ├── Pravila_raboty_Claude.template.md +│ │ ├── Plugin_stack_rules.template.md +│ │ ├── Tooling.template.md +│ │ ├── CHANGELOG_claude_md.template.md +│ │ └── visualizations/ +│ │ └── hooks-skills-plugins-map.html +│ └── README.md # Что лежит в этой папке (для разработчика) +│ +├── user-level-files/ # → копируется в $HOME/.claude/ и $HOME/.claude.json +│ ├── hooks/ +│ │ ├── skill-marker.py +│ │ ├── skill-check.py +│ │ ├── economy-mode.py +│ │ ├── economy-mode-test.py +│ │ ├── economy-self-check.py +│ │ ├── economy-self-check-test.py +│ │ ├── economy-state-guard.py +│ │ ├── economy-state-guard-test.py +│ │ ├── economy-postcompact.py +│ │ └── economy-verifier.py +│ ├── settings-fragment.json # enabledPlugins + permissions + hooks секции +│ ├── plugins-manifest.json # Pinned plugin versions + gitCommitSha (4 плагина) +│ ├── marketplaces.json # 3 marketplace sources (anthropics, obra, nextlevelbuilder) +│ ├── mcp-user.template.json # `magic` MCP с <> placeholder +│ └── README.md +│ +├── experiments/ # Песочница, НЕ синкается +│ ├── README.md # Правила песочницы +│ └── .gitkeep +│ +├── scripts/ # Sync-инструментарий +│ ├── install.sh # Главный sync скрипт +│ ├── extract.sh # Reverse sync (brain ← consumer) +│ ├── verify.sh # Проверка целостности после install +│ └── lib/ +│ ├── common.sh # Shared helpers (logging, color, exit) +│ └── merge-settings.sh # JSON merge для settings.json +│ +├── docs/ # Документация brain'а самого +│ ├── architecture.md # Эта spec в финальной форме +│ ├── how-to-use-brain.md # User guide +│ ├── how-to-experiment.md # Sandbox workflow +│ ├── adding-new-hook.md # Гайд по добавлению нового хука в реестр +│ └── consumer-projects.md # Список known consumer projects + их versions +│ +└── .github/ # CI на brain (lint Python, lint markdown) + └── workflows/ + └── ci.yml +``` + +**Файлов всего на v1.0:** ~30 файлов + 10 hooks + 1 visualization + 4 plugin/MCP конфига. Размер репо ~270 KB. + +--- + +## §5. Initial bootstrap (one-time) + +**Цель:** создать brain repo на основе текущего состояния (Лидерра + ~/.claude/) и зафиксировать как `brain-v1.0`. + +### §5.1. Шаги bootstrap (атомарные) + +| # | Действие | Команда / файлы | Verification | +|---|---|---|---| +| 1 | Создать директорию | `mkdir -p c:/моя/проекты/claude-brain` | `ls -la` | +| 2 | git init | `cd c:/моя/проекты/claude-brain && git init` | `.git/` существует | +| 3 | Создать структуру каталогов | `mkdir -p project-files/docs/visualizations user-level-files/hooks experiments scripts/lib docs .github/workflows` | `tree -L 3` | +| 4 | Скопировать CLAUDE.md как template | `cp 'c:/моя/проекты/портал crm/Документация/CLAUDE.md' project-files/CLAUDE.md.template` | diff показывает 0 | +| 5 | Скопировать Pravila как template | `cp '.../docs/Pravila_raboty_Claude_v1_1.md' project-files/docs/Pravila_raboty_Claude.template.md` | diff показывает 0 | +| 6 | Аналогично — Plugin_stack_rules, Tooling, CHANGELOG_claude_md | через `cp` | diff проверки | +| 7 | Скопировать visualization | `cp '.../docs/visualizations/hooks-skills-plugins-map.html' project-files/docs/visualizations/` | diff показывает 0 | +| 8 | Скопировать все 10 хуков | `cp $HOME/.claude/hooks/*.py user-level-files/hooks/` | `ls user-level-files/hooks` = 10 файлов | +| 9 | Извлечь `enabledPlugins` + `permissions` + `hooks` из settings.json | `jq '{enabledPlugins, permissions, hooks}' $HOME/.claude/settings.json > user-level-files/settings-fragment.json` | `jq` валидируется как JSON; содержит ровно 3 ключа | +| 10 | Скопировать marketplaces.json | `cp $HOME/.claude/plugins/known_marketplaces.json user-level-files/marketplaces.json` | 3 marketplace в JSON | +| 11 | Извлечь plugin manifest | `cp $HOME/.claude/plugins/installed_plugins.json user-level-files/plugins-manifest.json` | 4 плагина с pinned versions + gitCommitSha | +| 12 | Извлечь user-level MCP с masking API_KEY | `jq '.mcpServers \| with_entries(.value.args \|= map(if test("API_KEY=") then "API_KEY=<>" else . end))' $HOME/.claude.json > user-level-files/mcp-user.template.json` | API_KEY заменён placeholder'ом; gitleaks-сканирование показывает 0 secrets | +| 13 | Извлечь project-level universal MCP | Скопировать `.mcp.json`, удалить блок `laravel-boost` (Лидерра-only) → `project-files/.mcp.json.template` | jq показывает 3 server'а (playwright, github, semgrep), 0 laravel-boost | +| 14 | Написать meta-CLAUDE.md (brain'а) | Новый файл, объясняет что brain — ~30 строк | Markdown OK | +| 15 | Написать manifest.json | version=brain-v1.0, список ВСЕХ artifacts с sha256 (включая plugin/MCP конфиги), + min-python-version, + required-tools (`jq`, `gh`, `git`, `python3`) | JSON валиден, sha256 совпадает с реальными файлами | +| 16 | Написать README.md (root brain'а) | Quick start: install + extract + experiments + plugin install flow + secret setup | Markdown OK | +| 17 | Написать CHANGELOG.md | v1.0 entry с датой и составом (включая «plugins layer + MCP templates added») | Markdown OK | +| 18 | Написать scripts/install.sh | Контракт см. §6 (включая режимы `--with-plugins`, `--with-mcp`, secret prompt) | shellcheck OK | +| 19 | Написать scripts/extract.sh | Контракт см. §6.4 | shellcheck OK | +| 20 | Написать scripts/verify.sh | Проверка `.brain-version` + sha256 + plugin SHA pinning + MCP secrets resolved | shellcheck OK | +| 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 для `<>` (или GITHUB_TOKEN env-var hint) | shellcheck OK | +| 23 | Написать docs/* | architecture.md, how-to-use, how-to-experiment, consumer-projects.md, secrets-and-tokens.md | Markdown OK | +| 24 | Написать .gitignore | Исключить `experiments/*` (кроме `.gitkeep` и `README.md`), `__pycache__`, `*.pyc`, **`*-resolved.json`** (файлы с подставленными секретами после install) | OK | +| 25 | Написать CI workflow | actions/checkout + python lint + markdown lint + **gitleaks scan (secret check)** + jq validate всех JSON | YAML валиден | +| 26 | **Gitleaks self-scan** перед первым коммитом | `gitleaks detect --source=.` на свежем brain repo | 0 findings (или whitelist documented exclusions) | +| 27 | git add . && git commit -m "feat: initial brain v1.0 extracted from Liderra" | atomic commit | `git log` 1 entry | +| 28 | git tag brain-v1.0 | теговая ревизия | `git tag` показывает | +| 29 | Создать GitHub repo CoralMinister/claude-brain (private) | gh repo create | curl 200 OK | +| 30 | git push origin main --tags | публикация | gh repo view OK | +| 31 | В Лидерре: создать `.brain-version` файл | `echo "brain-v1.0\nsha: " > .brain-version` | cat OK | +| 32 | В Лидерре: git add .brain-version && commit -m "chore: declare brain v1.0 installed" | atomic | git log 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). + +### §5.3. Rollback bootstrap + +Если bootstrap пошёл не так: +``` +rm -rf c:/моя/проекты/claude-brain +rm c:/моя/проекты/портал\ crm/Документация/.brain-version +# В Лидерре: git reset --hard HEAD~1 (если коммит «declare brain» уже сделан) +``` + +Brain repo полностью изолирован; снос не задевает Лидерру. + +--- + +## §6. Sync workflow и контракты скриптов + +### §6.1. `scripts/install.sh` — главный sync + +**Signature:** +```bash +./scripts/install.sh --target= --version= [--dry-run] [--force] \ + [--with-plugins=yes|no] [--with-mcp=yes|no] [--skip-secrets] +``` + +**Параметры:** +- `--target=` — куда синкать; **обязательный**. Два режима: + - Если `` содержит `.git/` ИЛИ если в `/docs/` есть Pravila — режим **project-files** (синкается `project-files/*` включая `.mcp.json.template`) + - Если `` = `$HOME/.claude` ИЛИ содержит `hooks/` ИЛИ `settings.json` — режим **user-level-files** (синкается `user-level-files/*` включая plugins/MCP) + - Любой другой `` → exit 1 с пояснением. +- `--version=` — какую версию 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 или повторного запуска). Файлы остаются с `<>` placeholder; consumer должен resolve вручную. + +**Поведение:** +1. Валидация: brain repo clean (no uncommitted), tag существует, `command -v jq python3 git` — все есть. +2. Detection режима по ``. +3. Backup существующих файлов: `/.brain-backup-/`. +4. Копирование (cp -p — сохранить mtime). +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 `<>` всё ещё в файле — запустить `setup-secrets.sh` (если не `--skip-secrets`). +7. **(project mode + --with-mcp=yes)** Если `/.mcp.json` уже существует — `merge-mcp.sh` добавляет только universal-серверы (playwright, github, semgrep), оставляя project-specific (например, laravel-boost в Лидерре). Иначе — `cp .mcp.json.template /.mcp.json`. +8. **(user-level mode + --with-plugins=yes)** Запуск `scripts/lib/install-plugins.sh`: + - Прочитать `marketplaces.json` → для каждого marketplace: `claude marketplace add ` если ещё нет + - Прочитать `plugins-manifest.json` → для каждого плагина: `claude plugin install @` + - После каждого install: сравнить фактический gitCommitSha с pinned в manifest. Mismatch → warn (но не fail; marketplace мог обновиться, что норма) +9. Запись `.brain-version` в ``. +10. Запуск `scripts/verify.sh --target=`. + +**Exit codes:** +- 0 — успех +- 1 — параметры неверны или prereqs отсутствуют (jq/python3/git) +- 2 — brain repo dirty (требует stash или commit) +- 3 — tag не существует +- 4 — target unrecognised +- 5 — verification после copy не прошла → автоматический rollback из backup +- 6 — `claude plugin install` упал (network / marketplace 404) +- 7 — secret prompt отменён юзером (Ctrl+C) и нет `--skip-secrets` + +### §6.2. `scripts/verify.sh` — проверка целостности + +**Signature:** `./scripts/verify.sh --target= [--strict-secrets]` + +**Что проверяет:** +1. `.brain-version` существует и парсится. +2. Tag в `.brain-version` существует в brain repo. +3. Для каждого файла из `manifest.json` соответствующего режима: sha256 файла в `` == ожидаемого 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`; в `/.mcp.json` есть playwright/github/semgrep. +8. **`--strict-secrets`:** ни один файл в `` не содержит 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. + +**Алгоритм:** +```bash +jq -s '.[0] * {enabledPlugins: .[1].enabledPlugins, permissions: .[1].permissions, hooks: .[1].hooks}' \ + /settings.json \ + /user-level-files/settings-fragment.json \ + > /settings.json.tmp +mv /settings.json.tmp /settings.json +``` + +**Edge case:** если `/settings.json` не существует → копируется `settings-fragment.json` целиком. + +### §6.3a. `scripts/lib/merge-mcp.sh` — JSON merge для MCP-конфигов + +**Зачем нужен:** два source'а MCP — user-level (`~/.claude.json:mcpServers`) и project-level (`/.mcp.json:mcpServers`). Brain владеет subset'ом (magic в user, playwright/github/semgrep в project); консьюмер может иметь свои дополнительные (Лидерра имеет `laravel-boost`). + +**Алгоритм (user-level):** +```bash +# Merge: brain MCP-servers поверх consumer's, оставляя дополнительные +jq -s '.[0] | .mcpServers = ((.mcpServers // {}) * .[1].mcpServers)' \ + /.claude.json \ + /user-level-files/mcp-user.template.json \ + > /.claude.json.tmp +mv /.claude.json.tmp /.claude.json +``` + +**Алгоритм (project-level):** +```bash +# Merge: brain universal MCP + consumer's existing (например, laravel-boost) +jq -s '.[0] | .mcpServers = ((.[0].mcpServers // {}) * .[1].mcpServers)' \ + /.mcp.json \ + /project-files/.mcp.json.template \ + > /.mcp.json.tmp +mv /.mcp.json.tmp /.mcp.json +``` + +**Edge case:** если target-файл не существует → создаётся из template. + +### §6.3b. `scripts/lib/setup-secrets.sh` — interactive secret resolution + +**Зачем нужен:** brain хранит template с `<>` placeholder'ом. Реальный API_KEY — у пользователя в голове / в KeePass / в env. + +**Алгоритм:** +1. Сканировать `/.claude.json` на placeholder'ы `<<*>>`. +2. Для каждого — prompt: «Введите значение для `<>` (или ENTER для пропуска):» +3. Если введено — `sed -i "s|<>|$INPUT|"`. +4. Если пропущено — оставить placeholder + добавить в `.brain-deferred-secrets.txt` (для последующего напоминания). + +**Альтернатива:** `--secret=MAGIC_API_KEY=` через CLI (non-interactive режим для CI). + +**Secrets list для v1.0:** +- `<>` — 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[]' /user-level-files/marketplaces.json); do + repo=$(jq -r ".[\"$marketplace\"].source.repo" /user-level-files/marketplaces.json) + if ! claude marketplace list | grep -q "$marketplace"; then + claude marketplace add "$repo" + fi +done + +# 2. Install plugins from plugins-manifest.json +for plugin_key in $(jq -r '.plugins | keys[]' /user-level-files/plugins-manifest.json); do + expected_sha=$(jq -r ".plugins[\"$plugin_key\"][0].gitCommitSha" /user-level-files/plugins-manifest.json) + expected_ver=$(jq -r ".plugins[\"$plugin_key\"][0].version" /user-level-files/plugins-manifest.json) + + claude plugin install "$plugin_key" + + # Verify SHA pinning (warn if mismatch — marketplace might have updated) + actual_sha=$(claude plugin info "$plugin_key" --json | jq -r '.gitCommitSha') + if [[ "$actual_sha" != "$expected_sha" ]]; then + log_warn "Plugin $plugin_key: expected SHA $expected_sha, got $actual_sha (marketplace updated)" + fi +done +``` + +**Edge case:** если `claude` CLI не в PATH → exit 1 с инструкцией установить Claude Code сначала. + +### §6.4. `scripts/extract.sh` — обратный sync (rescue) + +**Signature:** `./scripts/extract.sh --source= --file=` + +**Зачем нужен:** Лидерра редактирует brain-файлы через плагин `claude-md-management` (правило §5 п.10 текущего CLAUDE.md). Если правка прошла в Лидерре, brain про неё не знает. extract.sh показывает diff и предлагает merge. + +**Поведение:** +1. Найти файл в `` по relative path (например, `CLAUDE.md`). +2. Найти соответствующий template в brain (`project-files/CLAUDE.md.template`). +3. Запустить `diff -u`. +4. Спросить: `[a]pply / [m]erge / [r]eject / [q]uit`. +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`. + +--- + +## §7. Brain dev workflow + +### §7.1. Нормальный цикл «улучшить хук» + +``` +# 1. Открыть brain repo +cd c:/моя/проекты/claude-brain + +# 2. Создать feature branch +git checkout -b feat/improve-economy-mode + +# 3. Редактировать user-level-files/hooks/economy-mode.py +# (Claude может работать в этом репо так же как в Лидерре) + +# 4. Запустить локально тесты +python user-level-files/hooks/economy-mode-test.py + +# 5. Commit + push +git add user-level-files/hooks/economy-mode.py user-level-files/hooks/economy-mode-test.py +git commit -m "feat(economy-mode): handle multi-line prompts correctly" +git push origin feat/improve-economy-mode + +# 6. Когда стабильно — merge в main, bump version +git checkout main && git merge feat/improve-economy-mode +# Обновить manifest.json (sha256 economy-mode.py) +# Обновить CHANGELOG.md (новая entry brain-v1.1) +git commit -m "chore: bump to brain-v1.1" +git tag brain-v1.1 + +# 7. Накатить в Лидерре (или $HOME/.claude) +./scripts/install.sh --target=$HOME/.claude --version=brain-v1.1 + +# 8. В Лидерре обновить .brain-version (если затронуло project-files) +./scripts/install.sh --target=/c/моя/проекты/портал\ crm/Документация --version=brain-v1.1 +cd /c/моя/проекты/портал\ crm/Документация +git add .brain-version && git commit -m "chore: bump brain to v1.1" +``` + +### §7.2. Песочница (experiments/) + +**Правило:** всё в `experiments/` — work-in-progress, не часть релиза, **не синкается** в consumer projects. + +**Use case 1:** новый хук, неясно нужен ли вообще. +``` +mkdir experiments/2026-05-15-syntax-check-hook +# Прототипировать в experiments/2026-05-15-syntax-check-hook/hook.py +# Тестировать через symlink: ln -s "$(pwd)/experiments/.../hook.py" $HOME/.claude/hooks/_experimental-syntax-check.py +# Когда зрелое — переезжает в user-level-files/hooks/syntax-check.py + manifest update + tests +``` + +**Use case 2:** альтернативная редакция Pravila. +``` +mkdir experiments/2026-05-15-pravila-v1-11-draft +cp project-files/docs/Pravila_raboty_Claude.template.md experiments/2026-05-15-pravila-v1-11-draft/ +# Редактировать draft независимо +# Когда готов — заменить template + version bump +``` + +**Гарантия:** `.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 в Лидерре | +| `docs/Pravila_raboty_Claude_v1_1.md` (в Лидерре) | `claude-brain/project-files/docs/Pravila*.template.md` | brain repo | Лидерра | +| `docs/Tooling_v8_3.md` (в Лидерре) | `claude-brain/project-files/docs/Tooling.template.md` | brain repo | Лидерра | +| `docs/Plugin_stack_rules_v1.md` (в Лидерре) | `claude-brain/project-files/docs/Plugin_stack_rules.template.md` | brain repo | Лидерра | +| `~/.claude/hooks/*.py` | `claude-brain/user-level-files/hooks/*.py` | brain repo | ~/.claude/hooks/ напрямую | +| `~/.claude/settings.json` (секции `enabledPlugins` + `permissions` + `hooks`) | `claude-brain/user-level-files/settings-fragment.json` | brain repo | ~/.claude/settings.json напрямую | +| `~/.claude/settings.json` (секции `theme`, `editorMode`, `statusLine`) | `~/.claude/settings.json` (consumer-machine) | ~/.claude/settings.json | brain repo | +| `~/.claude/plugins/known_marketplaces.json` | `claude-brain/user-level-files/marketplaces.json` | brain repo | ~/.claude/plugins/ напрямую (install.sh пишет) | +| `~/.claude/plugins/installed_plugins.json` | `claude-brain/user-level-files/plugins-manifest.json` (pinned) | brain repo (для bump'а версий) | ~/.claude/plugins/ напрямую | +| `~/.claude.json` (секция `mcpServers`) | `claude-brain/user-level-files/mcp-user.template.json` (с placeholder) | brain repo template | ~/.claude.json напрямую (install.sh merge'ит) | +| `~/.claude.json` (всё кроме `mcpServers`) | `~/.claude.json` (consumer-machine) | ~/.claude.json | brain repo | +| `/.mcp.json` (universal: playwright, github, semgrep) | `claude-brain/project-files/.mcp.json.template` | brain repo | напрямую `/.mcp.json` (install.sh merge'ит) | +| `/.mcp.json` (project-specific: laravel-boost) | консьюмер (например, Лидерра) | консьюмер | brain repo | +| **Secrets:** API_KEY для magic, GITHUB_TOKEN | НЕ в brain repo; локально у юзера | env-vars или setup-secrets.sh prompt | brain repo любой ценой (gitleaks gate) | +| `db/schema.sql`, ТЗ Лидерры, brandbook, web/v8 | Лидерра | Лидерра | brain repo | +| `experiments/*` | brain repo | brain repo, без sync | consumer projects | +| `.brain-version` (в Лидерре) | пишется install.sh | только install.sh | ручное редактирование | + +### §8.1. Migration story (после bootstrap) + +**Старый workflow (текущий):** +1. Дмитрий: «правь CLAUDE.md» +2. Claude: invoke `claude-md-management:claude-md-improver` → правит CLAUDE.md в Лидерре +3. Commit в Лидерра + +**Новый workflow (после bootstrap brain v1.0):** +1. Дмитрий: «правь CLAUDE.md» +2. Claude: `cd c:/моя/проекты/claude-brain && invoke claude-md-management:claude-md-improver` → правит `claude-brain/project-files/CLAUDE.md.template` +3. Commit в brain +4. `./scripts/install.sh --target= --version=` → синкает в Лидерру +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-/` перед любым 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=` поддерживает фильтрацию через `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 на `<>`. 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: список плагинов попадает в `/.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` не поддерживает `@` | Средняя (зависит от Claude Code CLI features) | Низкий | install.sh после `claude plugin install @` сравнивает фактический SHA с manifest и логирует warning (не fail). Воспроизводимость достигается на best-effort; v1.1+ может ввести `claude plugin install --pin=` если 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`. +2. **Все brain artifacts извлечены** — 6 markdown/html templates + 10 Python hooks + 1 settings-fragment + 3 plugin/marketplace JSON-конфига + 2 MCP template файла в правильных папках. +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` содержит `<>` placeholder вместо реального API_KEY; `.mcp.json.template` содержит 3 universal-сервера (playwright/github/semgrep) и **НЕ содержит** `laravel-boost`. + +### §10.2. Brain переиспользуем (доказательство), если: + +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`. + +--- + +## §11. Multi-project capability (future, v1.1+) + +### §11.1. Что будет работать + +- **N consumer projects** одновременно: brain v1.0 → Лидерра + Project-B + Project-C. +- Каждый consumer имеет свой `.brain-version`; могут быть разными (Лидерра на brain-v1.0, Project-B на brain-v1.1). +- `docs/consumer-projects.md` в brain repo ведёт learnyrecord: какие projects, какие versions. + +### §11.2. Что потребует доработки (v1.1+) + +- **Параметризация templates:** `{{PROJECT_NAME}}`, `{{TECH_STACK}}`, `{{CURRENT_PHASE}}` placeholder'ы. install.sh принимает `--project-config=` с overrides. +- **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'а. Дмитрий ревьюит. | +| Q4 | Шаг 9 (jq extraction permissions/hooks) — какие именно ключи входят в brain settings-fragment? | `permissions.allow`, `permissions.deny`, `permissions.ask`, `hooks` целиком. Остальное (theme, editorMode, MCP enables, statusLine) — машинно-локальное. | +| 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 уже поддерживает любой ``. Spec README.md показывает пример. | +| Q7 | Pre-commit hook в Лидерре, блокирующий правки brain-файлов (R9 mitigation) — в bootstrap или отложить? | Отложить v1.1. v1.0 — только документация в .brain-version comment. | +| Q8 | Brain CI (lint Python, markdown) — обязателен v1.0 или v1.1? | v1.0 — минимальный workflow (Python syntax check + markdownlint). Полные проверки v1.1+. | +| Q9 | Backup retention (`.brain-backup-/`) — сколько хранить? | Все, не чистим автоматически; ручное удаление через `find -mtime +30 -delete` если нужно. v1.1+ — keep-last-5 policy. | +| Q10 | Возможно ли откатить sync без brain repo? | Через `.brain-backup-/` — да; `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` → `/.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 @` — нужен ли подтверждающий 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 `, `claude plugin install @`, `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=` или `@` 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=`. +- ❌ **Не верифицировано** что в `~/.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. + +--- + +## §14. Связанные документы + +- **Этот spec:** `docs/superpowers/specs/2026-05-10-claude-brain-extraction-design.md` +- **Будущий 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 — `<>` — это intended design, не TBD) | +| Internal consistency: §3.1 артефакты ↔ §4 структура | ✅ | 3 артефакта (A/B/C) описаны в обеих секциях согласованно; §4 расширена 4 новыми файлами (plugins-manifest, marketplaces, mcp-user.template, .mcp.json.template) | +| Internal consistency: §5 bootstrap steps ↔ §6 install.sh контракт | ✅ | Шаги 18–22 (создание скриптов install + lib/install-plugins + lib/setup-secrets) согласованы с §6.1/§6.3a/§6.3b/§6.3c | +| Internal consistency: §8 matrix ↔ §6 поведение | ✅ | Matrix добавлены 6 новых строк (plugins/marketplaces/MCP user/MCP project/secrets); install.sh merge-mcp.sh обеспечивает «universal vs project-specific» разделение из matrix | +| Internal consistency: §2.1 inventory ↔ §10.1 success criteria | ✅ | §2.1 говорит 6 markdown + 10 hooks + 1 settings-fragment + 3 plugin/MCP конфига + 2 MCP template = §10.1 пункт 2 | +| Scope check: достаточно ли узок для одного plan'а | ✅ | v1.0 фокус: single consumer (Лидерра), single user-machine; полный stack (правила + хуки + плагины + MCP); multi-project отложен в §11 | +| Ambiguity check #1 | ✅ | §2.3 — маркеры ``: 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 | +| Success criteria measurable | ✅ | 10+5+4 conditions, все проверяемые `verify.sh` / `claude plugin list` / `gitleaks detect` / `git log` | +| 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 (полный охват согласно решению пользователя). + +--- + +**Конец spec'а.** diff --git a/docs/consumer-projects.md b/docs/consumer-projects.md new file mode 100644 index 0000000..c742ca0 --- /dev/null +++ b/docs/consumer-projects.md @@ -0,0 +1,20 @@ +# Consumer Projects + +Реестр проектов, которые подключают brain. + +| Проект | Brain version | Путь | Дата подключения | Status | +|---|---|---|---|---| +| Лидерра | brain-v1.0 | `c:/моя/проекты/портал crm/Документация/` | 2026-05-11 | active | + +## Как зарегистрировать новый проект + +1. `./scripts/install.sh --target=/path/to/new-project --version=brain-vX.Y` +2. В `new-project/` появится `.brain-version` +3. Добавить строку в эту таблицу +4. Commit + push brain repo + +## Reverse — отключить проект + +1. В `/` удалить brain'овские файлы (по списку из manifest.json) +2. Удалить `.brain-version` +3. Удалить строку из таблицы diff --git a/docs/how-to-experiment.md b/docs/how-to-experiment.md new file mode 100644 index 0000000..d1836ba --- /dev/null +++ b/docs/how-to-experiment.md @@ -0,0 +1,42 @@ +# How to experiment + +`experiments/` — песочница, **не синкается** в consumer-проекты (`.gitignore` excludes). + +## Эксперимент: новый хук + +```bash +cd c:/моя/проекты/claude-brain +mkdir experiments/2026-05-20-my-new-hook +# Прототипировать в experiments/2026-05-20-my-new-hook/hook.py +python experiments/2026-05-20-my-new-hook/hook.py < test-input.json + +# Тестировать на live ~/.claude/ — через symlink (Windows: mklink) +# Или через add-hook flag в settings.json указывая полный путь к experiments/... +``` + +## Промоут эксперимента → user-level-files + +Когда хук готов: + +```bash +git mv experiments/2026-05-20-my-new-hook/hook.py user-level-files/hooks/my-new-hook.py +# Обновить manifest.json — добавить sha256 нового файла +# Обновить CHANGELOG.md +git commit -m "feat: promote my-new-hook from experiments" +git tag brain-v1.1 +``` + +После — `./scripts/install.sh --target=$HOME/.claude --version=brain-v1.1` в нужном моменте. + +## Эксперимент: новая редакция Pravila + +```bash +mkdir experiments/2026-05-20-pravila-v2-draft +cp project-files/docs/Pravila_raboty_Claude.template.md experiments/2026-05-20-pravila-v2-draft/ +# Редактировать draft независимо +# Когда готов — заменить template + bump version +``` + +## Гарантия + +`experiments/*` в `.gitignore` (кроме `README.md` и `.gitkeep`). Никакие изменения там не попадают в consumer'ы. diff --git a/docs/how-to-use-brain.md b/docs/how-to-use-brain.md new file mode 100644 index 0000000..62b8ed1 --- /dev/null +++ b/docs/how-to-use-brain.md @@ -0,0 +1,42 @@ +# How to use Brain + +## Сценарий 1: Подключить brain к новому проекту + +```bash +cd c:/моя/проекты/claude-brain +./scripts/install.sh --target=/path/to/new-project --version=brain-v1.0 +``` + +После этого в `new-project/` появятся: +- `CLAUDE.md` (правила Claude) +- `docs/Pravila_*.md`, `docs/Plugin_stack_rules.md`, `docs/Tooling.md` +- `docs/visualizations/hooks-skills-plugins-map.html` +- `.mcp.json` (playwright + github + semgrep MCP) +- `.brain-version` (маркер) + +## Сценарий 2: Обновить brain в существующем проекте + +```bash +cd c:/моя/проекты/claude-brain +git pull +./scripts/install.sh --target=/path/to/existing-project --version=brain-v1.1 +``` + +Backup `/.brain-backup-/` создаётся автоматически. + +## Сценарий 3: Обновить хуки в `~/.claude/` + +```bash +./scripts/install.sh --target=$HOME/.claude --version=brain-v1.1 +``` + +При первом запуске prompt для `MAGIC_API_KEY`. После — Claude Code требует restart для подхвата новых хуков (раз). + +## Сценарий 4: Откатить sync + +Восстановить из backup: + +```bash +ls /path/to/project/.brain-backup-* +cp -r /path/to/project/.brain-backup-/* /path/to/project/ +``` diff --git a/docs/secrets-and-tokens.md b/docs/secrets-and-tokens.md new file mode 100644 index 0000000..013c0b6 --- /dev/null +++ b/docs/secrets-and-tokens.md @@ -0,0 +1,55 @@ +# Secrets and Tokens + +## Список секретов + +| Секрет | Где используется | Откуда взять | +|---|---|---| +| `MAGIC_API_KEY` | `~/.claude.json:mcpServers.magic.args` | 21st.dev → settings → API keys | +| `GITHUB_TOKEN` | `.mcp.json:mcpServers.github.headers` | GitHub → settings → Personal Access Tokens (fine-grained, repo+read:org) | + +## Где НЕ хранить + +- В brain repo (даже private) +- В commit history +- В CLAUDE.md / docs / README +- В скриншотах сессий + +## Где хранить + +- В KeePass / Bitwarden / 1Password +- Как env-vars в shell profile (для `GITHUB_TOKEN`) +- Inline в `~/.claude.json` локально (после resolve через `setup-secrets.sh`) + +## Workflow при первой установке + +```bash +./scripts/install.sh --target=$HOME/.claude --version=brain-v1.0 +# Скрипт промптит: +# > Enter value for <> (or empty to skip): +# Вводишь значение из KeePass +``` + +## Workflow в CI + +```bash +./scripts/install.sh --target=$HOME/.claude --version=brain-v1.0 \ + --skip-secrets +# Placeholder'ы остаются; .brain-deferred-secrets.txt создан +``` + +Затем — resolve через GH Actions secret + `setup-secrets.sh --secret=MAGIC_API_KEY=$MAGIC_API_KEY ...`. + +## Ротация при компрометации + +1. На 21st.dev: revoke + создать новый +2. Обновить локально через `setup-secrets.sh --secret=MAGIC_API_KEY=newvalue ~/.claude.json` +3. Никаких изменений в brain repo не нужно — placeholder остаётся + +## gitleaks scan + +В brain repo — pre-commit hook и CI workflow проверяют: +```bash +gitleaks detect --source=. --no-git +``` + +Если 0 findings — OK. Любой finding — **немедленный фикс** (mask API_KEY, force-push, ротация key). diff --git a/manifest.json b/manifest.json new file mode 100644 index 0000000..f73e5fe --- /dev/null +++ b/manifest.json @@ -0,0 +1,32 @@ +{ + "version": "brain-v1.0", + "created": "2026-05-10T22:03:38Z", + "min_python_version": "3.10", + "required_tools": ["jq", "python", "git", "bash"], + "optional_tools": ["gh", "gitleaks", "claude"], + "files": { + "project-files/.mcp.json.template": "14dd78e8d4a795b85b444bbf7d51cf71b44c5614e3e041bf09d7eb9a6133f1d0", + "project-files/CLAUDE.md.template": "eaee69ec015b07527400f2579192cc1e634ae3192e91e668393600d6e440f6c9", + "project-files/README.md": "f91f0737ffffbd94f3fb84eeb856eb561b4759b62a57fcbf1c3b3f652a9505d8", + "project-files/docs/CHANGELOG_claude_md.template.md": "c9a004af5defab9dfe5408f85b37a9024cc91d9c898d27421297ee590ea8f9e9", + "project-files/docs/Plugin_stack_rules.template.md": "a6624d13bc1366c572d590a7ab125aaeea9cce091c00264797443b00eeefb864", + "project-files/docs/Pravila_raboty_Claude.template.md": "33adaba80b311269861777422f378438bfd08e1a6b1114c49836dd74a096f14c", + "project-files/docs/Tooling.template.md": "9ac1bde261de859760033d2cc22d8a848279ec540c409bf15b7735f39f8d8f99", + "project-files/docs/visualizations/hooks-skills-plugins-map.html": "ad61c5069ac25c70f23315bf7d4c9bd80d2f55380f27f5a95d0e93b80dfe2532", + "user-level-files/README.md": "1bca220f99df30ef1fbfb9314b8f5182784ba44e44e63e7ded10edd77e3c2cba", + "user-level-files/hooks/economy-mode-test.py": "8e42f2137ca79206b8b205334cdf89f1ac991932fe9e773c828c8a1496fa2403", + "user-level-files/hooks/economy-mode.py": "865f36bba142a717dec18fb1e5f055c17b157bd53cc5fdbc7ef1e8628b3c2f64", + "user-level-files/hooks/economy-postcompact.py": "7b96abde074e2f17e0e95d26d7a7fc02f7c4617c0d9787e359c80b6e695716e6", + "user-level-files/hooks/economy-self-check-test.py": "f0f668b88c684674473458d7364f54d537432dc1797ee939b948f635690289e0", + "user-level-files/hooks/economy-self-check.py": "962db87b1abd05a8f783aa6e93d482750c14970ed5ab5229ea58582550f884d7", + "user-level-files/hooks/economy-state-guard-test.py": "2c407af63a5356d051271ea9852485dd2265c593c6535f85c4055a6ebe480196", + "user-level-files/hooks/economy-state-guard.py": "bb5278e356c33b8f99f05ad184b2b8b8d11692407b8e6216be7b0cfe3e11457c", + "user-level-files/hooks/economy-verifier.py": "2b7431bcc1bf80179989e4f918a90de6b37627073cd04fa7a139757b18637a16", + "user-level-files/hooks/skill-check.py": "5f708f412d4d6ea66cd2f14ba119cf784b602d79052bbb976f904339421a09ad", + "user-level-files/hooks/skill-marker.py": "2d2ff205ae1390f87d1f8162e238729fa4d8c12340f02016ee1d54b3fff014a4", + "user-level-files/marketplaces.json": "9017c313525cb78f2078ba79fd974260cb8016f69dbb9a099dcff7b4153af300", + "user-level-files/mcp-user.template.json": "80cce6f971fa3dfca5533becab009060b703c914196a92ac3d6b2e3768b8b923", + "user-level-files/plugins-manifest.json": "1374cf8f4206b972a9ef5be6692773f2b8eaf1016588470a32588539f347f324", + "user-level-files/settings-fragment.json": "cbdda1e23034d0056db5165a85667d6a7d55de6e0629d7be4e9d9d7e4ebb4a7d" + } +} diff --git a/project-files/README.md b/project-files/README.md new file mode 100644 index 0000000..8729d1e --- /dev/null +++ b/project-files/README.md @@ -0,0 +1,17 @@ +# project-files/ + +Содержимое для копирования в consumer-репозитории. + +## Файлы + +- `CLAUDE.md.template` — оперативная карта Claude Code (переименовывается в `CLAUDE.md` в consumer'е) +- `.mcp.json.template` — universal MCP-сервера (playwright, github, semgrep) +- `docs/Pravila_raboty_Claude.template.md` — правила работы Claude +- `docs/Plugin_stack_rules.template.md` — правила plugin stack +- `docs/Tooling.template.md` — реестр инструментов +- `docs/CHANGELOG_claude_md.template.md` — история правок +- `docs/visualizations/hooks-skills-plugins-map.html` — интерактивная карта мозга + +## Sync + +Не редактировать здесь напрямую. Все правки — в brain repo + `./scripts/install.sh --target= --version=...`. diff --git a/user-level-files/README.md b/user-level-files/README.md new file mode 100644 index 0000000..d98dced --- /dev/null +++ b/user-level-files/README.md @@ -0,0 +1,15 @@ +# user-level-files/ + +Содержимое для копирования в `~/.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=...`.