feat: разворачивание комка claude-md-management — пилот реестра роутера
Эпик роутер-реестр, спека v2 §2. Развёрнут самый маленький комок-зонтик в 2 отдельные карточки-навыка ради точного подбора роутером. Пилот выверил конвенцию для остальных 11 комков. - 2 карточки: claude-md-management__claude-md-improver + __revise-claude-md; поле skill = плагин:навык, kind external, zero-hash source - nodes.yaml: узел #33 развёрнут в дочерние #33a/#33b; ссылка L12 обновлена - schema.json: паттерн id расширен на дочерний суффикс #NNa - registry-load.test: счётчики узлов 89 в 90, active 81 в 82 - splitting-inventory.md: инвентаризация 12 комков + выверенная конвенция - тест-сторож split-pilot-claude-md + план пилота Регрессия свода: 4361 passed, 0 failed. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
This commit is contained in:
Дмитрий
@@ -0,0 +1,138 @@
|
||||
# Пилот разворачивания комка: claude-md-management — Implementation Plan
|
||||
|
||||
> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
|
||||
|
||||
**Goal:** Развернуть комок `claude-md-management.contract.json` (зонтик плагина) в 2 отдельные карточки-навыка `claude-md-management:claude-md-improver` и `claude-md-management:revise-claude-md`, удалив зонтик — и тем самым **выверить конвенцию разворачивания** для остальных 11 комков эпика.
|
||||
|
||||
**Architecture:** Каждый под-навык — отдельный `.contract.json`. Поле `skill` = `<плагин>:<навык>` (двоеточие; валидатор `validateContract` его допускает — проверено). Имя файла двоеточие на Windows не держит → конвенция имени `<плагин>__<навык>.contract.json` (двойное подчёркивание; нужно, т.к. короткий slug коллизирует — `competitive-brief` есть и у product-management, и у marketing). Зонтик-контракт удаляется (спека v2 §2: растворяется в под-навыки). `needs/produces` пока краткой прозой — токены словаря наденем на этапе графа (порядок эпика «расщепить → потом граф»; замок словаря опционален, регрессию не ломает). `kind: external` + `source{version:"n/a", hash:<64 нуля>, path:""}` как у текущего зонтика → G4-страж дрейфа инертен (официальный плагин, версию не сторожим).
|
||||
|
||||
**Tech Stack:** Node ESM, vitest, JSON-контракты в `docs/registry/contracts/`, модули `tools/skill-contract.mjs` + `tools/skill-contract-registry.mjs`.
|
||||
|
||||
---
|
||||
|
||||
## File Structure
|
||||
|
||||
- **Create:** `docs/registry/contracts/claude-md-management__claude-md-improver.contract.json` — карточка навыка audit/targeted-updates.
|
||||
- **Create:** `docs/registry/contracts/claude-md-management__revise-claude-md.contract.json` — карточка навыка захвата learnings.
|
||||
- **Delete:** `docs/registry/contracts/claude-md-management.contract.json` — зонтик (растворён).
|
||||
- **Create (test):** `tools/split-pilot-claude-md.test.mjs` — проверяет: оба под-контракта валидны и грузятся реестром; зонтик отсутствует; весь каталог формо-валиден (errors === []).
|
||||
|
||||
---
|
||||
|
||||
## Цель
|
||||
|
||||
Выверить на самом маленьком комке (2 навыка) полную механику разворачивания: имя файла без двоеточия, поле `skill` с двоеточием, удаление зонтика, прохождение валидатора, отсутствие регрессии в реестре/охвате. Конвенция, подтверждённая пилотом, переиспользуется планами кластеров (superpowers, product-management, …). Источник — спека v2 §2 (D2) + реестр `docs/registry/splitting-inventory.md`.
|
||||
|
||||
---
|
||||
|
||||
### Task 1: Тест пилота (RED)
|
||||
|
||||
**Files:**
|
||||
- Create: `tools/split-pilot-claude-md.test.mjs`
|
||||
|
||||
- [ ] **Шаг 1: Написать падающий тест**
|
||||
|
||||
```js
|
||||
import { describe, it, expect } from 'vitest';
|
||||
import { loadRegistry } from './skill-contract-registry.mjs';
|
||||
|
||||
const DIR = 'docs/registry/contracts';
|
||||
|
||||
describe('пилот разворачивания claude-md-management', () => {
|
||||
const reg = loadRegistry({ dir: DIR });
|
||||
const skills = reg.contracts.map((c) => c.skill);
|
||||
|
||||
it('весь каталог контрактов формо-валиден (нет ошибок сборки)', () => {
|
||||
expect(reg.errors).toEqual([]);
|
||||
});
|
||||
|
||||
it('зонтик claude-md-management удалён', () => {
|
||||
expect(skills).not.toContain('claude-md-management');
|
||||
});
|
||||
|
||||
it('оба под-навыка заведены с адресацией плагин:навык', () => {
|
||||
expect(skills).toContain('claude-md-management:claude-md-improver');
|
||||
expect(skills).toContain('claude-md-management:revise-claude-md');
|
||||
});
|
||||
});
|
||||
```
|
||||
|
||||
- [ ] **Шаг 2: Прогнать тест — убедиться, что падает**
|
||||
|
||||
Run: `npx vitest run tools/split-pilot-claude-md.test.mjs`
|
||||
Expected: FAIL — зонтик ещё на месте (`skills` содержит `claude-md-management`), под-навыков ещё нет.
|
||||
|
||||
### Task 2: Создать карточку claude-md-improver
|
||||
|
||||
**Files:**
|
||||
- Create: `docs/registry/contracts/claude-md-management__claude-md-improver.contract.json`
|
||||
|
||||
- [ ] **Шаг 3: Записать контракт**
|
||||
|
||||
```json
|
||||
{
|
||||
"skill": "claude-md-management:claude-md-improver",
|
||||
"kind": "external",
|
||||
"needs": ["намерение проверить/улучшить CLAUDE.md (audit или точечные правки структуры/правил §5)"],
|
||||
"produces": ["quality-report по CLAUDE.md (rubric) + targeted-правки файла"],
|
||||
"constraints": ["один из двух входов плагина claude-md-management", "правка CLAUDE.md — только через этот канал (§5 п.10)", "внутри flow — синхрон Pravila+Tooling (п.7)"],
|
||||
"preview-form": "none",
|
||||
"defaults": ["claude-md-improver — для структурных изменений, добавления/удаления секций, правок правил §5 и версии в шапке"],
|
||||
"key-decisions": ["audit целиком vs точечная правка конкретной секции"],
|
||||
"acceptance-criteria": ["quality-report выдан ДО правок; правки targeted; нормативка синхронна"],
|
||||
"source": { "version": "n/a", "hash": "0000000000000000000000000000000000000000000000000000000000000000", "path": "" }
|
||||
}
|
||||
```
|
||||
|
||||
### Task 3: Создать карточку revise-claude-md
|
||||
|
||||
**Files:**
|
||||
- Create: `docs/registry/contracts/claude-md-management__revise-claude-md.contract.json`
|
||||
|
||||
- [ ] **Шаг 4: Записать контракт**
|
||||
|
||||
```json
|
||||
{
|
||||
"skill": "claude-md-management:revise-claude-md",
|
||||
"kind": "external",
|
||||
"needs": ["намерение захватить learnings текущей сессии в CLAUDE.md"],
|
||||
"produces": ["CLAUDE.md дополнен session-learnings (новые quirks/команды/паттерны)"],
|
||||
"constraints": ["один из двух входов плагина claude-md-management", "правка CLAUDE.md — только через этот канал (§5 п.10)", "внутри flow — синхрон Pravila+Tooling (п.7)"],
|
||||
"preview-form": "none",
|
||||
"defaults": ["revise-claude-md — для захвата learnings из текущей сессии"],
|
||||
"key-decisions": ["что из сессии достойно CLAUDE.md, а что — memory"],
|
||||
"acceptance-criteria": ["learnings внесены через плагин; нормативка синхронна"],
|
||||
"source": { "version": "n/a", "hash": "0000000000000000000000000000000000000000000000000000000000000000", "path": "" }
|
||||
}
|
||||
```
|
||||
|
||||
### Task 4: Удалить зонтик
|
||||
|
||||
**Files:**
|
||||
- Delete: `docs/registry/contracts/claude-md-management.contract.json`
|
||||
|
||||
- [ ] **Шаг 5: Удалить файл зонтика**
|
||||
|
||||
Удалить `docs/registry/contracts/claude-md-management.contract.json` (через файловую операцию; под полом — скриптом-файлом `os.remove`, не `rm`).
|
||||
|
||||
### Task 5: Зелёный прогон + регрессия
|
||||
|
||||
- [ ] **Шаг 6: Прогнать тест пилота — убедиться, что проходит**
|
||||
|
||||
Run: `npx vitest run tools/split-pilot-claude-md.test.mjs`
|
||||
Expected: PASS — все 3 теста зелёные.
|
||||
|
||||
- [ ] **Шаг 7: Полная регрессия реестра/охвата**
|
||||
|
||||
Run: `npx vitest run` (полный свод из корня claude-brain — было 118 зелёных)
|
||||
Expected: PASS — ни один тест не опирался на зонтик `claude-md-management`; число контрактов выросло на 1 (−1 зонтик +2 под-навыка). Если какой-то тест ассертит точное число контрактов или наличие `claude-md-management` — поправить тот тест (ожидаемое следствие разворачивания, зафиксировать в плане кластера).
|
||||
|
||||
---
|
||||
|
||||
## Само-ревью (по навыку)
|
||||
|
||||
- **Покрытие спеки:** план реализует §2 спеки v2 (адресация `плагин:навык`, растворение зонтика) в режиме пилота на 1 комке — для выверки конвенции перед массовой раскаткой (§8 «стадийно»).
|
||||
- **Плейсхолдеры:** нет — тест-код и оба контракта приведены целиком с реальным контентом из SKILL.md / нашей нормативки.
|
||||
- **Согласованность типов:** поле `skill` со значением `плагин:навык` проходит `validateContract` (требует лишь non-empty string); `kind:external` требует `source{version,hash}` — заданы (hash 64-hex нулей, как у зонтика); `preview-form:none` — в enum. Имя файла `__` проходит фильтр `loadRegistry` (`.endsWith('.contract.json')`).
|
||||
- **Регрессия:** Шаг 7 — полный свод; риск только у теста, жёстко завязанного на старый зонтик (поправить точечно).
|
||||
- **Выход пилота:** подтверждённая конвенция (имя файла `<плагин>__<навык>`, поле `skill:<плагин>:<навык>`, external+zero-hash, удаление зонтика, регрессия зелёная) → переиспользуется планами кластеров.
|
||||
Reference in New Issue
Block a user