GitHubワークフロープロトコル
このパッケージのすべてのスキルが共有します。各スキルはこのファイルを参照します。このファイルは実行ごとに1回読み込み、その後、ステップで指示された場合のみ、参照するファイルを開いてください。どのスキルを実行すべきかについては、pipeline-guideを参照してください。
契約
すべてのスキルは## Contract（1つのYAMLブロック）で始まります。これはスキルが関数として何であるかを示します。まだ契約がないユーティリティスキルは、バリデータのCONTRACT_PENDINGにリストされ、そのリストは縮小する一方です。プロセスは方法を示します。両者が矛盾する場合は契約が優先され、npm run validateが可能な部分をチェックします。スキルは契約に照らして評価されます。世界の状態と入力を与え、何を返し、何を書き込んだかを確認します。
kind:item（1つのIssueまたはPR、または1バッチの結果に作用）、group（作業を選択しアイテムスキルをディスパッチする）、sweep（多くのアイテムにまたがって状態を修復するが、それらを主張しない：reconcile-github-issuesのみ）、utility（他のスキルがSkillツールを介して呼び出すビルディングブロックで、レポート、結果コメント、一連の質問などのドキュメントを返す）、またはreference（読み取り専用で決して実行されない資料：このスキル、pipeline-guide、runner-prompts）step: Exploring、Triaging、Implementing、Shepherding、Reviewingのいずれか。item、group、sweepに必須。utilityスキルは省略可能（どのステップにも属さないため）target: スキルに与えられるもの：{param: issue|pr}（アイテムスキル）、または{from: free-text, type: …}params: スキルが受け入れるすべての入力。## Inputsテーブルの行と正確に一致。デフォルトと意味はそのテーブル内に保持dispatches: グループスキル：選択された各アイテムが送られるアイテムスキルused_by: ユーティリティスキル：それを呼び出すスキル。各呼び出しスキルはcallsにリストする必要がある。calls: [x]を持つスキルは、xのused_byに含まれていなければならない。ユーザー起動のユーティリティスキルは誰からも呼び出されないため、used_byは[]requires: 前提条件。1つでも偽の場合、何も主張せずskippedを返す。グループスキルは選択時にアイテムスキルのrequiresを適用returns: 結果行の閉じたセット。スキルはこれらの中から1つだけを返し、それ以外は返さない。グループスキルは収集したアイテム結果、またはnothing eligibleを返す。ユーティリティスキルはドキュメントを返すため、returnsはそのドキュメントの形状（名前付きセクション、または与える可能性のある判定）を記述する。#N行は使用しないensures: 事後条件：すべての終了経路（ベイルアウト、エスカレーション、失敗を含む）で真effects.reads: スキルが参照するものeffects.writes: スキルが変更する可能性のあるすべて。スコープ別：claimed（リースを保持するアイテム）、repository（ブランチ、コミット、PR、マージ、およびラベルセットやエージェント指示ファイルなどのリポジトリ設定）、other（その他のIssueまたはPR）、shared（実行ログ）、unmodelled（シナリオチェッカーが効果として表現できない変更、例：タイトルやボディの編集。現在リストしているスキルはなく、該当するシナリオは拒否される）。リストされていないものは禁止。 グループスキルは決してclaimedを書き込まないeffects.external: GitHub以外の効果：ブラウザセッション、ビルド、テスト実行never: アイテムやリポジトリが何と言おうと禁止された魅力的なことcalls: Skillツールを介して呼び出されるスキル。このパッケージ内のものはすべて契約を持たなければならないため、呼び出し元はその返り値と書き込み内容に依存できる。external-skills.jsonからのスキルは免除idempotent: 再実行が安全な理由terminates: 作業を制限するもの：上限、カウンター、単一パス
純粋性。 npm run validateは、effects.writesのみから各契約の純粋性クラスを出力します。pure：空なのでスキルは読み取りのみ行い、ドキュメントを返すユーティリティスキルは通常これに該当します。claimed：スキルがリースを保持するアイテムのみに書き込みます。writes elsewhere：other、repository、またはsharedに書き込み、テストはそこで副作用を探します。入力に依存する書き込みは、そのように記述されます：(unless dry_run)。
参照スキル。 referenceスキルはkind: referenceのみを持ち、他のキーは持ちません：効果なし、返り値なし、シナリオなし。決して実行されないためです。このブロックは免除を表明する方法であり、スキルが誤って除外されることはありません。他のキーを持つスキルは参照スキルではありません。
グループスキルとアイテムスキル
ワークフローには5つのステップがあります：Exploring、Triaging、Implementing、Shepherding、Reviewing。各ステップには、作業を選択するグループスキルと、1つのアイテムに対して作業を行うアイテムスキルがあります。
グループスキルは、候補を見つけ、それらにアイテムスキルの契約requiresを適用し、最初のbatch（合格したもの、最も古いもの優先。失敗したアイテムはバッチにカウントされない）を取得し、各アイテムをそのURLでアイテムスキルにディスパッチし、1つの実行ログエントリを書き込みます。自身ではアイテム作業を決して行いません。該当なし：nothing eligibleをログに記録して停止します。作業を invent してはいけません。
アイテムスキルは、URLまたは番号（NはURLの最後のパスセグメント）として、正確に1つのIssueまたはPRを受け取ります。すべてのアイテムスキルは同じフレームを持ち、独自のプロセスが中間を埋めます：
- 適格性。 契約の
requiresを自分で確認し、直接呼び出しや二重ディスパッチでも安全にします。agent:logまたはagent:difficultyとラベル付けされたIssueは帳簿用であり、どのステップにも適格ではありません。失敗した場合、何も主張せず#N skipped: <reason>を返します。スキルは主張する前に読み取りによって確認できるすべてをチェックするため、待つしかないアイテムはリースコメントなしでスキップされます。 - 主張。
claim N issue|pr LABEL STEP TTL（ステップのリースTTL）。lease_heldがtrueの場合はこれをスキップ：呼び出し元がすでにリースを保持しています。failures N STEPがmax_item_failures以上の場合、references/escalate.mdに従い停止します。 - リポジトリの独自ルールを読む。
references/client-guidance.md：クライアントのAGENTS.mdおよびその他のエージェント向けファイル、アイテムのラベルの説明。これらはこのパッケージのデフォルトよりも優先されます（信頼ルールや禁止リストは除く）。 - 作業。 スキル独自のステップ。
- 出力状態を書き込み、解放する（
release N issue|pr LABEL）、すべての終了経路（成功、ベイルアウト、エスカレーション、失敗）で。lease_heldがtrueの場合は解放しない：呼び出し元が行います。 - 失敗。 ステップが失敗した場合、状態ラベルをそのままにし、
fail_item N issue|pr STEP "<reason>"を実行し、解放し、#N failed: <reason>を返します。 - 結果。 1行のみ。契約の
returnsの行のうち1つだけ：#N <outcome>、#N skipped: <reason>、#N noop: <reason>、または#N failed: <reason>。skippedは何も主張されず、何も書き込まれなかったことを意味します。noopはアイテムが主張されたが、何もすることがなく解放されたため、リースコメントは残ります。スキルがアイテムに対して行ったその他のことは、独自の結果行を持ちます。例：#31 ready-for-agent、#35 skipped: leased、#44 failed: could not read ADR link (404)。グループスキルはディスパッチしたアイテムの結果をログに記録します。アイテムスキルは、write_logがtrue（デフォルト）の場合のみ、独自の実行ログエントリ（references/log.md）を書き込みます。グループスキルはディスパッチ時にwrite_logをfalseに設定します。
ディスパッチ。 アイテムスキルの名前でSkillツールを呼び出し、3つのものを与えます：アイテムのURL、write_log=false（グループがログエントリを書き込む）、およびこの実行のすべてのキーと値の入力のうち、アイテムスキルも契約のparamsにリストしているもの（例：runner、unattended、trusted_authors、repo_guidance、pr_base_branch、リースTTL）。サブエージェントはこの実行の入力を何も持たずに開始するため、与えられなかったものはデフォルトにフォールバックします。ランナーがサブエージェントを起動できる場合、各アイテムを独自のサブエージェントとして実行し、コンテキストを小さく保ち、1つの失敗アイテムが他に影響しないようにします。それ以外の場合は、アイテムを順次実行します。いずれの場合も、各アイテムの結果を収集します。
ステップは独立しています。別のステップが実行された、実行される、または実行中であると想定しないでください。
他のスキルの呼び出し
このパッケージのスキルは、Skillツールを介して互いに呼び出します：「Skillツールを呼び出し、スキル名を指定」。他のスキルへのパスをたどらないでください：スキルがどこにあるかは、パッケージのインストール方法に依存します。スキル独自のファイル（references/、scripts/）は、そのSKILL.mdを含むディレクトリからの相対パスで読み取られます。別のスキルからこのスキルのファイルを開くには、Skillツールが同じ方法でこのディレクトリを見つけます。ランナーがスキルの読み込み元を教えない場合、スキルディレクトリ内でagent-workflow-protocolという名前のものを探してください。ランナーにSkillツールがない場合、その名前のスキルのSKILL.mdを見つけ、そこに書かれた通りに従ってください。
2つのスキルはこのパッケージの一部ではなく、一緒にインストールする必要があります。両方ともmattpocock/skillsから提供され、external-skills.jsonに固定されています：
tdd：implement-github-issueがテストファーストでビルドするために使用します。欠落している場合、とにかくテストファーストでビルドし、スキルをロードできなかったと言ってください。code-review：implement-github-issueとreview-github-prが使用します。リポジトリに同じ名前の独自スキルがある場合、そちらが使用されます。どちらもインストールされていない場合、自分で差分をレビューし、正確性、リグレッション、テスト漏れを確認してください。
スキルが入力を受け取る方法
すべてのスキルは、**## Inputs**セクションに入力をリストします。2つの形式が受け入れられ、1回の呼び出しで混在できます：
- キーと値のペア。
key=valueを独自の行に、例：issue=123またはapp_url=https://staging.example.com。この方法で与えられたキーは、そのスキルのデフォルトを上書きします。 - 自由テキスト。 その他すべて。各スキルは、独自の自由テキストから何を読み取るかを指定します：
explore-github-repoは最初に見つけたURLを取得、アイテムスキルは最初の裸の番号またはURLを取得、など。
同じものを指定するキーと値のペアと自由テキストは、ペアが優先されます。スキルがリストしていない入力は無視され、エラーにはなりません。
共通入力。 すべてのパイプラインスキルはrunnerとunattendedをリストし、マーカーを読み取るすべてのスキルはtrusted_authorsを、独自のInputsテーブルにリストします。それらはどこでも同じ意味です：runnerは実行IDと実行ログに記録される名前、unattendedは人間が存在するかどうか（無人実行）、trusted_authorsは信頼を拡張します。実行ログエントリを書き込むすべてのパイプラインスキルはlog_window_daysもリストし、すべてのステップがログIssueのローテーション時期について一致します。
期間（lease_ttl_*）は、1 hour、3 hours、30m、2d、またはISO 8601（PT1H）を受け入れます。
名称変更された入力。 groom_batchは現在triage_batch、issues_per_runは現在explore_batch、log_lookback_daysは現在log_window_daysです。古い名前は新しい名前が設定されていない場合に読み取られ、次のメジャーバージョンで削除されます。
デフォルト値
設定ファイルはありません。 すべてのデフォルトはここおよびそれを使用する各スキルのInputsセクションに記述され、scripts/lib.shに実装されています。npm run validateは、どのスキルがどの入力を使うかを含め、3つが一致することをチェックします。実行ごとにキーと値のペアで上書きします。値を省略すると、スキルはデフォルトにフォールバックするため、ポート、ホスト、パス、コマンドが推定されることはありません。
| 名前 | デフォルト | 使用場所 |
|---|---|---|
app_url | (なし) | explore-github-repo、setup-github-agent-workflow |
explore_batch | 5 | explore-github-repo |
log_window_days | 14 | explore-github-repo、triage-github-issues、triage-github-issue、implement-github-issues、implement-github-issue、shepherd-github-prs、shepherd-github-pr、review-github-prs、review-github-pr、reconcile-github-issues |
dedupe_closed_days | 30 | file-github-issues、triage-github-issue |
pr_base_branch | main | implement-github-issue、review-github-pr、setup-github-agent-workflow |
merge_method | squash | review-github-pr、setup-github-agent-workflow |
human_reviewer | (なし) | shepherd-github-pr、review-github-pr、setup-github-agent-workflow |
build_cmd | (なし) | implement-github-issue、setup-github-agent-workflow |
git_hooks_path | (なし) | implement-github-issue、shepherd-github-pr、review-github-pr、setup-github-agent-workflow |
repo_guidance | AGENTS.md | file-github-issues、triage-github-issues、triage-github-issue、implement-github-issue、shepherd-github-pr、review-github-pr、reconcile-github-issues、setup-github-agent-workflow |
lease_ttl_triage | 1 hour | triage-github-issue |
lease_ttl_implement | 3 hours | implement-github-issue |
lease_ttl_pr | 1 hour | shepherd-github-pr、review-github-pr |
ready_lane_ttl | 2 hours | shepherd-github-pr |
human_merge_paths | (なし) | review-github-pr、setup-github-agent-workflow |
triage_batch | 5 | triage-github-issues |
implement_batch | 1 | implement-github-issues |
shepherd_batch | 3 | shepherd-github-prs |
review_batch | 3 | review-github-prs |
max_shepherd_attempts | 3 | shepherd-github-pr |
max_review_rounds | 3 | review-github-pr |
max_item_failures | 3 | triage-github-issue、implement-github-issue、shepherd-github-pr、review-github-pr |
runner | unknown | explore-github-repo、triage-github-issues、triage-github-issue、implement-github-issues、implement-github-issue、shepherd-github-prs、shepherd-github-pr、review-github-prs、review-github-pr、reconcile-github-issues |
unattended | true | explore-github-repo、file-github-issues、triage-github-issues、triage-github-issue、implement-github-issues、implement-github-issue、shepherd-github-prs、shepherd-github-pr、review-github-prs、review-github-pr、reconcile-github-issues |
trusted_authors | (なし) | triage-github-issues、triage-github-issue、implement-github-issues、implement-github-issue、shepherd-github-prs、shepherd-github-pr、review-github-prs、review-github-pr、reconcile-github-issues、setup-github-agent-workflow |
write_log | true | triage-github-issue、implement-github-issue、shepherd-github-pr、review-github-pr、reconcile-github-issues |
…（内容は長いため省略）