Cohort 패키징 계약

이 문서는 cohort 패키징과 플러그인 매니페스트를 위한 안정적이고 다운스트림에서 소비 가능한 계약을 규정합니다. 소비자는 이 계약을 읽어 cohort를 열거하고 하니스별 네이티브 타깃을 매핑을 다시 도출하지 않고 해석합니다.

아티팩트

cohort 매니페스트의 형태

cohort 매니페스트는 세 개의 키를 가진 최상위 객체입니다.

• version — 매니페스트의 SemVer 문자열.
• cohorts[] — cohort당 하나의 항목. 각 항목은 id(닫힌 집합 core | developer | security | research | ai-engineering | full에서), name, description, 그리고 members(멤버 식별자를 카탈로그 타입별로 그룹화하는 객체: skills / agents / commands / rules / hooks)를 가집니다.
• per_harness_targets — 해석 계약(아래).

각 멤버 식별자는 src/apothem/ 아래의 실제 아티팩트(skills/<name>/, agents/<name>.md, commands/<name>.md, rules/<name>.md, 또는 hooks/ 항목)에 대응하는 안정적인 kebab-case 이름입니다.

cohort 열거

소비자는 cohort-manifest.yaml을 로드하고 cohort.schema.json에 대해 검증한 다음 cohorts[]를 반복합니다. 각 cohort에 대해 members.<type>를 읽어 각 카탈로그 타입의 멤버 식별자를 얻습니다.

하니스별 네이티브 타깃 해석(재도출 없음)

cohort 매니페스트는 하니스 매핑을 다시 진술하지 않습니다. 대신 per_harness_targets.source가 유일한 정보원인 lib/propagation-manifest.yaml을 가리킵니다. 해석 규칙:

카탈로그 타입 T(skills, agents, commands, rules, hooks 중 하나)의 cohort 멤버와 대상 하니스 H(per_harness_targets.harnesses에 나열된 것 중 하나)에 대해, 네이티브 플러그인 타깃은 lib/propagation-manifest.yaml의 harnesses.H.install 아래에서 source가 T/와 일치하는 항목의 target 필드입니다.

예를 들어, claude_code용으로 설치된 core cohort skill은 source: "skills/"를 가진 harnesses.claude_code.install 항목을 통해 target: "${HARNESS_ROOT}/skills/"로 해석됩니다. 동일한 skill은 opencode의 경우 ${HARNESS_ROOT}/skills/로, gemini_cli의 경우 ${PROJECT_ROOT}/.gemini/skills/로 해석됩니다. 소비자는 하니스 타깃을 결코 지어내지 않으며 — 그것을 조회합니다.

${HARNESS_ROOT} / ${PROJECT_ROOT} 자리표시자는 각 하니스 어댑터가 설치 시점에 해석합니다. cohort 소비자는 해석된 target을 그대로 다룹니다.

플러그인 매니페스트의 역할

plugin.schema.json은 plugin.json을 기술합니다 — 이는 필수 name, SemVer version, description을 가진, 카탈로그 멤버(skills / commands / agents / hooks / rules)의 자기 기술적 번들입니다. 플러그인 매니페스트는 하니스 어댑터가 자신의 네이티브 플러그인 표면으로 물질화하는 단위입니다. cohort는 플러그인이 어떤 멤버를 운반하는지 선택하고, 전파 매니페스트는 그 멤버들이 하니스별로 어디에 안착하는지 해석합니다.

패키징 결정 — 하나의 우산 번들, 논리적 cohort

cohort는 논리적 선택 계층(이 매니페스트)이지, 개별적으로 설치 가능한 분리된 번들 집합이 아닙니다. Apothem은 전체 카탈로그를 운반하는 하나의 우산 번들을 배포합니다. cohort 매니페스트는 소비자가 일관된 서브셋을 고를 수 있게 하고, 전파 매니페스트는 선택된 각 멤버가 하니스별로 어디에 안착하는지 해석합니다.

카탈로그를 cohort별 분리 번들(예: developer / security / research 계열별로 하나의 번들)로 나누는 것은, 주요 배포 표면이 문서화한 메타 플러그인 심볼릭 링크 패턴을 통해 리포지토리 수준의 중복 없이 달성 가능합니다. 하나의 마켓플레이스 카탈로그가 여러 cohort 플러그인을 나열하고, 각 cohort 플러그인 디렉터리는 복사본이 아니라 단일 소스의 공유 카탈로그로의 심볼릭 링크를 보유합니다. cohort가 설치되면 하니스는 마켓플레이스 내의 각 심볼릭 링크를 역참조하여 — 타깃의 콘텐츠를 해당 cohort의 캐시로 복사하므로 — 설치된 cohort는 자기 완결적인 반면, 리포지토리는 심볼릭 링크로 배선된 단일 정보원을 유지합니다(중복이 아니라 배선, 정확히 중복 제거 규율이 선호하는 대로). cohort 번들이 카탈로그를 "기계적으로 중복시킨다"는 이전의 해석은 설치 시점 캐시 중복(하니스의 정상적인 플러그인별 복사)과 리포지토리 중복을 혼동했습니다. 심볼릭 링크 패턴은 후자를 회피합니다.

Apothem은 현재 하나의 우산 번들을 배포하는데, 이는 cohort가 기계적으로 불가능하기 때문이 아니라 그것이 가장 단순한 배포 표면이기 때문입니다. cohort별 형태를 채택하는 것은 중복 제거 위반이 아니라 진정한 UX 및 유지보수 트레이드오프입니다. 이점은 "이 계열만 설치" 경험이 더 세분화된다는 것이고, 비용은 N개의 cohort 심볼릭 링크 디렉터리와 그 마켓플레이스 항목의 유지, 더 큰 적합성 / 테스트 / golden 표면, 그리고 cohort별 설치 시점 캐시 복사본입니다. 위의 논리적 cohort 계층은 이미 단일 번들에서 "필요한 것만 설치" 선택 결과를 제공합니다. cohort별 패키징은 더 세분화된 설치 UX가 필요할 때의 다음 단계입니다.