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

9.5 KiB
Raw Blame History

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/ есть отдельный файл 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 (1151 строк) и 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 — точные правила
  3. Read ~/.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