add-community-extension

コミュニティ拡張機能の追加

拡張機能の提出に関する Issue を処理し、コミュニティカタログに追加または更新します。

使用するタイミング

• 新しい [Extension] 提出 Issue が作成されたとき
• 既存の拡張機能が更新 Issue（新バージョン、メタデータの変更）を提出したとき
• extensions/catalog.community.json と docs/community/extensions.md のコミュニティ拡張機能を追加または更新する必要があるとき

手順

1. 提出 Issue を取得する

GitHub Issue を読み、すべてのメタデータを抽出します。

• 拡張機能 ID、名前、バージョン、説明、作成者
• リポジトリ URL、ダウンロード URL、ホームページ、ドキュメント、変更履歴
• ライセンス、必須の spec-kit バージョン、任意のツール依存関係
• コマンドとフックの数
• タグ

2. 公開ルールに照らして検証する

以下の項目をすべて確認します（extensions/EXTENSION-PUBLISHING-GUIDE.md に従ってください）。

確認項目	方法
リポジトリが存在し、公開されている	リポジトリ URL を取得する
extension.yml マニフェストが存在する	リポジトリのファイル一覧で確認する
README.md が存在する	リポジトリのファイル一覧で確認する
LICENSE ファイルが存在する	リポジトリのファイル一覧で確認する
バージョンに一致する GitHub リリースが存在する	リポジトリページのリリースを確認する
ダウンロード URL にアクセスできる	archive/refs/tags/vX.Y.Z.zip の形式に従っており、リリースが存在することを確認する
拡張機能 ID が小文字とハイフンのみで構成されている	正規表現：^[a-z][a-z0-9-]*$
バージョンがセマンティックバージョニングに従っている	形式：X.Y.Z
提出チェックリストの項目がすべてチェックされている	Issue の本文で確認する

3. 追加か更新かを判断する

extensions/catalog.community.json で拡張機能 ID を検索します。

• 見つからない → 新規追加です。手順 4 に進みます。
• 見つかった → 更新です。手順 4 に進みますが、挿入ではなく既存のエントリをその場で置き換えます。

4. extensions/catalog.community.json を追加または更新する

新しい拡張機能： 拡張機能 ID のアルファベット順にエントリを挿入します。

更新： 既存のエントリをその場で置き換えます。変更があったフィールドのみを更新します（通常は version、download_url、description、provides、requires、tags、updated_at）。既存のエントリにある created_at と downloads／stars は保持します。

既存のエントリを形式のテンプレートとして使用します。必須フィールド：

{
  "<id>": {
    "name": "<name>",
    "id": "<id>",
    "description": "<description>",
    "author": "<author>",
    "version": "<version>",
    "download_url": "<download_url>",
    "repository": "<repository>",
    "homepage": "<homepage>",
    "documentation": "<documentation>",
    "changelog": "<changelog>",
    "license": "<license>",
    "category": "<category>",
    "effect": "<effect>",
    "requires": {
      "speckit_version": "<speckit_version>"
    },
    "provides": {
      "commands": <N>,
      "hooks": <N>
    },
    "tags": ["<tag1>", "<tag2>"],
    "verified": false,
    "downloads": 0,
    "stars": 0,
    "created_at": "<today>T00:00:00Z",
    "updated_at": "<today>T00:00:00Z"
  }
}

カテゴリ — 任意の文字列。一般的な値：docs、code、process、integration、visibility 効果 — 次のいずれか：read-only、read-write

拡張機能に任意のツール依存関係がある場合は、"requires" 内に "tools" 配列を追加します。

"tools": [{ "name": "<tool>", "required": false }]

カタログのトップレベルにある "updated_at" のタイムスタンプも更新します。

編集後、次を実行して JSON を検証します。

python3 -c "import json; json.load(open('extensions/catalog.community.json')); print('Valid JSON')"

5. docs/community/extensions.md のコミュニティ拡張機能テーブルを追加または更新する

新しい拡張機能： # Community Extensions テーブルに、拡張機能名のアルファベット順で新しい行を挿入します。

更新： 既存の行を見つけ、説明やその他の変更されたフィールドをその場で更新します。

拡張機能の動作に基づいて、カテゴリと効果を判断します。

| <Name> | <Description> | `<category>` | <Effect> | [<repo-name>](<repository-url>) |

カテゴリ — 任意の値。一般的な値：docs、code、process、integration、visibility 効果 — extension.yml と catalog.community.json には正規の値 read-only または read-write を記載します。ドキュメントのテーブル表示には Read-only／Read+Write のみを使用します。

6. コミット、プッシュして PR を作成する

新しい拡張機能には add-、更新には update- を使用します。

# New extension
git checkout -b add-<extension-id>-extension

# Update
git checkout -b update-<extension-id>-extension

git add extensions/catalog.community.json docs/community/extensions.md

# New extension
git commit -m "Add <Name> extension to community catalog

Add <id> extension submitted by @<issue-author> to:
- extensions/catalog.community.json (alphabetical order)
- docs/community/extensions.md community extensions table

Closes #<issue-number>"

# Update
git commit -m "Update <Name> extension to v<version>

Update <id> extension submitted by @<issue-author>:
- extensions/catalog.community.json (version, download_url, etc.)
- docs/community/extensions.md community extensions table

Closes #<issue-number>"

git push origin <branch-name>

次の内容で upstream（github/spec-kit）に PR を作成します。

• タイトル： Add <Name> extension to community catalog（または Update <Name> extension to v<version>）
• 本文： 検証の概要、Closes #<issue-number>、cc @<issue-author> を含めます
• Head： <fork-owner>:<branch-name>
• Base： main

よくある落とし穴

• アルファベット順が重要です — JSON では ID 順、ドキュメントの表では名前順にエントリーを並べる必要があります。
• カタログの updated_at を忘れないでください — catalog.community.json の最上位にあるタイムスタンプを更新する必要があります。
• 編集後に JSON を検証してください — 末尾のカンマや閉じ括弧の不足があると、カタログが正しく動作しません。
• Fixes ではなく Closes を使ってください — 投稿に関するイシューには Closes #N が正しいキーワードです。
• 提案されたエントリーに合わせつつ、検証してください — イシューに JSON ブロックの提案が含まれている場合がありますが、フィールドの値は必ず実際のリポジトリの状態と照合してください。
• 更新時は created_at を保持してください — 元の created_at の値を維持し、変更するのは updated_at のみです。
• 更新時は downloads と stars を保持してください — これらは利用状況の指標を表すため、リセットしてはいけません。