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

# 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