Спецификация схемы артефактов

Шаблоны YAML-фронтматтера по классам и обязательные поля для всех артефактов экосистемы Apothem.

Источник истины. Машиночитаемый контракт, который применяет шлюз, — это JSON Schema по классам в src/apothem/schemas/ (agent.schema.json, command.schema.json, skill.schema.json, …). Схемы навыков и команд объявляют additionalProperties: false, поэтому отклоняют неизвестные ключи; схемы агентов, output-стилей и планов объявляют additionalProperties: true. Эта страница и frontmatter-schema.mdx — две человекочитаемые проекции этих схем: данная страница содержит шаблоны и разобранные примеры по классам, а frontmatter-schema — краткий указатель обязательных ключей. Если страница расходится с JSON Schema, приоритет у схем.

ОбзорCopy Anchor Link

Все артефакты в дереве исходного кода Apothem (в src/apothem/ и на корневой поверхности конфигурации) должны содержать блок YAML-фронтматтера (между разделителями ---) с обязательными и необязательными полями, специфичными для их типа артефакта. Этот документ определяет каноническую схему для каждого типа.

Универсальные правила:

• Фронтматтер соответствует YAML 1.2
• Все строковые значения записываются в двойных кавычках, а пустая строка записывается как ""
• Порядок полей: сначала обязательные поля, затем необязательные, сгруппированные по смыслу
• Комментарии во фронтматтере записываются через # с пробелом: # comment
• Значения путей должны быть относительными (без ведущего /) и использовать прямые слеши (/) для кроссплатформенной совместимости

Соглашение о версионировании (версионируемые классы артефактов — команды, помощники, навыки, CLAUDE.md):

• version — семантическая версия (MAJOR.MINOR.PATCH). Повышайте MAJOR при ломающих изменениях схемы или контракта; MINOR — при аддитивных изменениях без нарушения совместимости (новые необязательные поля, дополнительные разделы, дополнительные антипаттерны); PATCH — при изменении поведения, которое исправляет существующую директиву, не нарушая контракт.
• Исправления опечаток, ссылок, форматирование, а также правки, затрагивающие только комментарии или только документацию, не меняют version. Версию повышает только изменение поведения.
• updated — дата ISO 8601 (YYYY-MM-DD) последней правки. Она должна меняться при каждом повышении version и меняется также при исправлении опечатки или ссылки, не повышающем версию.
• Новые артефакты начинают с v0.Y.Z. Переход на vX.Y.Z означает, что контракт артефакта достаточно стабилен, чтобы стать публичным обязательством.
• Наборы планов не входят в эту конвенцию. Исправление опечатки в наборе планов повышает номер PATCH версии набора (vX.Y.Z → vX.Y.(Z+1)) и добавляет строку в таблицу истории ревизий. В руководстве разработчика правило для наборов планов описано в разделе о ревизиях набора планов.

Схема: правилаCopy Anchor Link

Шаблон пути: src/apothem/rules/*.md

Назначение: поведенческие мандаты и операционные директивы.

Обязательные поляCopy Anchor Link

---
name: "kebab-case-identifier"
description: "One-line description"
pathFilter: "**/*.py, **/*.toml"
alwaysApply: true | false
---

Необязательные поляCopy Anchor Link

У правил нет необязательных полей фронтматтера и — в отличие от других классов артефактов — нет также полей version / updated / scope / portability. Четыре обязательных поля выше составляют полный контракт фронтматтера правил, который применяет frontmatter_grep.

ПримерCopy Anchor Link

---
name: "operational-mandates"
description: "Behavioral definitions for CM-1 through CM-10: violation indicators and recovery actions"
pathFilter: ""
alwaysApply: true
---

# Rule: Operational Mandates
...

Схема: командыCopy Anchor Link

Шаблон пути: src/apothem/commands/*.md

Назначение: определения слеш-команд (/plan-execute, /freshify и т. д.).

Обязательные поляCopy Anchor Link

---
name: "command-name"
version: "MAJOR.MINOR.PATCH"
updated: "YYYY-MM-DD"
description: "What this command does"
argument-hint: "[argument-pattern]"
disable-model-invocation: true | false
portability: "universal"
allowed-tools: "Read, Glob, Grep"
---

Необязательные поляCopy Anchor Link

У команд нет необязательных полей фронтматтера — восемь обязательных полей выше составляют полный контракт фронтматтера команд, который применяет command.schema.json (additionalProperties: false).

ПримерCopy Anchor Link

---
name: "plan-execute"
version: "X.Y.Z"
updated: "2026-04-20"
description: "Executes a specific phase from a Master Plan Suite with conformity checking and quality gates"
argument-hint: "[path/to/plan-suite/] [phase-id] [--dry-run]"
disable-model-invocation: true
portability: "universal"
allowed-tools: "Read, Glob, Grep"
---

# /plan-execute — Execute a Specific Phase
...

Схема: помощникиCopy Anchor Link

Шаблон пути:

src/apothem/agents/*.md

Назначение: постоянные определения помощников (их также называют делегированными исполнителями) для параллельного исследования, аудита и шлюзов качества.

Обязательные поляCopy Anchor Link

---
name: "agent-name"
version: "MAJOR.MINOR.PATCH"
updated: "YYYY-MM-DD"
description: "What this agent specializes in"
tools: "Tool1, Tool2, Tool3"
disallowedTools: "Write, Edit"
maxTurns: 20
effort: "high" | "medium" | "low"
---

Необязательные поляCopy Anchor Link

permissionMode: "default"       # Permission handling
memory: user | project | local  # Persistent-memory scope; omit for none
pattern: "Research" | "Audit" | "Implementation" | "Quality"  # Agent team pattern
portability: "universal"

ПримерCopy Anchor Link

---
name: "codebase-explorer"
version: "X.Y.Z"
updated: "2026-04-20"
description: "Deep codebase exploration — find patterns, trace dependencies, discover conventions, map architecture"
tools: "Read, Glob, Grep, Bash"
disallowedTools: "Write, Edit, TodoWrite"
maxTurns: 20
effort: "high"
permissionMode: "default"
portability: "universal"
---

You are a codebase exploration specialist...

Схема: навыкиCopy Anchor Link

Шаблон пути: src/apothem/skills/*/SKILL.md

Назначение: переиспользуемые определения техник с сигналами обнаружения и процедурами выполнения.

Обязательные поляCopy Anchor Link

---
name: "skill-name"
version: "MAJOR.MINOR.PATCH"
updated: "YYYY-MM-DD"
description: "What this skill teaches"
archetype: "workflow-template"
userInvocable: true | false
disable-model-invocation: true | false
allowed-tools: "Read, Glob, Grep"
---

Необязательные поляCopy Anchor Link

argument-hint: "[args...]"                           # Usage pattern if userInvocable

ПримерCopy Anchor Link

---
name: "ecosystem-audit"
version: "X.Y.Z"
updated: "2026-04-20"
description: "Comprehensive blind audit of the apothem ecosystem"
archetype: "audit-template"
userInvocable: true
disable-model-invocation: false
allowed-tools: "Read, Glob, Grep, Agent, TodoWrite"
argument-hint: "[--focus area] [--fix]"
---

## Purpose
...

Схема: хукиCopy Anchor Link

Шаблон пути: блок hooks в settings.json плюс реализации на Python в src/apothem/hooks/.

Назначение: объявлять валидаторы, запускаемые событиями, и обработчики управления состоянием, которые хост вызывает в чётко определённых точках жизненного цикла.

Схема файла настроекCopy Anchor Link

Ключ верхнего уровня hooks сопоставляет имена событий с массивами блоков matcher:

"hooks": {
  "<EventName>": [
    {
      "matcher": "<pattern>",
      "hooks": [
        {
          "type": "command",
          "command": "${PYTHON_BIN}",
          "args": ["${HARNESS_ROOT}/.apothem/support/hooks/dispatch.py", "<EventName>", "<message-name>"],
          "timeout": <seconds>,
          "statusMessage": "<short human-readable label>"
        }
      ]
    }
  ]
}

Форма -m apothem.hooks.dispatch предназначена для разработки из чекаута исходного кода с PYTHONPATH=src.

Обязательные событияCopy Anchor Link

Шаблон Claude Code регистрирует четыре события: SessionStart, PreToolUse, PostToolUse и Stop. scripts/dev/validate_hooks.py проверяет наличие в settings.json пяти событий из таблицы ниже — это другой набор — и сообщает о каждом ненайденном событии как о предупреждении, а не как об ошибке. PostToolUse зарегистрировано, но не входит в число этих пяти. PreCompact и PostCompact входят в число пяти, но в Claude Code не регистрируются (справочник по хукам), поэтому проверка выдаёт предупреждения по обоим.

Значения тайм-аутов повторяют канонические бюджеты событий хуков — таблица ниже воспроизводит их для удобства читателя; определяющим остаётся канонический источник.

dispatch.py также принимает UserPromptSubmit и Notification в своём белом списке событий ради прямой совместимости; ни одно из них не подключено в поставляемых шаблонах. Чтобы включить их, добавьте блок matcher с тем же шаблоном exec-формы.

Слой PythonCopy Anchor Link

Каждая команда хука проходит через один и тот же диспетчер на Python:

ВалидацияCopy Anchor Link

scripts/dev/validate_hooks.py обеспечивает соблюдение контракта хуков:

• settings.json разбирается как JSON и объявляет каждое из пяти событий таблицы; отсутствие события — это предупреждение, а не ошибка.
• Все три скрипта Python существуют и разбираются как корректный Python.
• Все файлы сообщений, на которые ссылаются аргументы --context-file, существуют.
• В src/apothem/hooks/**.py нет жёстко заданных абсолютных пользовательских путей (C:\Users\... и т. п.).
• Shell-артефакты в src/apothem/hooks/ и scripts/ ограничены одобренными заглушками локатора / начальной загрузки.

Схема: CLAUDE.mdCopy Anchor Link

Путь: CLAUDE.md (корень)

Назначение: инструкции Claude Code уровня проекта.

Обязательный YAML-фронтматтерCopy Anchor Link

---
name: "CLAUDE"
version: "MAJOR.MINOR.PATCH"
updated: "YYYY-MM-DD"
description: "Project-scoped Claude Code instructions for the Apothem source repository"
scope: "project"
portability: "project-local"
---

РазделыCopy Anchor Link

CLAUDE.md пишется прозой по разделам; описание приведено в CLAUDE.md. Ни один валидатор не требует фиксированного списка разделов: scripts/dev/validate_ecosystem.py проверяет приведённые выше ключи фронтматтера.

Чек-лист валидацииCopy Anchor Link

Каждый артефакт должен проходить следующие проверки:

Валидация фронтматтераCopy Anchor Link

• YAML синтаксически корректен (нет ошибок разбора)
• Присутствуют все обязательные поля для типа артефакта
• name следует соглашению kebab-case
• version — семантическая версия (MAJOR.MINOR.PATCH)
• updated — в формате даты ISO 8601 (YYYY-MM-DD)
• description — непустая строка в одну строку
• Необязательные поля соответствуют ожидаемым значениям enum (если применимо)
• В именах полей нет опечаток (используйте канонические имена из схемы)
• Нет лишних пробелов и проблем с форматированием

Валидация содержимогоCopy Anchor Link

• Содержимое начинается с новой строки после закрывающего ---; в файлах семейства Markdown первым содержимым после него идёт каноническая строка заголовка SPDX
• Нет ссылок на внутренние материалы планов (соответствие CM-7)
• Перекрёстные ссылки разрешаются (если перечислены другие артефакты)
• Ссылки используют относительные пути с прямыми слешами

Валидация переносимостиCopy Anchor Link

• Нет жёстко заданных абсолютных путей (используйте относительные)
• Нет специфичного для Windows синтаксиса в артефактах с универсальной областью действия
• В качестве разделителей путей используются прямые слеши
• Переменные окружения используют платформенно-независимый формат (${VAR} или нативный для инструмента)

ПримечанияCopy Anchor Link

• Согласованность как безопасность: канонический фронтматтер позволяет автоматически проверять артефакты, использовать инструментарий и сверять артефакты между собой. Отклонения быстро накапливаются.
• Декларация переносимости: не все артефакты могут быть универсальными. Объявляйте ограничения явно: лучше задокументировать оговорку, чем поставить незаметную ошибку.
• Kebab-case для имён: удобен в URL, скриптах и контекстах командной строки. Избегайте пробелов, подчёркиваний и camelCase в именах.
• Гигиена повышения версии: каждая правка, меняющая поведение, должна повышать version и updated одновременно. Исправления опечаток, ссылок и форматирование не меняют версию; новые необязательные разделы или антипаттерны повышают MINOR; структурная реорганизация или изменения контракта повышают MAJOR.