release

リリーススキル

目的： プロジェクトを「コードの準備完了」から「タグ付けされ、オペレーターによってプッシュされ、正確なタグ付き SHA で CI が成功したことを確認済み」の状態にします。

事前検証、Git 履歴からの変更履歴作成、パッケージファイル全体のバージョン更新、リリースコミット、注釈付きタグ、厳選したリリースノート、プッシュ後の正確な SHA に対する CI 検証を行います。ローカルでの準備は取り消し可能です。公開（GitHub のリリースページを含む）は CI の役割です。

制約

• 準備は取り消し可能にし、公開の判断はオペレーターに委ねます。 このスキルではローカルのリリース成果物、コミット、注釈付きタグを作成できますが、プッシュ、公開、CI のトリガーは行いません。これらの操作は取り消し可能なローカルの境界を越えるためです。
• 決定論的な事前検証を必須にします。 確認済みバージョンに対するリリースゲートをすべて実行し、--skip-checks は明示的に選択された検証品質の低下として扱います。テストされていないタグは、信頼できるリリースの境界にはなり得ないためです。
• 完了の判定をタグ付きコミットに結び付けます。 タグの SHA、正確な SHA に対する CI の実行結果、照合結果を記録します。ブランチでの CI 成功や未検証のタグでは、リリースされた成果物の正しさを証明できないためです。
• リリースに関する主張は証拠に基づくものにします。 変更履歴、リリースノート、バージョンの選定、監査には、選択した Git 範囲と生成済み成果物のみを使用します。事実を捏造したり、以前の主張をそのまま引き継いだりすると、どちらの読者にとっても信頼性が損なわれるためです。
• アンドンを上げる前に pawl に相談します。 WARN、FAIL、REFUTED のリリース証拠については、自動的に修正して再実行します。通常の却下は準備の不備を示すものであり、HOLD に入ったり、ヘルパーレーンを消費したりする理由にはなりません。HOLD に入れる、またはヘルパーレーンを利用できるのは、実際に公開を妨げる要因がある場合のみです。

ブレーカーの状態遷移

• 通常の却下 — WARN|FAIL|REFUTED -> AUTO-REDO： 担当するリリース成果物を修正するか、不具合を生成元のビードに差し戻してから、事前検証と pawl を再実行します。通常の却下で HOLD に入ることも、ヘルパーレーンを消費することもありません。
• ブレーカー — BREAKER -> HOLD -> ONE-HELPER： 取り消し不能なリモート操作、成果物の識別の曖昧さ、または利用できないリリース権限によって安全に進められない場合、タグ付けまたは公開に関する案内を凍結します。その後、監査パケットとともに、範囲を限定したヘルパーへの相談を一度だけ行います。
• 復旧 — HELPER-UNSTUCK -> AUTO-REDO： HOLD を解除して範囲を限定した復旧を適用し、ローカル検証、正確な SHA の証拠、照合、pawl の判定を改めて取得します。
• ヘルパーからのエスカレーション — HELPER-ESCALATE -> HUMAN： 自動化を停止し、ヘルパーが提示したリリースの証拠をオペレーターに送ります。
• 人間への直接経路 — REFUSAL-LANE|EXPLICIT-JUDGMENT|EXHAUSTED-BUDGET -> HUMAN： ヘルパーを介さず、オペレーターに直接引き継ぎます。人間への直接経路となるのはこれらの状態のみです。

---

クイックスタート

/release 1.7.0                # full release: changelog + bump + commit + tag
/release 1.7.0 --dry-run      # show what would happen, change nothing
/release --check               # readiness validation only (GO/NO-GO)
/release                       # suggest version from commit analysis

---

引数

引数	必須	説明
version	いいえ	Semver 形式の文字列（例：1.7.0）。省略した場合は、コミットの分析に基づいて候補を提案します
--check	いいえ	準備状況の検証のみを行います。生成も書き込みもしません
--dry-run	いいえ	書き込みを行わず、生成される変更履歴とバージョン更新を表示します
--skip-checks	いいえ	事前検証（テスト、リンター）を省略します
--changelog-only	いいえ	CHANGELOG.md のみを更新します。バージョン更新、コミット、タグ付けは行いません

---

モード

モード	実行方法	動作
フルリリース	/release [version]	事前検証 → 変更履歴 → リリースノート → バージョン更新 → ユーザーレビュー → 書き込み → リリースコミット → タグ付け → プッシュの案内 → 正確な SHA に対する CI 検証。
チェック	/release --check	事前検証のみを実行し、GO/NO-GO を報告します。/validate と組み合わせて使用できます。書き込みは行いません。
変更履歴のみ	/release X.Y.Z --changelog-only	CHANGELOG.md のみを更新します。バージョン更新、コミット、タグ付けは行いません。

---

ワークフロー

各ステップの詳しい手順については、references/release-workflow-detail.md をお読みください — bash コマンド、チェック表、想定される出力、監査記録のテンプレート、実例が記載されています。以下の一覧は概要を示すものです。正しく実行するには、エージェントは release-workflow-detail.md に従って作業する必要があります。

1. 事前チェック — scripts/ci-local-release.sh（必須）と、バージョン／lint／テスト／ブランチ／変更履歴／SBOM／セキュリティの各チェックを実行します。--check モードでは、このステップの後に停止します。
2. 範囲を決定 — <last-tag>..HEAD。HEAD 以外を対象にする場合は、references/release-cut-and-bump.md を参照してください。
3. Git の履歴を確認 — git log --oneline --no-merges <range> と統計情報を使って、曖昧さを解消します。
4. 分類してグループ化 — CHANGELOG.md 用に Added / Changed / Fixed / Removed に分類します。変更履歴の本文では、references/release-notes.md に記載されている、より詳細な 8 種類のラベルを使用します。
5. バージョンを提案 — 破壊的変更がある場合は major、機能追加がある場合は minor、修正のみの場合は patch を提案します。AskUserQuestion で確認します。
6. 変更履歴のエントリーを生成 — Keep-a-Changelog 形式で今日の日付を使い、既存の最新エントリーに合わせたスタイルにします。
7. バージョン更新を検出して提案 — 一般的なパターン（package.json、pyproject.toml など）と、references/release-cut-and-bump.md に記載されている AgentOps 固有のマニフェストを対象にします。
8. ユーザーによるレビュー — 生成した変更履歴とバージョン差分を表示し、続行するか AskUserQuestion で確認します。--dry-run はここで停止します。
9. 変更を書き込む — CHANGELOG.md の更新とバージョンファイルの編集を行います。
10. リリースノートを生成 — references/release-notes.md に従って、編集済みの docs/releases/YYYY-MM-DD-v<version>-notes.md を作成します。リリースコミットの前に、必ずステージングしてください。
11. 監査証跡を書き込む — scripts/resolve-release-artifacts.sh で解決した docs/releases/YYYY-MM-DD-v<version>-audit.md を作成します。形式は workflow-detail のステップ 16 を参照してください。
12. リリースコミット — すべてのリリース関連ファイルをステージングして、git commit -m "Release v<version>" を実行します。
13. タグ付け — 注釈付きタグ git tag -a v<version> -m "Release v<version>" を作成します。
14. GitHub Release（CI が処理） — ローカルで gh release create を実行しないでください。作成するのは GoReleaser のみです。
15. push 後の正確な SHA に対する CI と照合の検証 — オペレーターによる push 後、scripts/verify-release-ci.sh v<version> が GO release-ci を出力することと、ao reconcile --json | bash skills/release/scripts/validate-reconcile.sh "v<version>" がその正確な想定タグに対して合格することの両方を必須とします。正確な SHA に対する CI だけでは、完了扱いにできません。
16. リリース後の案内 — push コマンドと検証コマンドを提示します。push は実行しないでください。
17. 監査証跡の形式 — Markdown テンプレートについては workflow-detail を参照してください。

チェックポイント： 書き込み前に、表示した変更履歴とバージョン差分についてオペレーターの承認を確認します。引き継ぎ前に、リリースコミット、注釈付きタグ、監査記録、リリースノートのバージョンが一致することを確認します。push 後は、完了を宣言する前に、正確な SHA に対する CI と照合の両方を必須とします。

---

対象範囲

このスキルで行うこと

• 事前チェック（テスト、lint、作業ツリーのクリーン状態、バージョン、ブランチ）
• Git の履歴に基づく変更履歴の生成
• コミットの分類に基づく Semver の提案
• パッケージファイル内のバージョン文字列の更新
• リリースコミットと注釈付きタグ
• GitHub Release ページ用のリリースノート（ハイライトと変更履歴）
• CI が GitHub Release ページに公開するための編集済みリリースノート
• リリース後の案内と、正確な SHA に対する CI 検証手順
• 監査証跡

このスキルで行わないこと

• 公開しません — npm publish、cargo publish、twine upload は実行しません。CI が処理します。
• ビルドしません — go build、npm pack、docker build は実行しません。CI が処理します。
• プッシュしません — git push と git push --tags は実行しません。プッシュするタイミングはユーザーが決定します。
• CI をトリガーしません — タグのプッシュ（ユーザーが実行）が CI をトリガーします。
• モノレポの複数バージョンには対応しません — バージョンは 1 つ、変更履歴は 1 つ、タグは 1 つです。v2 で対応する範囲です。

このスキルで行う操作はすべてローカルで、元に戻せます。

• 変更履歴に問題がある → ファイルを編集します
• バージョンの更新に誤りがある → git reset HEAD~1
• タグに問題がある → git tag -d v<version>
• リリースノートに問題がある → プッシュ前に docs/releases/*-notes.md を編集します

---

共通ルール

• 創作しない — git log に表示される内容だけを記録します
• 最終出力にコミットハッシュを含めない
• 最終出力に作者名を含めない
• 簡潔にする — 箇条書き 1 項目につき 1 文とし、技術的でありながら読みやすくします
• 押し付けず、合わせる — 特定の形式を押し付けず、プロジェクト既存のスタイルに合わせます
• ユーザーの確認を得る — まず下書きを提示し、確認を得てから作成します
• ローカルのみ — プッシュ、公開、リモート操作のトリガーは行いません
• タグ付けで完了ではありません — ユーザーがプッシュした後、正確なタグ SHA に対する validate.yml の成功を確認し、ao reconcile --json を実行して、実行 ID、結論、照合結果の全体ステータス、リリースタグの検出状態を引き継ぎ資料またはリリース監査メモに記録します。
• 対象読者は 2 種類です — CHANGELOG.md はコントリビューター向け（ファイルパス、課題 ID、実装の詳細）です。リリースノートはフィード読者向け（平易な英語、ユーザーから見える影響、内部向けの専門用語なし）です。変更履歴をリリースノートにそのままコピーしないでください。

---

出力仕様

• パス： docs/releases/YYYY-MM-DD-v<version>-audit.md。docs/releases/YYYY-MM-DD-v<version>-notes.md および注釈付き参照 refs/tags/v<version> と組み合わせます。
• ファイル名の規則： YYYY-MM-DD-v<version>-audit.md と YYYY-MM-DD-v<version>-notes.md。ここで <version> は、重複する v 接頭辞を含まない、確認済みの SemVer です。
• シリアライズ／スキーマ形式： リリース見出し、日付、前のタグ、コミット数、ローカル CI 成果物のパス、バージョン更新、事前確認の結果、リモート CI の判定を含む Markdown 形式の監査記録です。注釈付き Git タグはリリースコミットを指し、判定には正確な SHA、実行 ID、ステータス、結論を記録します。
• バリデーターコマンド： VERSION="<version>" を設定してから、bash scripts/validate-release-audit-artifacts.sh --mode target --target-release "$VERSION" && bash scripts/verify-release-ci.sh "v$VERSION" && ao reconcile --json | bash skills/release/scripts/validate-reconcile.sh "v$VERSION" を実行します。コマンドが成功しただけでは不十分です。照合 JSON に期待するタグが正確に記載され、意味的に問題がなく、中程度または重大なリリース検出事項がないことを確認してください。
• 後続作業への引き継ぎ： プッシュ前に、リリースコミット SHA、注釈付きタグ SHA、監査記録／ノートのパス、ロールバックコマンド、正確なプッシュ／検証コマンドを担当者に伝えます。プッシュ後、完了処理の前に、正確な SHA に対する CI および照合の証跡を追記します。

品質チェックリスト

• 変更履歴とノートには、選択した git 範囲で裏付けられる変更だけを記載し、リポジトリのスタイルに沿わせ、コントリビューターとフィード読者というそれぞれの対象読者に合わせます。
• バージョンファイル、リリースコミット、注釈付きタグ、監査記録、ノートにはすべて同じ確認済み SemVer を記載し、1 つのリリース境界に解決されるようにします。
• 完了前に、ローカルでのリリース検証と成果物チェックをすべて通過させます。担当者によるプッシュ後、正確なタグに対する CI と照合を通過させます。
• 通常の却下は AUTO-REDO のままにします。HOLD のヘルパーは 1 つだけとし、担当者へのエスカレーションは宣言された人間による状態に限定します。

---

例

ユーザーの入力: /release 1.7.0 エージェントは事前チェックを実行 → v1.6.0..HEAD の Git 履歴を読み取り → コミットを分類 → CHANGELOG.md のエントリーと厳選したリリースノートの草案を作成 → バージョンファイル（package.json、version.go、プラグインマニフェスト）を検出 → レビュー用に草案を提示 → 承認後、ファイルを書き込み、リリースコミットを作成し、注釈付きタグを作成して、プッシュ方法を案内します。その後、ユーザーがプッシュすると scripts/verify-release-ci.sh v1.7.0 を検証し、ao reconcile --json を実行して、実行 ID／結論と照合状態を記録します。

ユーザーの入力: /release --check エージェントはすべての事前チェックを実行し、GO／NO-GO の概要表を出力します。書き込みは行いません。

ユーザーの入力: /release（バージョン指定なし） エージェントはコミットを分類し、理由とともにバージョンを提案します（破壊的変更があればメジャー、新機能があればマイナー、修正のみならパッチ）。その後、ユーザーに確認または変更を求めます。

ユーザーの入力: /release 1.7.0 --dry-run エージェントは、変更履歴のエントリーとバージョン更新がどのようになるかを表示し、書き込みを行わずに終了します。

各手順の詳細な例については、references/release-workflow-detail.md を参照してください。

トラブルシューティング

問題	原因	解決策
「No commits since last tag」エラー	作業ツリーがクリーンで、新しいコミットがない	保留中の変更をコミットするか、リリースをスキップします
バージョン不一致の警告	package.json と go のバージョンが一致しない	リリース前に手動で同期するか、正とするソースを1つ選びます
事前チェック中にテストが失敗する	破壊的変更が事前に検出されていない	テストを修正するか、--skip-checks を使用します（推奨しません）
作業ツリーが汚れているという警告	未コミットの変更がある	リリース前にコミットするか、スタッシュします
GitHub Release ページの本文が空	既存のドラフトとの GoReleaser の競合	CI は GoReleaser の実行前に既存のリリースを削除します。ローカルで gh release create を実行しないでください
ci-local-release.sh が agents-hash で停止する	~/.agents/patterns が大きい	実行前に AGENTS_HUB_OVERRIDE=/tmp/empty-hub を設定します

トラブルシューティングの全項目については、references/release-workflow-detail.md を参照してください。

関連項目

• セキュリティ — 依存関係の監査と脆弱性スキャン（deps を統合）

--check モードを支える CI ワークフロー（または厳選したノートを使用するタグトリガーのリリースパイプライン）を接続または監査する際は、references/gh-actions-ci-patterns.md（一般的な CI）または references/gh-actions-release-automation.md（タグトリガー、ドラフトフロー、アセットのアップロード）から関連するパターンを取り入れてください。厳選したリリースノートファイルを生成する場合や、CHANGELOG.md のずれを監査する場合は、変更履歴を全体像を把握するためのレイヤーとして扱い、構造化されたセクション、破壊的変更の明示、ノートと変更履歴の規則について references/changelog-as-research-artifact.md を使用してください。

参考ドキュメント

• references/release-workflow-detail.md — 手順の全詳細
• references/release-cut-and-bump.md — HEAD 以外のコミットからの切り出しと AgentOps 固有の更新対象
• references/release-notes.md — 厳選ノートの形式と製品分野の分類
• references/release-preflight-and-publishers.md
• references/release-cadence.md
• references/changelog-as-research-artifact.md
• references/gh-actions-ci-patterns.md
• references/gh-actions-release-automation.md
• references/release.feature — 実行可能な仕様：--check の準備状況、厳選ノートと CHANGELOG の照合、オペレーターによるタグ付け／プッシュ、正確な SHA のグリーン検証（soc-qk4b）