diff --git a/docs/brain-v2-phase-0-final.md b/docs/brain-v2-phase-0-final.md new file mode 100644 index 0000000..f5fcb31 --- /dev/null +++ b/docs/brain-v2-phase-0-final.md @@ -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) diff --git a/docs/brain-v2-phase-0-preliminary.md b/docs/brain-v2-phase-0-preliminary.md new file mode 100644 index 0000000..f9e7190 --- /dev/null +++ b/docs/brain-v2-phase-0-preliminary.md @@ -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