maintain-skills

スキルを保守する

このライブラリに取り込まれているスキルを、アップストリームの更新に合わせて最新に保ちながら、この環境に適した軽微なローカル調整は維持します。調整の契約では、この環境の定義と、各アップストリームの変更をどう判断するかを説明しています。保守ガイドには、各手順で使用する補助コマンド、実行時の状態、チェック、ブランチのルールが記載されています。

次の2つのモードのいずれかで実行します。

• アップストリーム：各スキルについて、確認済みの時点以降のアップストリームの変更を採用し、新しいアップストリームのスキルを取り込み、前回の実行以降にファイルが変更されたスキルを確認します。
• 監査：アップストリームへの対応を行った後、持ち越し項目、忠実性のバックログ、保留中のスキル、古くなったレビューを順に確認し、各スキルを現在のツール、ドキュメント、リポジトリの規約と照合します。

ユーザーまたはスケジュールされたタスクがモードを指定できます。指定がない場合は、beginが選択します。スキルの対象を絞り込めるのは、明示的に指定されたスキルのサブセットのみです。

全体を通して/swarmを使用します。各ワーカーには、ソースのグループ、スキルのバッチ、修正など、1つの担当範囲を割り当てます。その際、正確なローカルリビジョン、変更されない候補、調整の契約、証拠の要件、書き込み可能なファイルを明示します。ワーカーは、別のコーディネーターを立ち上げずに、担当範囲を直接作業します。コーディネーターはソースの取得、チェックポイントと正規ドキュメントの管理、統合作業を担当し、すべてのワーカーの結果を回収します。失敗した結果や未提出の結果は保留のままにします。委任を行わず順番に作業する場合は、実行レポートに独立性が失われたことを記録します。

1. 開始

リポジトリのAGENTS.md、調整の契約、保守ガイドを読みます。beginを実行します。ロックが保持中だと報告された場合は、そこで停止し、ロックを保持している実行を明記します。それ以外の場合、この実行がreleaseを実行するまでロックを保持します。

レポート用に、beginのleftovers、つまり配信前に終了した実行の編集内容を記録します。その後、ガイドのブランチルールに従って両方の作業ツリーを同期し、それらの編集内容を破棄します。この作業は独自に再開されます。実行がチェックポイントと持ち越し項目を確定するのは配信後のみなので、中断された実行の項目は、beginが確認した状態のまま未解決です。beginがlegacyNextActionsを報告した場合は、そのファイルをnext-actions.jsonに変換します。未解決の保守PR、および質問からリンクされたPRについて、commentsSince以降に投稿されたオーナーのコメントを読みます。scripts/check-installs.pyでインストール済みのコピーを確認し、古くなっている場合はAGENTS.mdの指示に従って更新します。ライブラリの作業ツリーで、beginのチェックポイントを指定してinventory --resumeを実行します。

**完了条件：**この実行がロックを保持し、両方の作業ツリーが同期ルールに一致していること。また、beginのモード、チェックポイント、質問、持ち越し項目、残存編集、commentsSince以降のすべてのオーナーコメント、最新のインストール確認結果、およびchangedSince、contextChanged、staleReviewsの各リストを含むインベントリを把握していること。あるいは、ロックが保持中のため実行が停止し、ロックを保持している実行を明記していること。

2. 変更点を確認する

fetchを実行し、続けて--resumeを指定してcompare --fetchを実行します。インベントリ、フェッチ結果、比較レポートを実行フォルダーに保存します。以下の順番で作業リストを作成します。この順番がそのまま作業の順番になります。

1. まだ反映されていないオーナーの回答やコメント、およびPRなしでプッシュされたメンテナンスブランチ。
2. 変更された上流のスキルと共有入力、ならびにフェッチに失敗したすべてのソース。
3. カタログのスイートにおける、新規、削除、または移動された上流のスキル。
4. 新しいスキルを含むchangedSinceのスキルと、contextChangedの入力。
5. 監査モードのみ：引き継がれた項目（期限超過のものを優先）、インベントリのfidelityBacklog、チェックポイントで保留中と記録されたスキル、次に古いものからライブラリの4分の1までのstaleReviews。

上流モードで項目1～4がすべて空の場合は、比較レポートからチェックポイントを保存し、古い実行を整理してから、releaseを実行して終了します。変更のない実行では、ブランチ、チェック、レビュー、PR、レポートは必要ありません。

完了条件： 反映されていないオーナーの回答、PRなしでプッシュされたブランチ、比較レポートの項目、失敗したソース、changedSinceのスキル、contextChangedの入力すべてが、作業リストに含まれているか、変更なしとして記録されています。監査モードでは、引き継がれたすべての項目、fidelityBacklogの記録、保留中のスキル、およびライブラリの4分の1までの古いstaleReviewsも対象です。または、変更のない実行として終了しています。

3. 判断して修正する

ガイドのブランチルールに従い、メンテナンスブランチ上で編集します。上流の変更はそれぞれ適応契約に従って判断し、その説明に沿って判断を記録します。修正は/writing-for-agentsを使って分離されたライターに割り当て、返された差分をそれぞれ確認します。契約の説明に従って、新しい上流のスキルを取り込み、廃止を提案します。変更が共有オーナーに関わる場合は、両方のスイートでその利用先を確認します。

changedSinceの各スキルについて、編集によって記録済みの適応内容とリポジトリの規約が維持されていることを確認します。contextChangedの各入力について、チェックポイントのlibraryRevision以降の差分を読み、レビューへの影響を受けるスキルをすべて明記します。監査モードでは、各スキルが対応する環境に照らして、ツール名、コマンド、リンク、プラクティスを確認します。確認は、公開されているツールスキーマ、インストール済みバージョン、ローカルのヘルプ出力から始めます。ファーストパーティのスキルとローカルの適応テキストは/writing-for-agentsを使ってレビューし、ソース由来のテキストには契約の最小乖離ルールを適用します。

編集したソース由来のスキル、またはchangedSinceで見つかったソース由来のスキルすべてに、契約の忠実性チェックを実施します。監査モードでは、バックログの記録にも実施します。

チェックポイントで追跡されていない修正（この実行でスキル本文またはこのスキル自体の本文から見つかった修正など）に着手する前に、今日の日付を付けてnext-actions.jsonに追加します。これにより、実行が中断されても未完了として残ります。オーナーの判断待ちとなる各項目は、契約の判断記録の説明に従って質問として処理します。予算が尽きた場合、または後続の上流リビジョン待ちの場合に限り、項目を引き継ぎます。その場合は、最初に引き継いだ日付を付けたnext-actions.jsonのエントリを維持するか、追加します。期限超過の引き継ぎ項目はすでに監査を越えて残っているため、今回の監査で完了させるか、質問として提示します。

完了条件： 作業リストのすべての項目が、採用、適応、除外、質問としての提示、または理由を添えたnext-actions.jsonへの引き継ぎのいずれかで処理されています。期限超過の引き継ぎ項目はすべて完了しているか、質問として提示されています。すべてのcontextChanged入力について、影響を受けるスキルが明記されています。編集した、またはローカルで変更されたソース由来のスキルはすべて、両方向の忠実性チェックに合格しています。

4. 検証

変更した手順を最初から最後まで読み、メンテナンスガイドのチェックを実行します。変更したスクリプトやワークフローを小規模で隔離された例で試し、新しい回帰テストがそれぞれ、修正を元に戻すと失敗することを確認します。差分そのもの、判断内容、忠実性、網羅性について独立した最終レビューを依頼し、指摘事項に対応します。実行中に追加されたスキルも網羅対象に含めるため、スキルを再列挙します。

スキルのレビュー済み位置を先に進めるのは、その上流の差分全体について判断が済み、チェックに合格した場合に限ります。

完了条件： チェックに合格し、新しい回帰テストがそれぞれ修正を元に戻すと失敗し、最終レビューの指摘事項がすべて修正、質問、または保留として処理され、レビュー済み位置を進めたものはすべて、その差分全体について判断済みであること。

5. 提出

ライブラリの変更と、このスキル独自のプロセスに関する変更は、それぞれ別のメンテナンスブランチにコミットし、ガイドのプッシュルールに従って各ブランチをプッシュし、それぞれについてドラフト PR を1件作成または更新します。実行時の許可範囲内で行います。定期実行の場合はスケジュール済みプロンプトの許可範囲、呼び出し実行の場合はユーザーの依頼が許可範囲となります。各 PR を確認したら、実行時の状態を確定します。コミットで完了した保留項目、または説明文で確認を求めた項目と、コミットに回答が記録された質問を削除し、その後、この実行で完了したローカルレビューを含めてチェックポイントを保存します。手順3でコンテキストの変更をレビューした場合は、影響を受けたスキルを指定して --context-reviewed を追加します。チェックポイントによって位置が先に進むことはありません。古い実行を整理してから、release を実行します。

変更点、所有者の回答待ちの質問、ソースの失敗や破棄した未処理項目などの失敗、引き続き保留中の網羅範囲を報告します。

予算の終了時点では、新しい作業項目に着手しません。検証、提出、完了済み作業のチェックポイント保存を行い、残りは保留として引き継ぎます。

完了条件： 各 PR がドラフトであり、フォージ上のヘッドがプッシュ済みコミットと一致し、説明文に未解決の質問と、ガイドで求められる各 /usage-review コントラクトの名前が記載されていること。実行時の状態が確定され、その確認後にチェックポイントが保存され、報告が作成され、すべての操作が許可範囲内で行われ、ロックが解除されていること。