Дмитрий
ded5372f4e
Эпик роутер-реестр, спека v2 §2, этап 1. Зонтик plugin-dev развёрнут в 7 карточек-навыков + 7 под-узлов #57a..#57g. - 7 карточек plugin-dev__<навык>.contract.json (agent/command/hook/mcp/ plugin-structure/plugin-settings/skill-development) - nodes.yaml: узел #57 → #57a..#57g; keyword-триггеры на plugin-structure; ссылка L11 обновлена на plugin-dev:plugin-structure - зонтик plugin-dev убран (карточка + узел) - registry-load.test: 109 узлов / 101 active Регрессия (без 5 pre-existing node:test файлов): 4361 passed, exit 0. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
134 lines
17 KiB
Markdown
134 lines
17 KiB
Markdown
# Инвентаризация расщепления комков (разведка 2026-06-18)
|
||
|
||
> Эпик «роутер-реестр», спека v2 §2 (D2). Источник: 4 субагента-разведчика сверили
|
||
> наши контракты `docs/registry/contracts/*.contract.json` (91 шт) с реальными навыками
|
||
> плагинов в `~/.claude/plugins/cache/`. Read-only разведка. Кодовая фраза «роутер-реестр».
|
||
>
|
||
> **Статус:** черновик до решений владельца (развилки внизу). Числа под-навыков — фактические.
|
||
|
||
## Комки к расщеплению (плагин-зонтик → отдельные навыки `плагин:навык`)
|
||
|
||
| # | Контракт (комок) | Плагин | Под-навыков | Уже вынесено | Новых файлов |
|
||
|---|---|---|---|---|---|
|
||
| 1 | superpowers | superpowers-dev | 14 | writing-plans | 13 |
|
||
| 2 | plugin-dev | claude-plugins-official | 7 | — | 7 |
|
||
| 3 | adr-kit | rvdbreemen-adr-kit | 8 (3 служебных) | — | 2–5 (решение B) |
|
||
| 4 | claude-md-management | claude-plugins-official | 2 | — | 2 |
|
||
| 5 | hookify | claude-plugins-official | 1–2 (+команды) | — | 1–2 |
|
||
| 6 | product-management | knowledge-work-plugins | 8 | — | 8 |
|
||
| 7 | design-plugin | knowledge-work-plugins | 7 | — | 7 |
|
||
| 8 | marketing-plugin | knowledge-work-plugins | 8 | — | 8 |
|
||
| 9 | operations | knowledge-work-plugins | 9 | operations-process-doc | 8 |
|
||
| 10 | finance-plugin | knowledge-work-plugins | 8 (журнал ×2?) | — | 7–8 |
|
||
| 11 | brand-voice | knowledge-work-plugins | 3 | — | 3 |
|
||
|
||
Под-навыки по комкам:
|
||
- **superpowers (14):** using-superpowers, brainstorming, dispatching-parallel-agents, executing-plans, finishing-a-development-branch, receiving-code-review, requesting-code-review, subagent-driven-development, systematic-debugging, test-driven-development, writing-plans*, using-git-worktrees, verification-before-completion, writing-skills. (*writing-plans уже отдельным контрактом.)
|
||
- **plugin-dev (7):** agent-development, command-development, hook-development, mcp-integration, plugin-structure, plugin-settings, skill-development.
|
||
- **adr-kit (8):** adr, judge — содержательные; init, install-hooks, lint, migrate, setup, upgrade — служебные/инфра (кандидаты на исключение, развилка B).
|
||
- **claude-md-management (2):** claude-md-improver, revise-claude-md.
|
||
- **hookify:** содержательный навык writing-rules + главный hookify; configure/list/help — команды, не навыки.
|
||
- **product-management (8):** write-spec, roadmap-update, metrics-review, product-brainstorming, sprint-planning, stakeholder-update, synthesize-research, competitive-brief.
|
||
- **design-plugin (7):** accessibility-review, design-critique, design-handoff, design-system, research-synthesis, user-research, ux-copy. (Контракт сейчас покрывает лишь 3 — несоответствие.)
|
||
- **marketing-plugin (8):** brand-review, campaign-plan, competitive-brief, content-creation, draft-content, email-sequence, performance-report, seo-audit.
|
||
- **operations (9):** capacity-plan, change-request, compliance-tracking, process-doc*, process-optimization, risk-assessment, runbook, status-report, vendor-review. (*process-doc уже вынесен в operations-process-doc.)
|
||
- **finance-plugin (8):** audit-support, close-management, financial-statements, journal-entry, journal-entry-prep, reconciliation, sox-testing, variance-analysis. (journal-entry vs journal-entry-prep — возможный дубль, уточнить.)
|
||
- **brand-voice (3):** brand-voice-enforcement, discover-brand, guideline-generation.
|
||
|
||
## НЕ расщеплять (атомарные / материал / оркестратор)
|
||
|
||
- **ui-ux-pro-max** — физически 7 навыков (banner-design, brand, design, design-system, slides, ui-styling, ui-ux-pro-max), НО по нормативке (CLAUDE.md §5.5, PSR R10.1/R11.5/R14.3) это **резерв-библиотека-материал, не решатель** — как marketingskills. Оставляем атомарным маркером-материалом. (Развилка C — подтвердить.)
|
||
- **marketingskills** — библиотека 40 фреймворков-материалов (ADR-015 MKT3). Атомарный.
|
||
- **marketing-ru** — self-authored РФ-навык (own). Атомарный.
|
||
- **security-go-live** — НЕ комок, а композитный оркестратор (needs 5 выходов owasp-zap/nuclei/ward/pdn-152fz/threat-model). Уже правильный. Не трогать.
|
||
- **ccpm, postiz, discovery-interview, 21st-magic, frontend-design, skill-creator, architecture-patterns, normative-sync, prod-deploy-validator, data-scientist, laravel-backend-patterns, process-analysis, process-modeling, billing-audit, ru-tax-accounting, security-guidance, trail-of-bits, owasp-zap, nuclei, threat-model, ward, pdn-152fz-audit, roave-security, trivy, nightowl** + все *-mcp / pg-* / линтеры (gitleaks, vitest, pest, pint, larastan, php-insights, rector, deptrac, eslint-prettier, stylelint, markdownlint, lychee, cspell, mermaid, squawk, ide-helper, volar, vue-tsc, pa11y, histoire, boost, context7, dependabot) — одиночные инструменты/навыки.
|
||
|
||
## Аномалии и недопокрытия (отдельно от расщепления)
|
||
|
||
- **semgrep** — представляет 1 из 3 навыков плагина static-analysis (есть ещё codeql, sarif-parsing). Это НЕДОПОКРЫТИЕ охвата, не расщепление. Решить отдельно: заводить ли codeql/sarif-parsing.
|
||
- **operations-process-doc** — уже вынесенный под-навык operations (name `operations:process-doc`). При расщеплении operations — не плодить дубль, переиспользовать.
|
||
- **design-plugin** — контракт описывает 3 из 7 реальных навыков (рассогласование «контракт ↔ плагин»).
|
||
- **finance journal-entry vs journal-entry-prep** — похожие описания, проверить на дубль.
|
||
- **trail-of-bits пакет** — в кэше 8 security-плагинов (static-analysis×3, differential-review, audit-context-building, variant-analysis, supply-chain-risk-auditor, insecure-defaults, sharp-edges, agentic-actions-auditor). У нас контракт только trail-of-bits (атомарный) + semgrep. Вопрос охвата, не расщепления.
|
||
|
||
## Подсчёт «91 → ~150»
|
||
|
||
- Комков: **11** (если ui-ux-pro-max оставить материалом).
|
||
- Под-навыков в комках: ≈ 14+7+8+2+2+8+7+8+9+8+3 = **76** (с adr-kit полным) или ≈ **70** (adr-kit только adr/judge).
|
||
- Уже вынесено: 2 (writing-plans, operations-process-doc).
|
||
- Итог реестра: 91 − 11 зонтиков + ~76 под-навыков ≈ **156** (или ~150 при урезании служебных adr-kit).
|
||
|
||
→ «91» = файлов сейчас; «~150» = навыков после расщепления. Сходится.
|
||
|
||
## Решения владельца (зафиксировано 2026-06-18)
|
||
|
||
- **A. Зонтик-контракт → УБРАТЬ** (по спеке v2 §2: растворяется в под-навыки). После разворачивания удаляем `superpowers.contract.json`, `product-management.contract.json` и т.п.
|
||
- **B. adr-kit → только `adr` + `judge`** (содержательные «решатели», роутер их подбирает). Служебные init/install-hooks/lint/migrate/setup/upgrade — инфра-команды разовой настройки, в реестр НЕ тащим (роутеру нечего подбирать). *(Принято по логике «что произойдёт при вызове»; если владелец захочет иначе — поправить.)*
|
||
- **C. ui-ux-pro-max → РАЗВЕРНУТЬ на 7 с пометкой роли + правка PSR (путь 2).** По сути под-навыки (banner/slides/design-system/ui-styling…) — разные задачи, роутер подберёт точнее. НО в каждом под-контракте `constraints` фиксируют роль: «материал/решение по UI; стек приводить к Vue+Vuetify (R6.0); финальный код — Frontend Design (paired-stack)». Разворачивание UPM **тянет правку PSR** (сейчас PSR говорит «UPM — материал, не разворачивать») — отдельный аккуратный шаг нормативного синхрона.
|
||
- **D. Мелочь:** finance journal-entry vs journal-entry-prep — проверить на дубль при разворачивании (свести или оставить оба с разными визитками); semgrep-недопокрытие (codeql/sarif-parsing) — отдельной задачей охвата, не в этом разворачивании.
|
||
|
||
## Итоговый список к разворачиванию (12 комков)
|
||
|
||
| # | Комок | Новых под-навыков | Примечание |
|
||
|---|---|---|---|
|
||
| 1 | superpowers | 13 | writing-plans уже есть |
|
||
| 2 | plugin-dev | 7 | |
|
||
| 3 | adr-kit | 2 | только adr, judge |
|
||
| 4 | claude-md-management | 2 | |
|
||
| 5 | hookify | 1–2 | writing-rules (+hookify); команды не навыки |
|
||
| 6 | product-management | 8 | |
|
||
| 7 | design-plugin | 7 | контракт покрывал 3 из 7 |
|
||
| 8 | marketing-plugin | 8 | |
|
||
| 9 | operations | 8 | process-doc уже вынесен |
|
||
| 10 | finance-plugin | 7–8 | journal дубль? |
|
||
| 11 | brand-voice | 3 | |
|
||
| 12 | ui-ux-pro-max | 7 | + правка PSR |
|
||
|
||
Сумма ≈ **73–75** новых под-навыков. Реестр: 91 − 12 зонтиков + ~75 ≈ **~154**. Сходится с «~150».
|
||
|
||
## Инженерные заметки для плана (решить в плане)
|
||
|
||
- **Имя файла vs поле skill.** Поле `skill` = `плагин:навык` (с двоеточием, спека §2). НО двоеточие в имени файла на Windows запрещено → имя файла без двоеточия. Прецеденты: `writing-plans.contract.json` (просто slug), `operations-process-doc.contract.json` (дефис). **Коллизия:** `competitive-brief` есть И у product-management, И у marketing — значит имя файла ОБЯЗАНО нести плагин. Предлагаемая конвенция: `<плагин>__<навык>.contract.json` (двойное подчёркивание), поле `skill` внутри = `<плагин>:<навык>`.
|
||
- **needs/produces** на этапе разворачивания — временно прозой/скелетом; токены словаря надеваем на этапе графа (порядок «расщепить → потом граф»). Замок словаря опционален → регрессию не ломает.
|
||
- **Контент полей** под-контракта (визитка, constraints, defaults, key-decisions, acceptance) — из frontmatter `name:`/`description:` + тела SKILL.md плагина; для own-навыков — из наших источников.
|
||
|
||
## Конвенция разворачивания — ВЫВЕРЕНА пилотом claude-md-management (2026-06-18)
|
||
|
||
Пилот `claude-md-management` (2 навыка) прошёл зелёным (полная регрессия 4361 passed, 0 failed). Подтверждённый рецепт для остальных 11 комков — разворачивание трогает **ДВА файла + схему + один тест-счётчик**:
|
||
|
||
1. **Карточка** `docs/registry/contracts/<плагин>__<навык>.contract.json` (двойное подчёркивание в имени; двоеточие в имени файла Windows не держит). Поле `skill: "<плагин>:<навык>"`. `kind:external` + `source{version:"n/a", hash:<64 нуля>, path:""}` (G4 инертен). needs/produces пока краткой прозой.
|
||
2. **Узел** в `docs/registry/nodes.yaml`: зонтик `#NN` → дочерние `#NNa`, `#NNb`, … . Поля узла: `id`, `name` (≥3 симв), `slug:"<плагин>:<навык>"`, `category`, `status`, `triggers` (обязательны) + `capabilities`/`boundaries`/`chain_membership`/`attributes`.
|
||
3. **Схема** `docs/registry/schema.json`: паттерн `id` расширен на `^#\d+[a-z]?$` (допускает дочерний суффикс) — **уже сделано пилотом, для всех комков работает**. `slug` паттерн `^[a-z0-9-]+(:[a-z0-9-]+)*$` двоеточие уже допускал.
|
||
4. **Зонтик удаляется** в ОБОИХ местах: карточка (`<плагин>.contract.json`) + узел `#NN`. Карточку удалять скриптом-файлом (`node tools/_del.mjs` с `unlinkSync`) — пол режет `rm`.
|
||
5. **Цепочки L** (`chain_membership` + ссылки на `#NN` в `chains:`): трогать минимально (заменить ссылку `#NN` на slug под-узла). **Полный снос L1-L17 — отдельный эпик** (спека §2): затрагивает `registry-load.mjs` (`chains`/`findChainsByNode`), `node-graph.mjs` (`relatedByChain`), `schema.json` (`chains` в `required`), их тесты. НЕ смешивать с разворачиванием.
|
||
6. **Счётчик узлов:** `tools/registry-load.test.mjs` хардкодит число узлов (`toHaveLength(N)`) и активных — обновлять на каждый комок (разворачивание `#NN`→k под-узлов даёт +(k−1) узлов и активных).
|
||
7. **Инвариант-сторож** `tools/m3e-card-coverage-invariants.test.mjs` ловит рассинхрон «узел↔карточка» — НЕ глушить, а синхронизировать оба места.
|
||
|
||
**Артефакты пилота:** план `docs/superpowers/plans/2026-06-18-split-pilot-claude-md-management.md`, тест `tools/split-pilot-claude-md.test.mjs`. Контракты: `claude-md-management__claude-md-improver`, `claude-md-management__revise-claude-md`. Узлы: `#33a`, `#33b`. Закоммичено + запушено: `e98ba1e` (gitea/main).
|
||
|
||
## Прогресс разворачивания
|
||
|
||
| Комок | Статус | Коммит |
|
||
|---|---|---|
|
||
| claude-md-management (2) | ✅ DONE | e98ba1e (pushed) |
|
||
| superpowers (14) | ✅ DONE | 5a7c5c2 (pushed) |
|
||
| plugin-dev (7) | ✅ DONE | этот коммит |
|
||
| adr-kit (2: adr, judge) | ⬜ | |
|
||
| hookify (1–2) | ⬜ | |
|
||
| product-management (8) | ⬜ | |
|
||
| design-plugin (7) | ⬜ | |
|
||
| marketing-plugin (8) | ⬜ | |
|
||
| operations (8) | ⬜ | |
|
||
| finance-plugin (7–8) | ⬜ | |
|
||
| brand-voice (3) | ⬜ | |
|
||
| ui-ux-pro-max (7, +правка PSR) | ⬜ | |
|
||
|
||
### Доп-каскады, выявленные на superpowers (учесть для крупных комков)
|
||
|
||
- **Классификации-триггеры зонтика** (`classification: feature/planning/bugfix/refactor` + `keyword`) надо РАСПРЕДЕЛИТЬ по под-узлам, иначе роутер теряет подбор по классу. На superpowers: feature→brainstorming(#19a), planning→writing-plans(#19c), tdd→TDD(#19b), debug/bugfix→debugging(#19d), refactor→TDD. Каскад на `registry-load.test` (`findByClassification('feature')[0].node.id`) + потенциально `router-classifier.test`.
|
||
- **Хардкод-образцы в тестах.** `m3a-contract-invariants` (own-образец) и `m3c-coverage-invariants` (контракты 3-A) читали `writing-plans.contract.json` по имени → миграция сломала; обновлены на `marketing-ru` (own) и `superpowers__writing-plans`. При разворачивании других комков — грепать имя контракта по тестам ПЕРЕД удалением.
|
||
- **Частично-вынесенные карточки** (как `writing-plans` без префикса/узла, kind own) — привести к конвенции: skill `<плагин>:<навык>`, файл `<плагин>__<навык>`, kind external, завести узел.
|
||
- **Генератор карточек** (`tools/_gen-<плагин>.mjs`, самоудаляемый, данные внутри) — рабочий приём для комков с многими навыками: пишет N JSON + удаляет зонтик/кривые карточки. Узлы YAML — отдельным Edit-блоком.
|
||
|
||
**Артефакты superpowers:** 14 карточек `superpowers__*.contract.json`, узлы `#19a..#19n`, схема (id-паттерн уже расширен пилотом). Тесты обновлены: `registry-load.test` (103 узла/95 active, feature→#19a), `m3a`/`m3c` (образцы). Регрессия: 4361 passed, 0 failed. **Не закоммичено.**
|