Контрольный список развёртывания

Шаги предварительной проверки перед развёртыванием экосистемы Apothem на новой машине, её совместным использованием с другими или признанием её готовой к продакшену.

1. Валидность YAMLCopy Anchor Link

• Все файлы правил разбираются без ошибок YAML — блок frontmatter открывается ---, закрывается --- и не содержит осиротевшего контента за пределами блока
• Все файлы делегированных исполнителей разбираются без ошибок YAML
• Все файлы команд разбираются без ошибок YAML
• Все файлы навыков SKILL.md разбираются без ошибок YAML

Проверка: python scripts/dev/validate_ecosystem.py разбирает frontmatter каждого артефакта и помечает ошибки YAML и отсутствующие обязательные поля. Для специальной проверки осиротевших элементов списка: rg -n "^- " src/apothem/rules/*.md.

2. Полнота frontmatterCopy Anchor Link

Для каждого типа артефакта убедитесь, что обязательные поля присутствуют:

Правила (src/apothem/rules/*.md)Copy Anchor Link

• name — идентификатор в kebab-case, совпадающий с именем файла
• description — однострочное резюме
• alwaysApply — true для правил, которые действуют всегда, false для правил с фильтром по путям
• pathFilter — присутствует в каждом правиле: "" для правил, которые действуют всегда (alwaysApply: true), список glob-шаблонов через запятую для правил с фильтром по путям (alwaysApply: false)

Правила не содержат ключей version, updated, scope или portability.

Команды (src/apothem/commands/*.md)Copy Anchor Link

• name — имя команды в kebab-case
• version, updated, description, argument-hint, portability, allowed-tools присутствуют
• disable-model-invocation присутствует и намеренно (false для команд только для чтения или рекомендательных команд; true только когда выполнение команды меняет состояние за пределами рабочего дерева или зависит от выбора момента оператором)
• Ключа effort нет: command.schema.json задаёт additionalProperties: false и его не допускает

Делегированные исполнителиCopy Anchor Link

Путь:

src/apothem/agents/*.md

• name, version, updated, description присутствуют
• tools — список разрешённых инструментов через запятую
• disallowedTools — явно перечисляет запрещённые инструменты
• maxTurns — задан (с комментарием-обоснованием, если > 10)
• permissionMode — НЕ должен быть "bypassPermissions"; не задавайте ключ, поскольку нейтральная (agnostic) конфигурация заранее не задаёт режим разрешений
• memory не указан, если постоянная память не предусмотрена намеренно; если указан, то одно из значений user, project, local (логической формы нет)

Навыки (src/apothem/skills/*/SKILL.md)Copy Anchor Link

• name, version, updated, description, archetype, disable-model-invocation, allowed-tools присутствуют
• userInvocable объявлено (true/false). В исходнике используется написание userInvocable; навык несёт ровно одно из userInvocable или user-invocable (написание Claude Code).

3. БезопасностьCopy Anchor Link

• Ни один делегированный исполнитель не использует permissionMode: "bypassPermissions" — это обходит интерактивное подтверждение для операций Write/Bash
• Списки tools исполнителя минимальны — только те инструменты, которые исполнителю действительно нужны
• Исполнители с доступом к Bash обоснованы и имеют ограничения maxTurns
• Ни в одном артефакте нет жёстко прописанных путей, токенов или секретов
• Хуки в settings.json имеют разумные таймауты (≤ 60 секунд) и не выполняют произвольный код из пользовательского ввода

4. Целостность перекрёстных ссылокCopy Anchor Link

• Каждое правило, перечисленное в таблице src/apothem/rules/, существует на диске по указанному пути
• Каждая команда, перечисленная в таблице src/apothem/commands/, существует на диске
• Каждый делегированный исполнитель, перечисленный в таблице реестра src/apothem/agents/, существует на диске
• Каждый навык, перечисленный в таблице src/apothem/skills/, существует на диске
• Каждый хук в таблице src/apothem/hooks/ имеет соответствующую запись в settings.json
• Все файлы src/apothem/rules/*.md существуют, и их перекрёстные ссылки Bindings разрешаются

5. Покрытие предписанийCopy Anchor Link

• Каждое предписание CM-N имеет место применения (либо файл правила, либо явное встроенное определение)
• Ни один файл правила не противоречит другому (особенно в части масштабирования серьёзности)
• Разграничение трёх граней CM-21 соблюдается — ни одно правило не претендует на владение гранью CM-21 другого правила

6. Функциональные дымовые тестыCopy Anchor Link

Сначала запустите поверхность проверки на Python — она быстрая, автономная и отлавливает структурные регрессии:

• pytest tests — модульные тесты среды выполнения хуков, все зелёные
• python scripts/dev/validate_hooks.py — проверка структуры хуков + гигиены только-Python пройдена
• python scripts/dev/validate_ecosystem.py — полное дерево + frontmatter + проверки делегированных хуков пройдены
• python scripts/dev/chaos_pass.py — каждая настроенная команда хука возвращает корректный JSON-конверт при деградированных входных данных

Затем живые сценарии:

• /plan-spec <sample-file> — завершает приём и уточнение без ошибок уровня команды
• /plan-generate --dry-run — выдаёт предпросмотр структуры без записи файлов
• /plan-status на полном наборе планов — возвращает точное количество фаз
• Диспетчеризация делегированного исполнителя: исполнитель codebase-explorer, вызванный с небольшим охватом, завершается в пределах maxTurns и возвращает структурированный вывод

7. Актуальность документацииCopy Anchor Link

• CHANGELOG.md (в корне экосистемы) отражает каждое изменение артефакта с момента последнего выпуска; раздел следующего выпуска заполнен до того, как ляжет тег, или каждое изменение уже включено в опубликованный раздел
• site/content/docs/developer-guide.mdx точно описывает текущую структуру артефактов
• site/content/docs/reference/artifact-schema.mdx соответствует полям frontmatter, фактически присутствующим в артефактах
• site/content/docs/reference/settings-reference.mdx соответствует фактической конфигурации хуков в settings.json
• README.md согласован с деревом на диске

8. Переносимость (при совместном использовании с другими)Copy Anchor Link

• Все пути в командах хуков не зависят от среды или используют раскрытие ~
• Команды хуков используют форму exec и избегают строк команд, специфичных для конкретной оболочки
• Ни в одном артефакте нет жёстко прописанных путей C:\Users\username или /home/username
• settings.json использует одну таблицу охвата событий хуков и канонический путь к модулю диспетчеризации

9. Согласование версийCopy Anchor Link

• version в CLAUDE.md является наивысшей среди всех артефактов в дереве (или, по соглашению, равна версии самого недавно повышенного артефакта)
• version каждого артефакта совпадает с заявленным semver (MAJOR.MINOR.PATCH)
• CHANGELOG.md содержит ровно запись о выпуске для целевой версии перед тегированием
• Поле updated каждого артефакта соответствует дате его последнего изменяющего поведение редактирования или позже
• Ни один артефакт не несёт version ниже версии, на которой его в последний раз изменяли (без регрессий)
• src/apothem/skills/plan-suite/SKILL.md и src/apothem/skills/plan-suite/master-template.md закреплены на одной и той же линии версии шаблона

УтверждениеCopy Anchor Link

Развёртывание одобрено: ___________________ Дата: ___________________ Развёрнутая версия экосистемы: ___________________