Контракт упаковки когорт

Этот документ задаёт стабильный, потребляемый ниже по потоку контракт для упаковки когорт и манифестов плагинов. Потребитель читает этот контракт, чтобы перечислить когорты и разрешить их нативные цели по окружениям без повторного выведения сопоставления.

Артефакты

Форма манифеста когорт

Манифест когорт — это объект верхнего уровня с тремя ключами:

• version — строка SemVer манифеста.
• cohorts[] — одна запись на когорту. Каждая запись имеет id (из закрытого набора core | developer | security | research | ai-engineering | full), name, description и members (объект, группирующий идентификаторы участников по типу каталога: skills / agents / commands / rules / hooks).
• per_harness_targets — контракт разрешения (ниже).

Каждый идентификатор участника — это стабильное имя в kebab-case, которое соответствует реальному артефакту под src/apothem/ (skills/<name>/, agents/<name>.md, commands/<name>.md, rules/<name>.md или записи hooks/).

Перечисление когорт

Потребитель загружает cohort-manifest.yaml, проверяет его относительно cohort.schema.json, затем перебирает cohorts[]. Для каждой когорты он читает members.<type>, чтобы получить идентификаторы участников каждого типа каталога.

Разрешение нативных целей по окружениям (без повторного выведения)

Манифест когорт не повторяет сопоставление окружений. Вместо этого per_harness_targets.source указывает на lib/propagation-manifest.yaml — единственный источник истины. Правило разрешения:

Для участника когорты типа каталога T (один из skills, agents, commands, rules, hooks) и целевого окружения H (одного из перечисленных в per_harness_targets.harnesses) нативная цель плагина — это поле target записи в lib/propagation-manifest.yaml под harnesses.H.install, чей source совпадает с T/.

Например, skill когорты core, установленный для claude_code, разрешается через запись harnesses.claude_code.install с source: "skills/" в target: "${HARNESS_ROOT}/skills/". Тот же skill для opencode разрешается в ${HARNESS_ROOT}/skills/; для gemini_cli — в ${PROJECT_ROOT}/.gemini/skills/. Потребители никогда не выдумывают цели окружений — они их ищут.

Плейсхолдеры ${HARNESS_ROOT} / ${PROJECT_ROOT} разрешаются во время установки каждым адаптером окружения; потребители когорт трактуют разрешённую target буквально.

Роль манифеста плагина

plugin.schema.json описывает plugin.json — самоописывающий пакет участников каталога (skills / commands / agents / hooks / rules) с обязательным name, SemVer version и description. Манифест плагина — это единица, которую адаптер окружения материализует в свою нативную поверхность плагина; когорты выбирают, каких участников несёт плагин, а манифест распространения разрешает, где эти участники приземляются по окружениям.

Решение об упаковке — один зонтичный пакет, логические когорты

Когорты — это логический слой выбора (этот манифест), а не набор отдельных, независимо устанавливаемых пакетов. Apothem поставляет один зонтичный пакет, несущий полный каталог; манифест когорт позволяет потребителю выбрать согласованное подмножество, а манифест распространения разрешает, где приземляется каждый выбранный участник по окружениям.

Разбиение каталога на отдельные пакеты по когортам (например, один пакет на семейство developer / security / research) достижимо без дублирования на уровне репозитория через паттерн символических ссылок мета-плагина, задокументированный основной поверхностью распространения: один каталог маркетплейса перечисляет несколько плагинов когорт, и каждый каталог плагина когорты содержит символические ссылки на общий каталог с единым источником вместо копий. Когда когорта устанавливается, окружение разыменовывает каждую символическую ссылку внутри маркетплейса — копируя содержимое цели в кэш этой когорты — так что установленная когорта самодостаточна, тогда как репозиторий сохраняет единый источник истины, связанный символическими ссылками (связывание вместо избыточности, ровно так, как предпочитает дисциплина дедупликации). Раннее прочтение о том, что пакеты когорт «механически дублируют» каталог, смешивало дублирование кэша во время установки (обычное копирование на плагин, выполняемое окружением) с дублированием репозитория; паттерн символических ссылок избегает последнего.

Apothem в настоящее время поставляет один зонтичный пакет, потому что это самая простая поверхность распространения, а не потому, что когорты механически невозможны. Принятие формы по когортам — это подлинный компромисс между UX и сопровождением, а не нарушение дедупликации: преимущество — более тонкий опыт «установить только это семейство»; затраты — сопровождение N каталогов символических ссылок когорт плюс их записей в маркетплейсе, более крупная поверхность соответствия / тестов / golden и копии кэша во время установки по когортам. Логический слой когорт выше уже обеспечивает результат выбора «установить только то, что нужно» из единого пакета; упаковка по когортам — это следующий шаг, когда требуется более тонкий UX установки.