liderra/brain
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
dbd80e97153738ca2000ababc49c19a7f883196d
brain/docs/brain-v2-phase-0-preliminary.md
T
Дмитрий b58f29d23c 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

142 lines
9.5 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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
Reference in New Issue View Git Blame Copy Permalink