issuekit

issuekit

gh CLI を通じて GitHub の issue ライフサイクルを担います。明示的な モード は 5 つです。

• create. 計画ドキュメントまたは簡潔な説明から、適切な形式の issue を作成します。
• start. ready または stacked の issue を専用のワークツリーに取り込み、状態を in-progress に変更します。
• close. PR がマージされたら issue をクローズし、その issue によってブロックされていた作業のブロックを解除して、ワークツリーを削除します。
• sync. 事後に PR と issue の関連付けを調整し、修復します（マージ済み PR でクローズされるべきだった issue、既存の PR にリンクがない場合、マージ済みの issue によって依然として blocked と表示されている依存先）。
• triage. トラッカーの状態を報告し、承認された修正を適用します。これには、issue の検討がまとまった後に needs-planning → ready へ移行することや、対応済み、重複、または古くなった issue のクローズが含まれます。

1 つのスキルに 5 つの役割があるのは、開発ワークフローの 5 つの段階における同じ仕事だからです。作業を登録し、着手し、完了させ、PR のマージ後にすべてを同期し、トラッカーの情報を正確に保ちます。

close と sync の違い。 トラッカーに対する作業は一部重なりますが、違いは手段ではなく 対象範囲 にあります。close は、PR がマージされたと分かっている 指定された 1 件の issue を処理し、ファイルシステムに触れる唯一のモードです（ワークツリーの削除）。sync は事後に トラッカー全体 を調べてずれを修正します。これには、マージ済み PR でクローズされるべきだったのにクローズされていない issue、リンクがない場合、マージ済みの作業によって依然として blocked と表示されている依存先が含まれます。また、ワークツリーには一切触れません。close は、調整の内容を繰り返し記述するのではなく、sync の調整処理を再利用します。

発動条件

ユーザーが GitHub の issue に対する操作を求めている場合は、その依頼に応じてモードに振り分けます。

• create. 「この計画から issue を作成して」「plan-auth.md の issue を作成して」「X の issue を登録して」「これを issue として登録して」「GitHub issue を作成して」「これをタスクとして記録して」「バックログに追加して」「これらの TODO の issue を作成して」。
• start. 「issue #42 を開始して」「#42 に着手して」「#42 を引き受けて」「#42 用のワークツリーを作成して」「今から 42 に取り組みます」。
• close. 「#42 をクローズして」「#42 の対応を終わらせて」「PR がマージされたので #42 を片付けて」「#42 のワークツリーを削除して」「#42 がマージされたので、後片付けして」。
• sync. 「自分の issue を同期して」「この PR はマージされたのに issue がまだオープンのままです」「この PR を #42 にリンクして」「#42 がブロックしていた作業のブロックを解除して」。
• triage. 「バックログをトリアージして」「issue の状態を教えて」「オープンな issue を確認して」「古くなった issue はある？」「バックログの優先順位を決めて」「#42 の優先度を設定して」「優先度が何も設定されていません」「#42 のラベルを変更して」「issue #42 の名前を変更して」「これらの issue のタイトルを修正して」「これらのタイトルは規約に従っていません」「#42 の検討がまとまったので、ready にして」「issue を整理して」「クローズできる issue はどれ？」「これらの重複 issue を統合して」.

モードが明確でない場合は、まず確認します。 モードを選択肢として提示し、何かを実行する前にユーザーに選んでもらってください。また、issue の作成とトラッカーの変更のどちらかを推測してはいけません。

ワークツリーとブランチは gitkit の担当です。 start と close はワークツリーのライフサイクルの開始と終了を担い、ブランチ名、パスの規約、作成するか既存のものを採用するか、削除のすべてを担当する gitkit に処理を委ねます。issuekit が答えるのは 「この issue に取り組める状態か、そしてトラッカーには今どう表示されているか？」 です。gitkit が答えるのは 「このブランチのコードはどこにあるか？」 です。互いの内部には立ち入りません。issuekit は issue 番号とタイトルを gitkit に渡し、gitkit はブランチとパスを返します。

事前確認（すべてのモード）

GitHub にアクセスする前に、ツールが使用できる状態か確認します。

gh --version        # gh installed?
gh auth status      # authenticated?
gh repo view --json nameWithOwner -q .nameWithOwner   # inside a repo?

• gh がインストールされていない、または認証されていない場合は、その旨を伝え、https://cli.github.com と gh auth login を案内してください。別の方法で回避してはいけません。
• issuekit を呼び出した時点で、このプロジェクトが GitHub Issues を使っているかどうかの確認は済んでいます。 すべてのプロジェクトがここで作業を追跡するわけではなく、リポジトリを調査するスキルは、何かを提案する前にその点を確認する必要があります。issuekit ではその必要はありません。issuekit に issue の作成、開始、クローズを依頼する人は、作業場所をすでに示しています。そのため、create はプロジェクトが issue を扱っているかどうかを事前に確認せずに issue を作成し、リポジトリが別の場所で作業を追跡しているように見えるという理由で、どのモードも依頼を断ることはありません。
• シェルも gh も使えない場合（ブラウザベースのエージェントなど）は、gh を実行できません。代わりに、ユーザーが提供した情報をもとに判断し、ユーザー自身が実行できる正確な gh コマンドを出力してください。issue の本文はコードブロックで示し、gh issue create … / gh issue close … の行はそのまま貼り付けられる形にします。

このスキル全体に適用される安全方針。 issue の作成、クローズ、ラベルの変更、および PR 本文の編集は、外部に反映される変更です。すべての変更を実行前にプレビューし、承認を得てください。GitHub 上の変更が、ユーザーの意図なく行われないようにします。 PR をマージしてはいけません。

すべての呼び出し元について、create、start、close、sync でのラベル変更は例外です。 issue または PR のラベル追加・削除は、プレビューや確認なしでそのまま実行します。人がキーボードで操作する場合も、オーケストレーターが実行する場合も同様です。対象となるのは、ライフサイクルと優先度の両方のラベルです。ラベル変更は手軽で、変更内容が見えやすく、コマンドひとつで元に戻せるため、変更のたびに確認を求めるコストは、変更そのものに見合いません。また、変更を拒否すると、すでに起きた作業がトラッカー上で正しく反映されなくなります。各ラベル変更は、それに伴うプレビューに明記し、引き継ぎ時に変更後のラベルを報告してください。 これにより、変更を監査できる状態に保ちます。

この例外が適用されるのはラベルだけです。それ以外の外部に反映される変更には、上記のルールが引き続き適用されます。create は作成する issue をプレビューし、close はクローズとワークツリーの削除をプレビューし、sync は各ペアリングと本文の各編集をプレビューします。triage はこの例外の対象外です。 triage のラベル変更は、実際に行われた作業を記録するものではなく、レポートで提案する判断（分類、順位付け、昇格）です。そのため、triage はまずレポートを提示し、ラベル変更を含むすべての修正を、ユーザーの承認を得てから適用します。PR をマージしてはいけません。

タイトルの規則（このスキルが作成するすべてのイシュー）

イシューのタイトルは、commitkit のコミットサブジェクトおよび Conventional Commits の仕様と同じ形式にします。これにより、トラッカーと git ログを一連のワークフローとして読めます。形式：

type(scope): short imperative summary

変更するファイルではなく、イシューで実現する内容に基づいて type を選びます。使用できる種類は commitkit と同じで、変更ありません。

type	when
feat	ユーザーが目に見える新機能
fix	バグ修正
hotfix	ベースブランチに直接適用する緊急の修正
docs	ドキュメントのみ
refactor	動作を変えないコード変更
perf	パフォーマンスの改善
test	テストの追加または修正
build / ci	ビルドシステム、依存関係、パイプライン
style	ロジックを変えないフォーマットや空白の変更
chore	上記のどれにも当てはまらない定期的なメンテナンス

作成するすべてのタイトルに、次のルールを適用します。

• (scope) は必須です。作業対象のモジュール、パッケージ、ディレクトリ、または機能領域を指定します（feat(auth): …）。リポジトリ全体に関わる作業（リポジトリ全体の設定、ツール、横断的な整理）の場合は、repo を指定します：chore(repo): …。
• すべて小文字にします。タイトルの先頭を含め、単語を大文字にしないでください。固有名詞と頭字語（OIDC、SSO、CI）のみ例外です。
• 命令形で、作業の内容ではなく「もたらす効果」を示します（「sso login を追加する」）。末尾にピリオドは付けず、簡潔にします。
• 最初のフェーズではなく、イシュー全体にタイトルを付けます。 複数フェーズにわたるイシューでは、最後まで実装する機能を示します（feat(auth): add sso login）。各フェーズは本文に記載します。タイトルが一つのフェーズだけを示しているようなら、イシューを細分化しすぎている可能性があります。

hotfix では、ブランチを作成する前にイシューを立てる必要はありません。 ベースブランチに直接適用する緊急作業は、症状への対応から始まります。担当者が hotfix-<slug> ブランチを作成し、トラッカーを待たずに hotfix(scope): のプルリクエストを作成します。そのため、このスキルのどのモードも hotfix を制限せず、start もその手順には含まれません。作業後に記録のためイシューを作成する場合は、タイトルを hotfix(scope): … とし、プルリクエストがすでに開かれている場合は in-review ラベルを付けます。作業がまだ始まっていないことを意味してしまうため、ready ラベルは決して付けないでください。

リポジトリ独自のイシュータイトルのスタイルがある場合（gh issue list や .github/ISSUE_TEMPLATE/ で確認できます）は、そちらに従い、その旨を伝えてください。詳しくはNotesを参照してください。

---

ライフサイクルラベル（すべてのモード）

issuekit は、ワークフローのどの段階にあるかを、少数のフラットなステータスラベルで追跡します。これらのラベルは使用しますが、作成はしません。ラベルの準備は、連携するスキルであるrepokitの役割です。このスキルが必要とするラベルがリポジトリにない場合は、そこで停止し、追加方法をユーザーに案内してください（repokit を実行するか、該当する gh label create のコマンドを実行します）。自分で作成したり、黙って処理をスキップしたりしてはいけません。

正式なマップでは、ワークフローを左から右へ進むステータスラベルを常に1つだけ有効にし、該当する場合は3つの分岐先ラベルを適用します。この表は、これらのラベルを準備するスキルであるrepokitとの共通の契約です。メンテナーは、ラベル名、色、意味について、2つの表の内容を一致させてください。

ラベル	色	意味	通常の設定元
triage	FBCA04	起票済みだが、まだ評価も細分化もされていない	作成（臨時）、トリアージ
needs-planning	F1C40F	作業に着手するには仕様がまだ不十分で、人による計画・検討セッションが必要	issuekit create / afkkit gate
ready	0E8A16	仕様が固まり、独立して作業できるため、今すぐ専用のgitワークツリーに取り込める	issuekit create
blocked	D93F0B	未着手の前提条件が満たされていない	issuekit create / sync
stacked	006B75	前提となる課題のPRがオープン中のため、その課題の上に積み重ねたブランチで今すぐ作業できる	prkit / issuekit sync
in-progress	1D76DB	ワークツリーで作業中	issuekit start
in-review	5319E7	PRがオープン中で、レビューまたはマージ待ち	PR作成スキル / sync
needs-info	D4C5F9	先に進むための詳細情報が必要で、作業が停滞している	トリアージ
wontfix	FFFFFF	対応しない	トリアージ
duplicate	CFD3D7	別の課題に統合された	トリアージ

クローズ済みの課題には、done ラベルは不要です。クローズ状態自体が完了の合図になるためです。

ready と blocked は並行作業のためのラベルの組み合わせです。 issuekit は、各課題を順序の制約なく専用のワークツリーで開始できるように規模を調整し、順序を設定します。こうした課題には ready を付けます。例外として、別の課題が取り込まれるまで本当に着手できない課題には blocked を付け、前提となる課題を記録します。これにより、gh issue list --label ready で、ユーザーが今すぐ並行して着手できる課題を正確に一覧表示できます。

blocked と stacked は、待機中と積み重ね可能な状態を分けます。この区別が重要です。 誰も着手していない前提課題は本当に待つ必要があるため、その依存課題は blocked のままです。前提課題が実装済みで、プッシュされ、オープン中のPRにある場合は、待つ必要はまったくありません。コードが存在するため、依存課題は前提課題のブランチから作成したブランチで今すぐ作業でき、PRのマージ先も trunk ではなくそのブランチになります。その課題には stacked を付けます。この2つの状態を1つにまとめると、レビューをできるのが自分だけの作成者がその完了を待つことになり、個人プロジェクトの作業が止まってしまいます。

stacked は計算によって得られる状態ではなく、保存されるラベルです。そのため、ready と同様に gh issue list --label stacked で並行作業の対象を一覧表示できます。保存されたラベルは古くなる可能性があるため、それだけで処理を許可することはありません。ブランチを作成する前に、start が前提課題のPRをその場で再確認します。

依存関係の記録

GitHub 標準のイシュー依存関係を正とします。 gh issue edit でエッジを書き込み、文章を解析するのではなく、構造化データとして読み戻します。

gh issue edit 44 --add-blocked-by 43
gh issue list --state open --json number,title,labels,blockedBy,blocking

イシューを読む人が別の画面を開かなくても依存先を確認できるよう、本文にも Blocked by #N の行を書き続けてください。この行は説明文であり、保存先ではありません。 両者が食い違う場合は、標準のエッジを優先し、この行を修正します。

フラグの利用には gh 2.94.0 以降が必要です。それより古い場合は、拒否するのではなく機能を縮退させます。 本文の行だけを書き込み、標準のエッジをスキップしたこととその理由を一度だけ伝えます。これらのラベルとワークフローは、そのマシンにインストールされている gh のバージョンを問わず動作する必要があります。

needs-planning と ready は、人間による確認のゲートとなる組み合わせです。 ready は、人間の介入なしで作業できるだけの仕様が決まっていることを意味します。つまり、エージェント（または afkkit のようなオーケストレーター）が、人間を介さずにそのまま PR まで進められます。needs-planning は、イシューに取り組める状態にする前に、人間による計画の策定や掘り下げのセッションがまだ必要であることを意味します。イシューに ready を付けられるのは、グリルで決定事項が確定した後だけです。作成時のグリルゲートを参照してください。これにより、gh issue list --label needs-planning は人間による対応がまだ必要なイシューの正確な一覧となり、ready の展開先一覧と対になります。

種別はラベルではなくタイトルに記載します。 イシューにはすでにタイトル規約に従って feat(scope): / fix(scope): が付いているため、この一覧には type: ラベルはなく、ライフサイクル状態のみが含まれます。

必要なラベルがない場合は、gh label list で一度確認してから、その場しのぎで変更するのではなく、不足を報告します。

このリポジトリにラベル blocked がありません。repokit でワークフローのラベルを用意するか、このラベルだけを追加してください。 gh label create blocked --color D93F0B --description "has an unmet prerequisite that has not started"

ラベルは存在してから適用してください（gh issue edit <n> --add-label <label>）。ラベルの免除規定に従い、この書き込みに確認は不要です。一緒に提示するプレビューにラベル名を記載し、引き継ぎ時にも報告してください。

依存先の昇格

依存先のラベルを決める遷移ルールは一つだけであり、依存先を移動または確認するすべてのモードで適用します。 前提イシューの状態が変わったら、直近で移動したイシューだけではなく、開いているすべての前提イシューから依存先のラベルを再計算します。イシュー C が A と B に依存している場合、A がマージされても、B がまだ着手されていなければ C は blocked のままです。

依存関係の記録で指定した保存先である標準のエッジをたどって依存先を探し、それぞれのイシューの前提イシュー一式を同じ方法で読み取ります。

gh issue view 43 --json blocking -q '[.blocking[].number]'      # who waits on #43
gh issue view 44 --json blockedBy,labels                          # everything #44 waits on

gh 2.94.0 より古い場合は、代わりに本文の Blocked by #N の行を読み取り、標準のエッジが利用できないことを一度だけ伝えます。その後、次の条件に一致する最初の行を適用します。

開いている前提イシュー	新しいラベル
なし	ready
すべてに開いている PR があり、それらの PR が一つのチェーンを形成している（各 PR のベースが次の PR のヘッドである）	そのチェーンの最上位 PR に stacked
すべてに開いている PR があるが、それらの PR が一つのチェーンを形成していない	現在のラベルを維持し、互換性のない前提イシューを報告する
少なくとも一つに開いている PR がない	blocked

• 前提イシューの変更によって移動するのは、blocked と stacked の依存先だけです。 needs-planning の依存先は、依存関係ではなくグリルゲートによって保留されているため、ラベルを維持します。作業が始まっている in-progress または in-review の依存先も、ラベルを維持します。
• 一つのレイヤーには親ブランチが一つあります。 開いている PR が別々のブランチにある場合、すべてを満たすベースはありません。候補となる各親 PR を報告で挙げ、ユーザーに判断を委ねてください。いずれか一つを選んではいけません。
• ラベルの変更はすべて置き換えです。 新しいラベルを追加するのと同じ呼び出しで、現在のライフサイクルラベルを削除します。例：gh issue edit 44 --remove-label blocked --add-label ready。
• PR の検索に失敗した場合、依存先には手を加えません。 状態は不明として報告し、失敗した呼び出しを明記します。エラーは PR が存在しない証拠にはなりません。

優先度ラベル（すべてのモード）

2 つ目のラベル名前空間であり、次に何を取り上げるかを決めるものです。ライフサイクルラベルと同様に、issuekit はこれらのラベルを使用するだけで、作成することはありません。ラベルは repokit が用意します。ラベルがない場合は、回避策を講じずに報告します。

label	color	意味	通常の設定者
critical	B60205	すべてを中断する。すでに進行中の作業より優先	issuekit create / triage
high	E99695	対応可能な他の issue より先に対応する	issuekit create / triage
medium	FEF2C0	通常の優先度。評価後のデフォルト	issuekit create / triage
low	C5DEF5	いずれ対応する価値はあるが、何よりも優先されることはない	issuekit create / triage

この表は repokit との共有契約のもう半分です。両方のスキルで、名前、色、意味を一致させてください。

ライフサイクルと優先度は互いに独立しているため、それぞれのラベルを 1 つずつ付け、どちらかがもう一方を示すことはありません。 ライフサイクルは対応可能かを示し、優先度は次に対応すべきかを示します。issue が ready かつ high、または blocked かつ critical であっても、どちらも整合しています。今すぐ対応可能な low の issue は依然として対応可能であり、ブロックされている critical の issue は、そのブロッカーが重要である理由そのものです。一方から他方を決して推測しないでください。critical だからといって issue を ready に昇格させると、十分に精査されていない作業が監視されていないワーカーに渡されてしまいます。ready のガードはまさにそれを防ぐためにあります。

優先度ラベルがない場合は未評価であり、medium ではありません。 ラベルがないことは実際の状態であり、triage が探すのはその状態です。issue を暗黙に中間の優先度に設定しないでください。ランク付けされていない issue を全員が通常の優先度だと思い込むと、実際に誰かが検討した issue と区別できなくなります。この尺度の価値は、その違いにあります。終了予定のないサイドイグジット（wontfix、duplicate）を除き、すべてのオープン issue に優先度を設定することが想定されています。

優先度ラベルは一度に必ず 1 つだけ付けてください。GitHub はこの制約を適用しないため、こちらで徹底する必要があります。 ラベルは相互排他的ではないフラットな名前空間です。そのため、issue に critical と low を同時に付けることもでき、優先度が 2 つ付いた issue は、後続のあらゆる処理で予測不能な順序になります。したがって、ラベルの更新は追加ではなく、常に置き換えとして行います。issue の現在のラベルを読み取り、実際に付いている兄弟ラベルを、新しいラベルを追加するのと同じ呼び出しで削除してください。

gh issue view 42 --json labels -q '[.labels[].name]'   # → ["ready","medium"]
gh issue edit 42 --add-label high --remove-label medium

兄弟ラベルを 3 つとも一律に削除するのではなく、issue に実際に付いているラベルを基に削除対象を決めてください。そうすることでプレビューの内容を正確に保てます（medium → high と set high では意味合いが異なります）。また、存在しないラベルの削除を gh のバージョンがどのように処理するかにも左右されません。

---

モード

各モードの本文は、modes/ 内のファイルに 1 つずつ格納されています。When this fires に従ってルーティングし、該当するファイルを 1 つ読んで、その手順に従ってください。この行より上の内容はすべてのモードに適用されるため、モードのファイルには再掲していません。

• モード create → modes/create.md を読み、その手順に従ってください。
• モード start → modes/start.md を読み、その手順に従ってください。
• モード close → modes/close.md を読み、その手順に従ってください。
• モード sync → modes/sync.md を読み、その手順に従ってください。
• モード triage → modes/triage.md を読み、その手順に従ってください。

---

共有アクション：計画や判断をコメントする

create と triage では、監査証跡として、計画の抜粋や判断を issue に投稿する場合があります。これはモードではなく、共有アクションです。

gh issue comment <n> --body-file <file>

複数行の Markdown には一時ファイルを使用し、使用後に削除してください。

メモ

• 決して PR をマージしたり、変更内容を提示して事前に OK を得たりせずに GitHub の状態を変更したりしないでください。
• リポジトリに独自の issue の規約がある場合は、.github/ISSUE_TEMPLATE/ のテンプレート、ラベル付けの方式、gh issue list で確認できるタイトルのスタイルのいずれであっても、ここに記載されたデフォルトより優先し、その規約に従ったことを伝えてください。
• 複数行の内容には、--body より --body-file を優先してください。作業後は一時ファイルを削除してください。
• issue の規模は作業に見合ったものにしてください。1 行の修正なら、受け入れ基準を 1 つ設けた issue を 1 件作成し、段階的な大規模開発にしないでください。本文の分量は計画の実際の範囲に合わせ、大規模な計画は 1 件の大規模な issue のままにしてください。