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 とアーカイブ 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 の使い方。