new-metadata-item

name	new-metadata-item
description	Создание нового объекта метаданных (metadataItem) по фикстурам и схемам. При добавлении новых объектов метаданных используй этот скилл.

Добавление нового объекта метаданных

Скилл запускает сценарий добавления или существенной правки metadataItem. Устойчивые правила реализации живут в .agents/knowledge/metadata/.

Перед работой обязательно прочитай:

1. .agents/knowledge/metadata/INDEX.md
2. .agents/knowledge/metadata/sources-of-truth.md
3. .agents/knowledge/metadata/metadata-item-implementation.md
4. .agents/knowledge/metadata/round-trip-cycle.md
5. .agents/knowledge/metadata/yaml-contract.md
6. .agents/knowledge/metadata/registries.md

Точка входа

Новый объект — начинай с брифа из .agents/knowledge/metadata/metadata-item-implementation.md.

Существующий объект — начинай с XML-цикла из .agents/knowledge/metadata/round-trip-cycle.md. Если XML-цикл уже зелёный и проблема только в YAML, начинай с YAML-цикла.

Шаг 1. Бриф (последовательный)

Не задавай всё списком. Перед каждым вопросом быстро исследуй кодовую базу и спрашивай только то, что не выводится из кода, схемы или соседей. Базовый список брифа — в .agents/knowledge/metadata/metadata-item-implementation.md.

Пункты брифа — в этом порядке, по одному:

XML-сторона:

1. Путь к каталогу нового объекта метаданных (обычно дан в аргументе команды).
2. XML-фикстуры — проверь, что в __fixtures__/ лежит 1–3 файла с разным заполнением. Если меньше — попроси добавить до продолжения.
3. Схема объекта (XSD) — её нужно получить от пользователя, если в репозитории нет соответствующего .xsd.
4. Свойства, не встречающиеся в XML-фикстурах (например, runtimeOnly-поля) — запроси отдельным пунктом с типом и признаком runtimeOnly.
5. Родительский каталог для index.ts — выводится из пути аргумента.
6. Дочерние коллекции — извлеки из XML-фикстуры, подтверди наличие/отсутствие.
7. Известные ограничения: только для чтения из XML, только для записи и т.п. — явный вопрос.

YAML-сторона (обязательно спрашиваем заранее, хотя применим только на шаге 11):

8. YAML-имена ключей для каждого свойства (проверь types.ts / соседний metadataItem — если там уже есть XxxYAML-интерфейс, показывай его и проси подтверждения).
9. itemTypePrefix — YAML-префикс объекта верхнего уровня (например, "Нумератор", "Документ", "Перечисление").
10. Для каких свойств нужен defaultValueYAML — чтобы в YAML при экспорте опускались значения-дефолты.
11. Свойства, исключённые из YAML (toYAML: false, fromYAML: false) — обычно технические/служебные.
12. Особые YAML-флаги на полях (excludeIfEqualNameYAML, useAsShortValueYAML) — только если пользователь их знает; иначе — по аналогии с соседом, явно предложи.

Правило для каждого пункта: если ответ виден в коде или схеме — не спрашивай, показывай пользователю что ты нашёл и проси подтверждения/корректировки.

Без брифа не начинай реализацию.

Шаг 2. Анализ

Прочитай XML-фикстуры, схему, список свойств и 1–2 похожих metadataItem. Источники истины и приоритеты — в .agents/knowledge/metadata/sources-of-truth.md.

Шаг 3. types.ts

Создай или обнови файл типов по шаблону types.md.

Шаг 4. rules.ts — первое приближение ⟲

Создай или обнови файл правил по шаблону rules.md.

Правило: предпочитай rules.ts вместо ручных fromXML/toXML/fromYAML/toYAML.

Шаг 5. Регистрация типов

Без регистрации round-trip не запустится. Проверь и обнови реестры по .agents/knowledge/metadata/registries.md, а привязку правила к типу делай по types.md.

Шаг 6. index.ts

Создай или обнови index.ts в каталоге объекта и экспорт вышестоящего каталога.

---

XML-цикл

Шаги 7–10 образуют цикл из .agents/knowledge/metadata/round-trip-cycle.md. Ошибка на любом шаге → фикс rules.ts → перезапуск с шага 7.

Шаг 7. XML round-trip ⟲ (жёсткий барьер)

Напиши fromXML.test.ts с round-trip блоком. Шаблоны и протокол эскалации — в tests.md, порядок цикла — в .agents/knowledge/metadata/round-trip-cycle.md.

Если расхождение относится к подчинённому metadataItem, остановись и спроси пользователя: укажи имя, путь и XML-фрагмент. Не правь чужой rules.ts сам.

Шаг 8. TS-фикстуры

На каждую XML-фикстуру <name>.xml создай отдельный TS-файл __fixtures__/<name>.ts с ожидаемой формой объекта. Подробнее — fixtures-data.md.

YAML-поля на этом шаге не заполняй — <fixtureName>YAML добавляется на шаге 11 после обсуждения черновика YAML в барьере.

Существующие объекты метаданных, ещё использующие единый data.ts, не переписывай насильно. Новая конвенция применяется к новым фикстурам; старые мигрируют при естественной правке.

Шаг 9. fromXML тест

Допиши в fromXML.test.ts блок it("import <name>") для каждой XML-фикстуры. Round-trip блок остаётся как регресс. Если тест падает → фикс → перезапуск XML-цикла.

Шаг 10. toXML тест

Создай toXML.test.ts по tests.md. Если тест падает → фикс → перезапуск XML-цикла.

---

Барьер: обсуждение YAML-структуры

Не переходи к YAML-циклу, пока XML-цикл не завершён полностью. Сгенерируй черновик YAML по .agents/knowledge/metadata/yaml-contract.md и аналогии с соседями. Без подтверждения пользователя YAML-правила не пиши.

---

YAML-цикл

Шаги 11–13 образуют цикл из .agents/knowledge/metadata/round-trip-cycle.md. Ошибка на любом шаге → фикс rules.ts → перезапуск с шага 11.

Шаг 11. YAML round-trip ⟲ (жёсткий барьер)

Допиши YAML-часть в rules.ts, добавь <fixtureName>YAML в TS-фикстуры и напиши fromYAML.test.ts с round-trip блоком. Шаблоны — tests.md, YAML-контракт — .agents/knowledge/metadata/yaml-contract.md.

Если расхождение относится к подчинённому metadataItem, остановись и спроси пользователя: укажи имя, путь и YAML-фрагмент. Не правь чужой rules.ts сам.

Шаг 12. fromYAML тест

Допиши в fromYAML.test.ts проверку импорта. Round-trip остаётся как регресс. Если тест падает → фикс → перезапуск YAML-цикла.

Шаг 13. toYAML тест

Создай toYAML.test.ts. Если тест падает → фикс → перезапуск YAML-цикла.

---

Шаг 14. Отчёт о покрытии

В финальном сообщении пользователю приведи явный список свойств, не покрытых ни одной XML-фикстурой (правила написаны, но поведение не проверено). Пользователь решает, докидывать ли фикстуру.

Формат:

Покрытие свойств фикстурами: 12/15
Непокрытые: Parent, Comment, UseStandardCommand

Ссылки

• rules.md — правила
• types.md — типы
• fixtures-data.md — TS-фикстуры
• tests.md — round-trip, протокол эскалации, раздельные тесты
• scripts.md — вспомогательные раннеры для печати YAML/XML