release-bumper

リリースバンパー

スラッシュまたはドル記号による呼び出しで、これらの指示がすでに会話に追加されている場合は、そのまま従ってください。その 場合、このスキルをスキルツールから再度呼び出さないでください。

1 つまたは複数のパッケージをリリースします。バージョン更新、変更履歴の記載、コミット、タグ付けを行います。

ドライランではない呼び出しは、このワークフローで定義されたリポジトリ内のバージョン編集、変更履歴、コミット、注釈付きタグの作成を許可します。エージェントがリリース計画を導き出した後に、一般的な確認手順を追加しないでください。未解決のパッケージ選択または依存関係のバージョン範囲ポリシーによって、リリース対象や手順が変わる場合に限り、質問してください。GitHub リリースの作成は別個の外部書き込みであり、以下の規定に従います。

引数

• packages：任意のパッケージ名またはディレクトリです。単一パッケージのリポジトリでは省略してください。
• version：任意の明示的な SemVer です。ユーザーが選択したパッケージが 1 つの場合に限り有効です。
• --beta：-beta.X のプレリリースを作成または更新します。
• --dry-run：ファイルの変更、コミット、タグ付けを行わずにプレビューします。

ヘルパーインターフェース

この SKILL.md から <skill-dir> を解決します。ヘルパーの標準出力は JSON、診断メッセージは標準エラー出力に保持してください。

bun run "<skill-dir>/scripts/plan-release.ts" \
  [--cwd <repo>] [--beta] [--dry-run] [--version <semver>] \
  [--package <name-or-dir>]...

読み取り専用の検出結果の schemaVersion は 2 です。パッケージの識別情報、パッケージごとの変更ファイルの全件、ワークスペースの依存関係と宣言されたバージョン範囲、以前のタグに関する情報、選択された対象、ワークツリーの状態が報告されます。changeHints はファイル名に基づく、明示的に非確定的なナビゲーション用ヒントです。リリースとの関連性や変更履歴への掲載を判断するために、これらを使用しないでください。

エージェントが安定版のパッチ／マイナー／メジャーバージョンをすべて決定した後、検出結果の JSON を一時ファイルに書き込み、次を実行します。

uv run "<skill-dir>/scripts/finalize-release-plan.py" \
  --discovery <discovery.json> \
  [--version <package>=<semver>]...

ファイナライザーは、ベータ版および明示的なバージョンへの移行、安定版へのプレリリース昇格、npm のバージョン範囲への適合性、単純な依存関係バージョン範囲の提案、依存関係の順序付けを行います。複雑なバージョン範囲、ピア依存関係のバージョン範囲、依存関係の循環、およびエージェントから安定版バージョンが提示されていない項目は、未解決の判断事項として報告されます。満たされていない依存関係によって依存元パッケージがリリース対象に追加された場合、そのパッケージのリリースバージョンを選択し、別の --version 割り当てを指定して再実行してください。ファイナライザーは通常リリースのバージョン区分や依存関係ポリシーを決定しません。

作成した安定版の変更履歴はすべて、次の方法で決定的な構造を検証してください。

uv run "<skill-dir>/scripts/validate-changelog.py" \
  --file <CHANGELOG.md> --version <semver> --date <YYYY-MM-DD> [--tag <tag>]

リリースと日付、見出しとカテゴリの順序、使用可能なカテゴリ、リスト構造、リリースリンクのタグが期待どおりかを確認します。重要性、表現、意味上のカテゴリは評価しません。

ワークフロー

1. ユーザー引数をそのままマッピングしてディスカバリーを実行します。終了コード 2 は、対象がリリース可能な Git／パッケージリポジトリではないことを意味します。終了コード 64 は、入力が無効であることを意味します。どちらの場合も停止します。

2. workingTree.clean を必須とします。無関係な作業を取り込みません。

3. 不明または曖昧なパッケージ選択を解決します。ユーザーがバージョンを明示した場合は、単一パッケージのみを対象とします。対象の previousTags バージョンがマニフェストのバージョンより古い場合、そのバージョンはタグなしでリリースされており、報告されたベースは古い状態です。リリースコミットに、不足している注釈付きタグを作成し（例：docs: release <version>）、確認できたタグの規則に従ってプッシュコマンドに含め、ディスカバリーを再実行します。リリースコミットを特定できない場合に限り、確認を求めます。

4. 各対象の changedFiles 全体と、前回のタグからの正味の差分を確認します。残った変更にリリースの価値があるか判断します。実行環境、リファクタリング、ドキュメント、テスト、ツール類も、状況によっては関連性があります。ファイル名だけで判断してはいけません。

5. 関連性のある安定版の対象ごとに、バージョンが明示されていない場合は、利用者向けの変更内容に基づいてパッチ、マイナー、メジャーのいずれかを選びます。ベータ版では、機械的なバージョン遷移をファイナライザーに任せます。

6. ファイナライザーを実行します。解決されていないワークスペースの依存関係を確認します。単純な依存範囲については、そのポリシーが適切な場合に限り、提示された案を採用します。ピア依存関係と複雑な範囲のポリシーは明示的に選択します。依存パッケージと、エージェントが選んだそれらのリリースバージョンを追加し、パッケージ構成と依存順序が確定するまで再実行します。

7. ドライランでは、パッケージとバージョンの順序付きプラン、範囲の編集、変更履歴／タグ／コミットの処理、エージェントが判断したスキップを報告します。書き込みを行う前に停止します。

8. 安定版リリースでは、references/common-changelog.md を読み、範囲を限定した正味の差分に基づいて利用者向けの項目を記述します。項目の選定、表現、重要度、カテゴリはエージェントが決定します。ベータ版リリースでは変更履歴を更新しません。

9. マニフェストと、採用した依存範囲を更新します。すべての安定版変更履歴を、変更履歴をループ処理して各結果を報告する単一のシェル呼び出しでヘルパーを使って検証します。

10. リポジトリで定められた、最も対象範囲の狭いコマンドを一度だけ使ってフォーマットします。

11. 依存パッケージから依存先パッケージの順にコミットとタグを作成します。パッケージごとにコミットを1つ、注釈付きタグを1つ作成します。

    • 単一パッケージのコミット：docs: release <version>。
    • モノレポのコミット：docs: release <package> <version>。
    • 単一パッケージのタグ：確認できた v<version> またはバージョン番号のみの形式に従います。
    • モノレポのタグ：確認できたパッケージタグの形式に従い、特に確認できない場合は <package-dir>@<version> とします。

12. プッシュしません。成功後、この実行で作成したタグのみを含む、正確な git push origin <tag>... コマンドを提示します。--tags は使用しません。

13. 最終報告の前に、ステップ内の基準とステップ14の基準の両方について、.github/workflows/ を一度確認します。このステップでは、プッシュされたタグから GitHub リリースを作成または公開する、有効なワークフローを探します。release.yml のようなファイル名は手掛かりにすぎず、証拠にはなりません。同じターン内で $cli-gh を使って読み取り専用の gh release list を実行し、リポジトリに継続的な GitHub リリースの実績があるか確認します。実績がある場合は、次の規則に従い、承認を得たうえで新しい各タグの GitHub リリースを作成することを提案します。

    • タグが1～3個で、該当するリリース CI がある場合：手動でのリリース作成を提案しません。この場合、タグのプッシュによって CI が起動します。
    • 該当するリリース CI がない場合：$cli-gh 経由で gh release create を使用し、新しいタグごとに1つのリリースを作成することを提案します。
    • 4個以上のタグをまとめてプッシュする場合：リリース CI がある場合でも、$cli-gh 経由で gh release create を使用し、タグごとに1つのリリースを作成することを提案します。この数を超えると、GitHub はタグのプッシュイベントを作成しないためです。詳細はGitHub のプッシュイベントの上限を参照してください。 ユーザーの承認なしに GitHub リリースを作成しないでください。リリース履歴を確認できない場合は、 不明と報告し、書き込みを提案しないでください。

14. 最終報告の前に、手順 13 の .github/workflows/ の調査結果だけを使って、タグのプッシュ時に実行され、 id-token: write を設定し、npm stage publish（ステージング）または npm publish （直接公開）を実行する有効なワークフローがあるかどうかも確認してください。そのようなワークフローがある場合：

    • 推奨タグをプッシュすると npm 公開が開始されることを報告してください。
    • ステージング公開の場合は、メンテナーが 2FA で承認するまで各バージョンは未公開のままであることを報告してください。 メンテナーは npm stage approve <stage-id> を実行するか、npmjs.com の Staged Packages タブを使用できます。
    • GitHub はタグのプッシュ数がその上限を超えるとタグのプッシュイベントを作成しないため、プッシュコマンドに含めるタグは最大 3 個にするよう推奨してください。手順 13 のプッシュイベント上限のリンクを参照してください。
    • npm publish、npm stage approve、npm stage reject は決して実行しないでください。

安全性と完了条件

ヘルパーの失敗は、不正な入力、不変条件違反、または検証失敗を意味します。未解決のエージェント判断は JSON 内のデータであり、ヘルパーの失敗ではありません。検出とドライランは読み取り専用です。最終的な安定版パッケージのセットが確定する前に変更履歴を書き込まないでください。また、検出で報告された観測事実からタグの規則を推測しないでください。

ドライランの完了には、検出結果に基づきエージェントがレビューしたアクションプレビューが必要で、書き込みはゼロでなければなりません。リリースの完了には、検証済みのマニフェストと安定した変更履歴、フォーマット、依存関係順でのパッケージごとのコミットと注釈付きタグが必要です。また、作成したコミット／タグ、エージェントが判断したスキップ、正確なタグプッシュコマンド（1 つまたは複数）、該当する場合は GitHub リリースの提案、および CI による npm 公開の通知を報告してください。

該当する場合は、### ⛔ Release stopped — working tree is not clean、### ⚠️ Release decision required、 ### 🔎 Release preview — no files, commits, or tags written、または ### 🏁 Release complete を使用してください。ヘルパーの JSON、バージョン、ハッシュ、タグ、コマンド、変更履歴のテキストは、正確なまま装飾を加えないでください。