HagiTask 커뮤니티 기여하기

대상 독자: HagiTask 커뮤니티 작업의 기여자와 관리자.

사전 준비:

hagitask-community-packages를 클론하고 Node.js/npm을 준비해야 합니다.
저장소 안에 중첩된 hagitask checkout을 초기화할 수 있어야 합니다.
JSON, Markdown, Git Pull Request에 익숙해야 합니다.

이 페이지는 기여자를 위한 전체 작업 절차입니다. Community Packages README에는 저장소의 책임 범위, 디렉터리, 명령어 참조만 담습니다.

저장소의 책임 범위와 게시 흐름

Community Packages는 커뮤니티 작업 정의의 source of truth입니다. 기여자는 data/<taskId>/를 편집하고, HagiTask는 공통 패키지 Schema를 관리합니다. HagiTask Site는 Community Packages의 특정 커밋을 읽어 정규화한 후 다음을 생성합니다.

/index.json: 작업 검색을 위한 간결한 목록.
/tasks/<taskId>.json: 전체 리소스와 호환성 정보를 담은 상세 문서.
/packages/<taskId>.zip: 앱에서 설치할 때 사용하는 아카이브.

이 JSON과 ZIP은 생성 결과물이므로 Community Packages에서 수동으로 만들거나 수정하지 마세요. 아카이브에는 data/<taskId>/ 디렉터리 전체가 포함되므로 디렉터리에 새로 추가한 리소스도 패키지와 함께 게시됩니다.

1. Schema와 저장소 준비하기

Community Packages 저장소에서 실행합니다.

git submodule update --init --recursive
npm install

공통 패키지 Schema의 권위 있는 원본은 repos/hagitask/schemas/task-preset-plugin/에 있으며 Community Packages는 중첩된 checkout을 통해 사용합니다. Community Packages나 HagiTask Site에 Schema를 복사하거나 그곳에서 수정하지 마세요.

2. 작업 패키지 만들기

새 작업은 data/<taskId>/에 둡니다. taskId는 안정적이고 고유한 lowercase kebab-case여야 하며 언제나 manifest.json의 taskPresetId와 정확히 일치해야 합니다. 디렉터리 이름을 바꾸면 게시된 상세 정보와 아카이브의 URL이 바뀝니다.

현재 게시된 정식 ID는 다음과 같습니다.

표시 이름	`taskId`
UI Master	`ui-master`
AgentsMD	`claude-md-update`
Last 30 Days	`last30days`
Ponytail	`ponytail`
Goal	`goal`
OpenSpec Spec Compress	`openspec-spec-compress`

agentsmd와 portytail은 사람이 쓰는 별칭일 뿐 프로토콜의 작업 ID가 아닙니다.

data/<taskId>/
  manifest.json
  frontend/
    panel.json
    commands.json                 # 有命令目录时才需要
  backend/
    task-preset.json
    prompts.json
    templates/<locale>/
      system.md
      user.hbs
  locales/
    en-US.json
    zh-CN.json
  store-page/
    index.en-US.md
    index.zh-CN.md

manifest.json, frontend/panel.json, backend/task-preset.json, backend/prompts.json, 영어와 중국어 locale, 두 개의 store page, 선언한 각 언어의 prompt 템플릿은 필수 리소스입니다. commands.json은 패키지가 실제로 명령 목록을 제공할 때만 추가합니다.

파일이 목록에 미치는 영향

원본 파일	게시 결과
`manifest.json`의 `version`	목록 및 상세 정보의 버전
`manifest.json`의 `owner`	게시자
`manifest.json`의 `localization`	클라이언트가 로드하는 locale bundle
`backend/task-preset.json`의 `requirements`	작업 요구 사항과 여기서 파생된 호환성 정보
store page의 `title` / `summary`	여러 언어의 이름, 요약, 설명
영어 store page의 `catalog` / `tags`	카테고리와 태그

영어 페이지에 catalog가 없다면 카테고리는 첫 번째 tag를 사용하고, 그것도 없으면 General을 사용합니다. 목록의 카테고리 생성에는 영어 페이지의 catalog와 tags만 사용합니다.

3. Schema 참조 및 리소스 작성하기

각 JSON 파일에 해당하는 $schema를 유지하고 공개된 Schema URL을 사용하세요.

https://tasks.hagicode.com/schemas/task-preset-plugin/<schema>.schema.json

각 파일에 대응하는 Schema는 hagitask/schemas/task-preset-plugin/을 기준으로 확인하세요. manifest.json에는 작업 ID, 버전, 게시자, 현지화 bundle, 프런트엔드/백엔드 리소스 경로를 선언해야 합니다. locale 파일 간에는 동일한 키 집합을 유지하세요.

store-page/index.en-US.md와 index.zh-CN.md에는 최소한 locale, slug, title, summary frontmatter가 필요합니다. 게시 사이트는 영어 페이지에서 카테고리와 태그를 생성하므로 catalog와 tags는 영어 페이지에 넣으세요.

4. 버전 관리와 검증

게시된 콘텐츠를 변경할 때마다 시맨틱 버저닝에 따라 manifest.json의 version을 변경해야 합니다. 이전 버전 번호를 재사용하면 목록 메타데이터와 패키지 다이제스트가 모호해집니다.

기존 검증 명령을 실행합니다.

npm run validate

검증 도구는 정식 ID, Schema, 리소스 선언, 현지화 범위, prompt 템플릿, store-page frontmatter를 확인합니다. 실패하면 data/<taskId>/의 원본 파일을 고치세요. /index.json, /tasks/<taskId>.json, /packages/<taskId>.zip은 수정하면 안 됩니다. 모두 HagiTask Site가 게시할 때마다 생성하는 결과물입니다.

검증 워크플로는 패키지 내용을 변경하는 Pull Request와 main push에서 실행되며, 검증에 실패하면 패키지를 병합할 수 없습니다.

게시 계약을 추가로 확인해야 한다면 hagitask-site checkout에서 다음을 실행할 수 있습니다.

npm install
npm run typecheck
npm run build
npm run stage:schemas
npm run verify

사이트 빌드 과정에서는 정규화와 게시 Schema 검증을 다시 수행합니다. 빌드에 성공하면 생성된 목록과 상세 정보가 community-index-v1 및 community-task-detail-v1 계약을 충족합니다.

5. Pull Request 제출하기

Pull Request는 hagitask-site나 hagitask가 아닌 hagitask-community-packages에 제출하세요. 병합 후 HagiTask Site가 Community Packages의 특정 커밋을 업데이트하고 인덱스, 상세 정보, ZIP 아카이브를 다시 생성합니다.

hagitask는 공통 Schema와 내장 프리셋을 담당합니다. 패키지 형식의 계약 자체를 변경해야 한다면 HagiTask 저장소에 별도의 Schema 변경을 제안하세요. Community Packages는 data/ 원본 데이터만 관리하고 사이트는 생성 결과물만 게시합니다.

검증에 실패할 때

오류가 가리키는 data/<taskId>/의 원본 파일을 수정하세요.

패키지 Schema 오류: 해당 JSON을 수정하고 $schema를 삭제하거나 검증 기준을 완화하지 마세요.
리소스 또는 locale 누락: 선언과 실제 파일이 일치하도록 manifest, locale, prompt template 또는 store page를 업데이트하세요.
목록 상세 정보나 아카이브 Schema 오류: 원본 패키지와 사이트 정규화 입력을 확인하고 생성된 JSON을 수정하지 마세요.

Schema 계약 자체에 문제가 있다면 이 저장소에 Schema를 복사하지 말고 HagiTask 저장소에서 계약 변경을 제안하세요.

다음 단계: HagiTask 설치 또는 HagiTask 사용법.