brain/docs/brain-v2-phase-0-final.md

# 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)