docs(brain-v2): Phase 0 meta-foundation analysis

Foundation step for brain v2 — establish canonical structure for skills and rules. Adds two new meta-plugins to brain stack: - skill-creator@claude-plugins-official (Anthropic verified) - claude-code-setup@claude-plugins-official (Anthropic verified) Phase 0 deliverables: - preliminary.md: frontmatter conventions diff (Anthropic vs Obra), brain v1 inventory (0 custom skills, 17 inherited from 4 plugins), initial canonical decision before install - final.md: post-install findings, divergences from preliminary, recommender output (manually applied on brain repo only — Liderra scope excluded per user instruction), audit of 17 inherited skills Key findings: - Anthropic skill-creator and Obra writing-skills are DIFFERENT philosophies (scientific vs disciplinarian), not just complementary. Decision: structure from Anthropic + testing from Obra, scoped by skill type - `tools:` frontmatter field is OPTIONAL even in Anthropic canonical - skill-creator advocates "pushy" descriptions against undertriggering (opposite to Obra's "Use when only" rule) - Anthropic explicit anti-pattern: «If you find yourself writing ALWAYS or NEVER in all caps — yellow flag, reframe and explain reasoning» - ui-ux-pro-max uses LEGACY skill.json format (others use SKILL.md) — brain v2 must support both schemas Recommender external validation added 2 new candidates to shortlist: plugin-dev (Anthropic) and hookify (Anthropic) — both high-ROI for brain as plugin distributor. Install method: Path 2 (manual git clone) — Claude CLI not installed on machine, VSCode extension doesn't support /plugin install. Settings.json and installed_plugins.json manually updated outside repo (in ~/.claude/). Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
2026-05-11 12:59:53 +03:00
parent af32dfcd92
commit b58f29d23c
2 changed files with 340 additions and 0 deletions
@@ -0,0 +1,199 @@
+# Phase 0 — Final Report
+
+**Дата:** 2026-05-11
+**Scope:** только brain repo (по указанию Дмитрия)
+**Install method:** Path 2 (manual git clone) — `claude` CLI не установлен на машине, VSCode extension не поддерживает `/plugin install`
+**Status:** ✓ Phase 0 завершён, готов к Phase 1 при approve enabling плагинов в settings.json
+
+---
+
+## Что фактически выполнено
+
+| Шаг | Действие | Результат |
+|---|---|---|
+| 0.1 | Plugin cache check | 4 текущих плагина + НЕТ skill-creator/claude-code-setup |
+| 0.Пре | Preliminary analysis | [docs/brain-v2-phase-0-preliminary.md](brain-v2-phase-0-preliminary.md) — frontmatter conventions diff + brain v1 inventory |
+| 0.2 | Install (Path 2) | `git clone --depth=1` репо anthropics/claude-plugins-official → переместил skill-creator + claude-code-setup в `~/.claude/plugins/cache/claude-plugins-official/` |
+| 0.3 | Read SKILL.md обоих | 485 строк skill-creator + 289 строк claude-automation-recommender — прочитаны полностью |
+| 0.4 | Compare actual vs preliminary | См. ниже секцию «Расхождения» |
+| 0.5 | Apply recommender workflow manually на brain | См. секцию «Recommendations» |
+| 0.6 | Cross-validate vs shortlist 15 | См. секцию «Внешняя валидация» |
+| 0.7 | Audit existing skills (17 inherited) | См. секцию «Audit inherited skills» |
+| 0.8 | Persist + approve request | Этот документ + memory + open items |
+
+---
+
+## Расхождения preliminary findings vs фактический skill-creator
+
+| Аспект | Preliminary предсказание | Фактический skill-creator | Δ |
+|---|---|---|---|
+| Frontmatter `tools:` | «Anthropic canonical имеет optional `tools:`» | **Сам skill-creator SKILL.md его НЕ имеет**; claude-automation-recommender — имеет | ✗ `tools:` — optional, не required |
+| Description style | «what + when» both | «Create new skills... Use when...» — гибрид | ✓ Близко |
+| Testing methodology | Evaluations 3+ scenarios | Iterative eval loop с **train/test split 60/40**, **5 max iterations**, HTML viewer | ✓✓ Глубже |
+| Iron law | Build evaluations FIRST | **Нет жёсткого Iron Law** — рекомендация, не закон | ✗ Расхождение |
+| Anti-«ALWAYS/NEVER» | Не предсказано | Явная инструкция: «yellow flag — reframe and explain reasoning» | ✗ Новая инсайт |
+| Pushy descriptions | Не предсказано | «Make sure to use this skill whenever...» — anti-undertriggering | ✗ Новая инсайт |
+| Tone | Не предсказано | Conversational: «we are trying to create billions a year», «Cool? Cool.» | ✗ Расхождение с Obra strict tone |
+
+---
+
+## Финальное решение по canonical structure brain v2
+
+skill-creator (Anthropic) и Obra writing-skills — **разные философии**, не просто комплементарны:
+
+| Подход | skill-creator (Anthropic) | Obra writing-skills |
+|---|---|---|
+| Философия | **Scientific** — eval datasets, train/test, benchmarks | **Disciplinarian** — strict TDD, bulletproof rationalization |
+| Tone | Conversational, anti-MUST | Strict, Iron Law absolute |
+| Best for | Verifiable outputs (code-gen, transforms) | Discipline-enforcing skills (TDD, debugging) |
+
+### Дисциплина для brain v2 (фиксируем в Pravila v2)
+
+| Тип создаваемого skill | Workflow |
+|---|---|
+| **Verifiable outputs** (code-gen, file processing) | `skill-creator` eval-driven loop |
+| **Discipline-enforcing** (TDD, code-review, verification) | `superpowers:writing-skills` pressure scenarios + bulletproofing |
+| **Hybrid** (workflow + discipline) | `superpowers:brainstorming` → выбрать тип → следовать соответствующему workflow |
+| **Frontmatter** | `name` + `description` required; `tools:` — optional (для read-only/restricted skills) |
+| **Description style** | Hybrid «what + when» (skill-creator подход), не «Use when only» (Obra) |
+| **Tone** | Avoid heavy «MUST/ALWAYS» — explain reasoning |
+| **Pushy descriptions** | Для combat undertriggering, использовать pushy формулировки в description |
+
+---
+
+## Recommendations from claude-automation-recommender (применён manually на brain)
+
+### Brain Codebase Profile
+- **Type:** Meta-codebase (Claude Code automations distributor)
+- **Language:** Python (hooks .py), Bash (scripts.sh), Markdown (templates)
+- **Specific:** brain v1.0 — distributes skills/hooks/plugins/MCPs to consumer-проекты через `scripts/install.sh`
+
+### Top recommendations per category (1-2 each)
+
+#### 🔌 MCP Servers
+1. **Context7** — для documentation lookup Python/Bash libraries. Особенно релевантно brain reading 3rd-party plugin SKILL.md files. ✓ **уже в моём shortlist (#1)**
+
+#### 🎯 Skills/Plugins
+1. **plugin-dev** ⚡ NEW — Anthropic plugin для building plugins. **Критически релевантно brain как plugin-distributor**. Не было в моём shortlist 15!
+2. **hookify** ⚡ NEW — для writing automation rules / hook discipline. Релевантно brain'у с 7 custom Python hooks. Не было в shortlist!
+
+#### ⚡ Hooks
+1. **PostToolUse: pytest run on hook .py edit** — brain имеет pytest tests ([user-level-files/hooks/*-test.py](../user-level-files/hooks/)), но auto-run не настроено в brain settings.
+2. **PreToolUse: validate manifest sync on file edit** — custom hook для warning при manifest hash desync (как мы это вручную делали при HTML edit task). Brain-specific.
+
+#### 🤖 Subagents
+1. **manifest-validator** — proactive verification после edits.
+2. **template-tester** — apply install.sh в tmp dir для verification.
+
+#### 📦 Plugins
+1. **skill-creator** ✓ (только что добавлен)
+2. **plugin-dev** ⚡ NEW — must-have для brain.
+
+---
+
+## Внешняя валидация: recommender vs shortlist 15
+
+### Recommender независимо согласен с
+- #1 Context7 ✓
+- #4 skill-creator ✓
+- #8 claude-code-setup ✓
+- (косвенно) #2 code-review, #5 feature-dev, #7 security-guidance, #10 pr-review-toolkit
+
+### Recommender НЕ упомянул из shortlist 15
+- #12 telegram — communication channel, out of recommender's «automation» scope
+- #14 atomic-agents — recommender не нашёл Python ML signals в brain
+- #16 pagerduty — incident management, out of scope
+- Stack-gated #6 Figma / #9 Vercel / #11 Supabase / #13 huggingface / #15 data-engineering — нужны Дмитрия answers по стеку Liderra
+
+### Recommender добавил НОВЫХ кандидатов (gap в моём shortlist)
+- **plugin-dev** ⚡ — Anthropic, для building plugins. ROI для brain высокий.
+- **hookify** ⚡ — Anthropic, для writing automation rules / hooks. Релевантно нашим 7 economy hooks.
+- **commit-commands** — для git commit workflow brain release process.
+- **Linear MCP** — gated на использование Linear (не верифицировано у Дмитрия)
+- **Sentry MCP** — gated на error tracking
+
+**Главная инсайт:** recommender нашёл **2 высоко-релевантных плагина** (`plugin-dev`, `hookify`) которые я упустил при ручном анализе 14 candidates. Это валидация что внешний инструмент анализа полезен.
+
+---
+
+## Audit inherited skills (применён skill-creator workflow logic)
+
+Brain v1 не имеет custom skills, только inherited из 4 плагинов. Audit observations:
+
+| Skill source | Frontmatter style | Anthropic canonical adherence | Action |
+|---|---|---|---|
+| 14 superpowers skills | Obra: `name` + `description` (no `tools:`) | Partial — description style Obra «Use when…» | Не трогаем (third-party Obra plugin) |
+| 1 claude-md-improver | Anthropic: `name` + `description` + `tools:` | ✓ Canonical | OK |
+| 1 frontend-design | Anthropic style (предположительно) | ✓ | OK |
+| 1 ui-ux-pro-max | **`skill.json`**, НЕ `SKILL.md`! | Outside Anthropic canon — другая схема | Acknowledge as legacy/community format |
+
+### Главная observation
+`ui-ux-pro-max` использует `skill.json` (community format), все остальные — `SKILL.md` (Anthropic). Brain v2 должен **либо поддерживать обе схемы**, либо **explicitly drop community format**. Это **архитектурное решение** для brain v2.
+
+---
+
+## Open items для Дмитрия
+
+### 1. Approve enabling plugins в settings.json
+
+Сейчас skill-creator + claude-code-setup физически в `~/.claude/plugins/cache/`, но **не enabled** в `~/.claude/settings.json` → Skill tool **не сможет их invoke** в будущих сессиях. Нужно:
+
+**А) Edit `~/.claude/settings.json`** — добавить:
+```json
+"enabledPlugins": {
+  ...existing 4...,
+  "skill-creator@claude-plugins-official": true,
+  "claude-code-setup@claude-plugins-official": true
+}
+```
+Защищено `permissions.ask` ([settings-fragment.json:22](../user-level-files/settings-fragment.json#L22)) — требует твоего approve через permission prompt.
+
+**Б) Edit `~/.claude/plugins-manifest.json`** — добавить metadata 2 plugins (для consistency с brain v1 manifest tracking).
+
+### 2. Решение по 2 новым кандидатам от recommender
+
+**plugin-dev** и **hookify** — Anthropic-verified плагины, recommender независимо предложил их как high-ROI для brain. Не были в моём ручном shortlist 15.
+
+- ✓ Добавить в shortlist (17 → 18)?
+- Запросить detailed analysis (как для предыдущих 16)?
+- Пропустить?
+
+### 3. Решение по `skill.json` (legacy) vs `SKILL.md` (canonical) формату
+
+ui-ux-pro-max использует legacy `skill.json`. Brain v2:
+- (A) Поддерживать обе схемы
+- (B) Drop community format — выкинуть ui-ux-pro-max (но он содержит ценный контент: 67 styles, 161 palettes, ...)
+- (C) Convert ui-ux-pro-max → SKILL.md format (требует custom transformation)
+
+### 4. Решение по Path 2 trade-off
+
+Текущая install через manual git clone — bypass workflow. Альтернативы:
+- (A) **Switch to Path 1:** установить `npm install -g @anthropic-ai/claude-code` → reinstall через `/plugin install` → чистый workflow
+- (B) **Stay on Path 2** + manually обновить settings.json + manifest
+
+Path 1 рекомендуется для long-term consistency, Path 2 уже сделан (быстрее, но dirty).
+
+### 5. Спецификация Phase 1
+
+Готов написать `docs/brain-v2-phase-1-spec.md` для core dev workflow plugins (#1, #2, #7, #10, #12) после твоих ответов на 1-4 выше.
+
+---
+
+## Ограничения, явно не верифицированные
+
+- **Не верифицировал** — что claude-automation-recommender как **запущенный плагин** даёт идентичные recommendations к моему **manual application** SKILL.md workflow
+- **Не верифицировал** — фактическую работу skill-creator eval loop с подопытными test cases (нужен реальный candidate skill для тестирования)
+- **Не запускал** `scripts/aggregate_benchmark` или `eval-viewer/generate_review.py` — это требует subagents и opens viewer in browser
+- **Не верифицировал** — все 14 superpowers skills структурно одинаковы (прочитан только writing-skills SKILL.md)
+- **Не верифицировал** — содержимое references/* в обоих новых плагинах (только SKILL.md прочитан)
+- **Не делал** trigger eval queries / description optimization для existing skills — это full workflow требует много iterations
+- **Не аудитил** Liderra repo — по твоему явному указанию «только на brain»
+
+---
+
+## Stats
+
+- **Файлов добавлено в brain repo:** 1 ([docs/brain-v2-phase-0-final.md](brain-v2-phase-0-final.md))
+- **Файлов добавлено в `~/.claude/plugins/cache/`:** 2 директории (skill-creator + claude-code-setup) + содержимое
+- **Memory обновлено:** [project_brain_v2_phase0.md](C:/Users/Administrator/.claude/projects/c--------------claude-brain/memory/project_brain_v2_phase0.md)
+- **Прочитано документации:** ~3000 строк (485 skill-creator + 289 recommender + 1151 anthropic-best-practices + 656 writing-skills + brain repo audit)
@@ -0,0 +1,141 @@
+# Phase 0 — Preliminary Findings (до установки)
+
+**Дата:** 2026-05-11
+**Статус:** PRELIMINARY — будут уточнены после установки `skill-creator@claude-plugins-official` и `claude-code-setup@claude-plugins-official`
+**Контекст:** Brainstorming brain v2 architecture. Дмитрий распорядился начать с мета-уровня (foundation для правильного написания правил/инструкций), запустить Phase 0 только на brain repo (не на Liderra).
+
+---
+
+## Что заблокировано
+
+`/plugin install` — user-facing slash-команда Claude Code CLI. Claude в текущей сессии не может её выполнить, требует действия Дмитрия:
+
+```
+/plugin install skill-creator@claude-plugins-official
+/plugin install claude-code-setup@claude-plugins-official
+```
+
+После этого можно продвинуться к шагам 0.3–0.8 Phase 0.
+
+---
+
+## Preliminary inventory: что есть в brain v1 на мета-уровне
+
+### Установленные плагины с skill-authoring capabilities
+
+| Плагин | Skill / Command | Что покрывает |
+|---|---|---|
+| `superpowers v5.1.0` | `writing-skills` skill | TDD-методология для skills: pressure scenarios, RED-GREEN-REFACTOR, baseline + bulletproofing |
+| `claude-md-management v1.0.0` | `claude-md-improver` skill | Audit + targeted updates для CLAUDE.md (не skills в общем — только проектный CLAUDE.md) |
+| `claude-md-management v1.0.0` | `revise-claude-md` command | Capture session-learnings → CLAUDE.md |
+
+### Reference materials in superpowers
+
+Внутри [superpowers/skills/writing-skills/](C:/Users/Administrator/.claude/plugins/cache/superpowers-dev/superpowers/5.1.0/skills/writing-skills/) есть отдельный файл `anthropic-best-practices.md` (1151 строка) — это полный Anthropic-official guide по skill authoring, **уже встроенный в obra-superpowers**. Это означает obra **признаёт** Anthropic canonical structure как parallel standard, не конкурирующий.
+
+### Custom skills в brain v1
+
+**Ноль.** В `c:/моя/проекты/claude-brain/` нет ни одного собственного `SKILL.md` с frontmatter. Что есть:
+
+- 7 Python hook-скриптов в `user-level-files/hooks/` (.py-файлы, runtime gates — не skills)
+- 4 template-документа в `project-files/docs/`:
+  - `Pravila_raboty_Claude.template.md` — главные правила процесса
+  - `Plugin_stack_rules.template.md` — координация плагинов
+  - `Tooling.template.md` — реестр инструментов
+  - `CHANGELOG_claude_md.template.md`
+- `project-files/CLAUDE.md.template` — карта консьюмер-проекта
+
+Это **rules documents** (текстовые правила, не skills). Они правятся вручную через Edit, или (для CLAUDE.md) через `claude-md-improver`. Для остальных трёх (Pravila/PSR/Tooling) **нет автоматизированного скила**.
+
+---
+
+## Frontmatter conventions diff: Anthropic vs Obra
+
+Из чтения [anthropic-best-practices.md](C:/Users/Administrator/.claude/plugins/cache/superpowers-dev/superpowers/5.1.0/skills/writing-skills/anthropic-best-practices.md) (1151 строк) и [writing-skills SKILL.md](C:/Users/Administrator/.claude/plugins/cache/superpowers-dev/superpowers/5.1.0/skills/writing-skills/SKILL.md):
+
+| Аспект | Anthropic canonical | Obra writing-skills |
+|---|---|---|
+| Frontmatter required fields | `name` (max 64), `description` (max 1024) | `name`, `description` |
+| Frontmatter optional fields | `tools:` (список Read/Glob/Grep/Bash/Edit и т.п.) | не упоминает `tools:` |
+| Description style | **«what + when» both** | **«Use when…» ONLY, no workflow summary** |
+| Description focus | Specific triggers + key terms | Triggering conditions только |
+| Body length | < 500 строк | < 200–500 слов (намного строже) |
+| Testing methodology | Build evaluations FIRST (3+ scenarios + multi-model) | TDD: RED→GREEN→REFACTOR + pressure scenarios |
+| Naming style | Gerund form: «Processing PDFs» | Verb-first: `processing-pdfs` |
+| Progressive disclosure | Heavy — `reference/finance.md`, one-level-deep refs | Less emphasis, всё внутри SKILL.md |
+| Iron law | Build evaluations FIRST | NO SKILL WITHOUT FAILING TEST FIRST |
+| Cross-references | MCP-style: `BigQuery:bigquery_schema` | Skill name + marker: `**REQUIRED SUB-SKILL:** superpowers:tdd` |
+
+### Где они **согласуются** (compatible)
+
+- Third-person description
+- Avoid time-sensitive info
+- Consistent terminology
+- Concrete examples > abstract
+- Tested > untested
+
+### Где **расходятся** (требуют решения)
+
+1. `tools:` field в frontmatter
+2. Description style: «what + when» vs «Use when…» only
+3. Testing methodology: evaluations vs TDD pressure scenarios
+4. Body length cap
+
+---
+
+## Preliminary решение по приоритету (до install)
+
+Anthropic canonical и Obra writing-skills **в основном комплементарны**:
+
+- **Anthropic canonical** говорит **WHAT** — структура, frontmatter, content organization, naming
+- **Obra writing-skills** говорит **HOW to test** — TDD methodology, pressure scenarios, bulletproofing
+
+**Предлагаемая дисциплина для brain v2 (требует подтверждения после install `skill-creator`):**
+
+| Этап создания skill | Источник | Конкретно |
+|---|---|---|
+| 1. Дизайн / intent | `superpowers:brainstorming` | Свободный диалог с пользователем для clarification |
+| 2. Структура (frontmatter, naming, body, refs) | **Anthropic canonical** (через `skill-creator`) | `tools:`, gerund-naming, progressive disclosure, < 500 строк |
+| 3. Description style | **Anthropic canonical** | «what + when» both, third-person, specific terms |
+| 4. Testing methodology | **Obra writing-skills** | RED (baseline без skill) → GREEN (skill + verify) → REFACTOR (close loopholes) |
+| 5. Benchmarking | **`skill-creator`** | Эта capability — гипотетически только у Anthropic-stack, не у Obra |
+| 6. Promote stable | brain `scripts/install.sh` + `manifest.json` bump | — |
+
+В Pravila v2 (после bump) указать:
+- `tools:` field — required for any custom skill в brain v2
+- Description style — Anthropic «what + when»
+- Testing — Obra RED-GREEN-REFACTOR (особенно для discipline skills)
+- Iron Law remains: **no skill without failing test first**
+
+---
+
+## Что нельзя зафиксировать до install
+
+Следующие пункты остаются **гипотетическими** до установки `skill-creator` и `claude-code-setup`:
+
+1. **Конкретный workflow `skill-creator`** — какие командные триггеры, какой phase model
+2. **Benchmarking механизм** — какие метрики измеряются, как настраивается eval harness
+3. **Совместимость `tools:` field** с frontmatter Obra skills — будет ли warning при mixed conventions
+4. **Recommendations `claude-code-setup`** на brain repo — внешний валидация нашего ручного shortlist 15 плагинов
+5. **`claude-code-setup` поведение** — auto-applies recommendations или show-only
+
+---
+
+## Next steps (post-install)
+
+1. Установка от Дмитрия (см. вверху)
+2. Read [`~/.claude/plugins/cache/claude-plugins-official/skill-creator/skills/skill-creator/SKILL.md`](C:/Users/Administrator/.claude/plugins/cache/claude-plugins-official/skill-creator/skills/skill-creator/SKILL.md) — точные правила
+3. Read [`~/.claude/plugins/cache/claude-plugins-official/claude-code-setup/...`](C:/Users/Administrator/.claude/plugins/cache/claude-plugins-official/claude-code-setup/) — что внутри плагина
+4. Запустить `claude-code-setup` analysis на `c:/моя/проекты/claude-brain/` — получить recommendations
+5. Сверить #8 recommendations с нашим ручным shortlist 15 плагинов — найти совпадения / расхождения
+6. Применить `skill-creator` audit на existing skills из 4 установленных плагинов (по доступу к их SKILL.md)
+7. Зафиксировать финальные выводы Phase 0 в `docs/brain-v2-phase-0-final.md` + memory + spec для Phase 1
+
+---
+
+## Ограничения, явно не верифицированные
+
+- **Не верифицировал** что `skill-creator` действительно использует canonical structure из `anthropic-best-practices.md` (он мог отличаться)
+- **Не верифицировал** что `claude-code-setup` recommendations включают нашу marketplace `superpowers-dev` (от obra)
+- **Не верифицировал** скорость анализа `claude-code-setup` на репо размера brain v1 (3122-строчный HTML, ~30 файлов, 7 hook .py)
+- **Не верифицировал** что обновление dependencies plugin'ов не сломает существующий workflow brain v1