DenisSergeevitch/repo-task-proof-loop

Repo Task Proof Loop

このスキルは、ユーザーが反復可能で監査可能な実装ワークフローを必要とする場合に使用します。特に、機能追加、リファクタリング、移行、バグ修正など、.agent/tasks/<TASK_ID>/ 内にリポジトリローカルな証拠を残すべき重要なコーディングタスクに適しています。

このワークフローで作成されるすべてのタスクアーティファクトは、リポジトリ内に保持する必要があります。

以下の例で scripts/task_loop.py と記載されている場合、そのパスはこのスキルのルートからの相対パスです。シェルの作業ディレクトリをターゲットリポジトリ内にして実行してください。

このスキルの機能

1. .agent/tasks/<TASK_ID>/ 以下に厳格なリポジトリローカルタスクフォルダを初期化します。
2. 必要なアーティファクトファイルをシードまたは更新します。
3. プロジェクトスコープのCodexおよびClaudeサブエージェントテンプレートを .codex/agents/ および .claude/agents/ にインストールします。
4. Codexのベースラインであるリポジトリルートの AGENTS.md と、リポジトリのClaudeガイドファイル（CLAUDE.md または .claude/CLAUDE.md）に、ワークフローを説明する管理ブロックを更新します。
5. エージェントを厳密なループでガイドします：
   • 仕様凍結
   • ビルダーによる実装
   • 証拠のパッケージング
   • 新鮮な検証
   • 最小限の修正
   • 新鮮な検証（PASS になるまで繰り返し）

参照：

• references/REFERENCE.md
• references/COMMANDS.md
• references/SUBAGENTS.md
• references/SCHEMAS.md

このスキルがサポートするコマンド

ユーザーがこのスキルを呼び出した場合、以下の単語をコマンドとして扱います：

• init <TASK_ID>：.agent/tasks/<TASK_ID>/ を作成し、サブエージェントテンプレートをインストールまたは更新し、AGENTS.md とリポジトリのClaudeガイドファイルを更新します。
• freeze <TASK_ID>：ユーザータスク、タスクファイル、およびリポジトリガイダンスから spec.md を作成または改良します。
• build <TASK_ID>：凍結された仕様に基づいてタスクを実装します。
• evidence <TASK_ID>：プロダクションコードを変更せずに、evidence.md、evidence.json、および生のアーティファクトを作成または更新します。
• verify <TASK_ID>：新しい検証パスを実行し、verdict.json を書き込み、必要に応じて problems.md も作成します。
• fix <TASK_ID>：problems.md から最も小さな安全な修正セットを適用し、その後証拠バンドルを更新します。
• run <TASK_ID>：仕様凍結から検証までの完全なループを実行します。
• status <TASK_ID>：現在のアーティファクトの状態を要約します。

ユーザーがコマンドを指定しない場合は、リポジトリの状態から次のステップを推測します：

• タスクフォルダが存在しない場合、最初に init を実行します。ユーザーが初期化のみを明示的に希望する場合は、そこで停止します。そうでなければ、init が成功し .agent/tasks/<TASK_ID>/spec.md が存在する場合、同じターンでリポジトリの状態を再評価して続行します。init を freeze、build、evidence、verify、fix、validate、status、またはサブエージェントの作業と重複させないでください。
• spec.md がない、またはプレースホルダーのみの場合は、freeze を実行します。
• 実装がまだ完了していない場合は、build を実行します。
• 証拠が古いか不足している場合は、evidence を実行します。
• 新しい判定結果が存在しない場合は、verify を実行します。
• 判定結果が PASS でない場合は、fix を実行します。

初期化ステップ

リポジトリルートまたはリポジトリ内のカレントワーキングディレクトリから、バンドルされている初期化スクリプトを実行します：

scripts/task_loop.py init --task-id <TASK_ID>

オプションのタスクシード：

scripts/task_loop.py init --task-id <TASK_ID> --task-file path/to/task.md
scripts/task_loop.py init --task-id <TASK_ID> --task-text "ユーザータスクのテキスト"

初期化スクリプトは以下を実行します：

• リポジトリのルートを解決します。
• .agent/tasks/<TASK_ID>/ を作成します。
• raw/ 配下のプレースホルダーを含む、すべての必要なアーティファクトを作成します。
• プロジェクトスコープのサブエージェントファイルをインストールします。
• AGENTS.md とリポジトリのClaudeガイドファイルに、管理されたワークフローブロックを挿入または更新します。

Codexの場合、初期化スクリプトは管理されたワークフローブロックをリポジトリルートの AGENTS.md に保持します。Codexはまた AGENTS.override.md および設定されたフォールバックガイドファイル名をサポートします。コードに近いネストされたファイルが優先され、このスキルは意図的にそれらを上書きしません。 init が実行中のCodexセッション中に AGENTS.md を作成または書き換えた場合、更新された指示に依存する前に新しいCodexセッションを開始してください。Codexはプロジェクトドキュメントのガイダンスをセッション開始時にスナップショットします。

Claude Codeの場合、初期化スクリプトは管理されたワークフローブロックをリポジトリルートの CLAUDE.md に保持します。Claude Codeはまた .claude/CLAUDE.md、.claude/rules/*.md、および CLAUDE.local.md をサポートしますが、このスキルはルートの CLAUDE.md を主要なプロジェクトガイドとして扱います。なぜならClaudeがそれを直接表示するからです。

Claude Codeで、init が現在のセッション中に .claude/agents/* を書き込んだか更新した場合でも、それらの更新されたエージェントがセッション途中で既に利用可能であると想定しないでください。

init を直列的な前提条件として扱います。freeze、build、evidence、verify、fix、validate、status、または子エージェントの生成と決して重複させないでください。

大規模タスクのデフォルトワークフロー

大規模なタスクの場合、ユーザーへのリクエストをシンプルに保ちます。Codexでは、ユーザーが明示的に委任または並列エージェント作業を要求しない限り、直列的に続行します。その承認後、現在のプロダクトサーフェスが委任をサポートし、タスクの形状がそれを正当化する場合、スキルは内部の子エージェント設定を自動的に選択できます。

推奨される委任シーケンス

1. 必要に応じて init <TASK_ID> を実行します。完了を待ち、続行する前に .agent/tasks/<TASK_ID>/spec.md とリポジトリローカルタスク構造が存在することを確認します。
2. init が完了した後でのみ、正確に1つの仕様凍結サブエージェントを生成し、その完了を待ちます。
3. 正確に1つのビルダーサブエージェントを生成し、実装させます。
4. 同じビルダーセッションを証拠パッケージングに使用します。
5. 正確に1つの新しい検証サブエージェントを生成し、その完了を待ちます。
6. 判定結果が PASS でない場合、正確に1つの修正サブエージェントを生成します。
7. 再度1つの新しい検証サブエージェントを生成します。
8. 検証が PASS を返すか、ユーザーがループを停止するまで、ステップ6〜7を繰り返します。

Codexアダプティブファンアウト

これは、ユーザーが明示的にCodex委任を承認し、タスクが制限付きの並列作業の恩恵を受けられるほど広範囲である場合にのみ使用してください。狭いタスクには上記のシンプルな直列シーケンスを使用します。

適したケース：

• 仕様が安定する前に、複数の独立したコードベースの質問に答える必要がある。
• 実装を互いに素な書き込みスコープに分割できる。
• 証明のために、異なるサーフェスにわたる複数の独立した読み取り専用チェックが必要。

Codexパターン：

1. init は直列のままです。
2. タスクがまだあいまいな場合、最大3つの組み込み explorer 子エージェントを並列にファンアウトします。それぞれに単一の質問、サブシステム、またはパススコープを与えます。それらを待ち、その後仕様を凍結します。
3. 1つの仕様凍結子エージェントを生成し、その完了を待ちます。
4. 1つの task-builder 子エージェントを統合オーナーとして生成します。
5. 実装がきれいに分割される場合、親は制限付きの組み込み worker 子エージェントを並列に生成することもできます。各ワーカーは明示的なファイルまたはモジュールの所有権を持ち、evidence.md、evidence.json、verdict.json、または problems.md を書き込んではなりません。
6. send_input または同等のフォローアップサーフェスを使用して、統合ビルダーを証拠パッケージングのために存続させます。ビルダーは証拠バンドルの単一オーナーのままです。
7. 追加の証明が必要な場合、親は小さな制限付きセットの読み取り専用 explorer 子エージェントを並列にファンアウトして、互いに素なチェックを再実行したり、別の証明ギャップを調査したりできます。これらの子エージェントはコマンド、出力、および調査結果を報告できますが、verdict.json を書き込んではなりません。
8. 各検証パスごとに正確に1つの新しい検証子エージェントを実行します。

プラットフォームの動作

• Codexでは、init 後は通常のパスを直列かつauto-mode-firstに保ちます。委任の内部を、それが作業に実質的に影響を与えない限り表面化しないでください。
• Codexでは、ユーザーが明示的にサブエージェント、委任、または並列エージェント作業を要求した場合にのみ、制限付きのサブエージェントを生成します。
• Codexでは、一度委任が承認されると、スキルは適切な子エージェントの役割と、一度に1つの子エージェントとするか制限付きファンアウトとするかを選択できます。ユーザーが特定の子エージェントの役割やスラッシュコマンドを指定する必要はありません。
• Codexでは、子エージェントの生成は依然として明示的な親オーケストレーターのアクションです。現在のCodexサーフェスが委任をブロックする場合、それが作業に実質的に影響を与える場合にのみ簡潔に述べ、その後直列的に続行します。
• Codexでは、タスクツリーを浅く保ちます。親セッションは、研究、ビルダー、修正、検証の子エージェントを直接生成し、1つのカスタムタスク子エージェントにさらに子エージェントをオーケストレートさせることは避けるべきです。
• Codexでは、委任が承認されたら、凍結された仕様、リポジトリの形状、および現在の委任サーフェスに基づいて、一度に1つの子エージェント委任と制限付きファンアウトの間で選択します。どちらの場合も、init、証拠の所有権、および各検証パスを直列化したままにします。
• Codexでは、ヘルパー・ファンアウトを控えめかつウェーブベースに保ちます。一度に最大3つの並列ヘルパー子エージェントを優先し、そのウェーブが終了するのを待ってから次のフェーズを決定します。
• Codexでは、組み込みの explorer が読み取り専用のリポジトリ探索と証明プローブの最初の選択肢です。組み込みの worker は、明示的な所有権を割り当てることができる場合の、互いに素な実装またはチェックの再実行に適しています。
• Codexでは、ライブのビルダー子エージェントを証拠パッケージングに再利用するために、フォローアップ指示を送信します。検証パスは新しい子エージェントまたは新しいセッションを使用する必要があります。以前の検証を再開することで検証の新しさを満たさないでください。ビルダーと修正の子エージェントは、意図的にそのコンテキストを戻したい場合に再利用または再開できます。
• Codexでは、子エージェントを再利用または再開する前に、現在の子スレッドリストを検査します。Codex CLIで /agent を使用するか、現在のCodexプロダクトサーフェスで利用可能な同等の子スレッドインベントリサーフェスを使用します。
• Codexでは、update_plan からの計画/ToDoチェックリストUIはオプションのセッションガイダンスのみです。ライブ進捗表示には便利ですが、このワークフローの真実のソースではありません。
• Claude Codeでは、スキルはメインスレッドに留まるか、init 後にメインのClaudeセッションに現在のフェーズを適切な組み込みまたはプロジェクトサブエージェントに自動委任させるかを決定する必要があります。ユーザーが特定のClaudeサブエージェントまたは委任モードを個別に要求する必要はありません。
• Claude Codeでは、TodoWriteまたは可視のタスク/ToDo UIはオプションのセッションスコープの進捗表示のみです。現在のセッションでのライブ追跡に役立ちますが、このワークフローの真実のソースではありません。
• Claude Codeでは、.claude/agents/ からインストールされたプロジェクトサブエージェントを優先し、その説明を一致するプルーフループフェーズのプロアクティブなトリガー条件として記述します。Claudeのメインセッションは、タスクリクエスト、サブエージェントの説明、および現在のコンテキストによってルーティングされるため、各フェーズのプロンプトを自然言語で明確に保ちます。デフォルトで証拠ステップに同じビルダー子エージェントを再利用します。元のビルダーセッションが利用できないか、意図的に破棄した場合にのみ、新しいビルダーを証拠のみモードで実行します。init が現在のClaudeセッション中に .claude/agents/* を更新した場合、更新されたエージェントがすぐに利用可能であると想定せず、メインスレッドまたは既に表示されているエージェントにフォールバックします。
• Claude Codeでは、オーケストレーションをフラットに保ちます。メインセッションの自動委任は許容されますが、プルーフループワークフローエージェント自体はリーフロールです。親セッションは、1つのカスタムタスクエージェントに別のエージェントを生成させる代わりに、プルーフループのフェーズ遷移を所有する必要があります。
• Claude Codeでは、正規の永続状態は常に .agent/tasks/<TASK_ID>/ 配下のリポジトリローカルアーティファクトセット、特に spec.md、evidence.md、evidence.json、verdict.json、および problems.md です。
• サブエージェントが利用できない場合、現在のセッション内の別々のセッションまたは明確なモード変更にわたって、同じ役割の分離を維持します。

references/COMMANDS.md の正確な役割プロンプトを使用します。

仕様凍結の要件

spec.md には少なくとも以下を含める必要があります：

• 元のタスクステートメント
• AC1、AC2、... とラベル付けされた明示的な合格基準
• 制約
• 非目標

以下を含めることもできます：

• リポジトリガイダンスソース
• 検証計画
• ユーザーリクエストから狭く解決された前提条件

仕様凍結中はプロダクションコードを編集しないでください。

証拠パッケージングの要件

evidence.md と evidence.json は、各合格基準を独立して以下のいずれかで判定する必要があります：

• PASS
• FAIL
• UNKNOWN

証拠パッケージングは不足しているチェックを実行することもありますが、プロダクションコードを変更し続けてはなりません。

すべての PASS は、以下のような具体的な証拠を引用する必要があります：

• ファイルパス
• 実行されたコマンド
• 終了コード
• 出力の要約
• raw/ 配下のアーティファクトパス

すべての合格基準が PASS でない限り、証拠バンドルで全体的な PASS を主張してはなりません。

新鮮な検証の要件

検証は、新しいセッションまたは新しいサブエージェントである必要があります。 Codexでは、以前の検証子エージェントを再開することでこの要件を満たさないでください。

検証は、ビルダーの説明ではなく、現在のリポジトリ状態と現在の再実行結果を判定する必要があります。

検証は以下を書き込みます：

• .agent/tasks/<TASK_ID>/verdict.json
• 全体的な判定結果が PASS でない場合のみ .agent/tasks/<TASK_ID>/problems.md

problems.md には、PASS でない各基準について以下を含める必要があります：

• 基準のIDとテキスト
• ステータス
• 証明されていない理由
• 最小限の再現手順
• 期待値と実際の値
• 影響を受けるファイル
• 最も小さな安全な修正
• 1〜3文での修正ヒント

検証はプロダクションコードを変更したり、証拠バンドルをバックフィルしたりしてはなりません。

修正の要件

修正は以下のみを読み取ります：

• spec.md
• verdict.json
• problems.md

修正は以下を実行する必要があります：

• 編集前にコードベース内でリストされた各問題を再確認する
• 最も小さな安全な変更セットを行う
• 既に合格している基準を後退させない
• evidence.md、evidence.json、および生のアーティファクトを再生成する
• 最終的な署名オフを書かずに停止する

検証

ワークフローが正しく初期化されたこと、またはアーティファクトセットが完了していることを主張する前に、以下を実行します：

scripts/task_loop.py validate --task-id <TASK_ID>

init が完全に終了した後にのみ validate を実行します。初期化が進行中であると報告された場合は、待ってから再実行し、その結果を安定したタスク失敗として扱わないでください。

クイックサマリーの場合：

scripts/task_loop.py status --task-id <TASK_ID>

init が完全に終了した後にのみ status を実行します。init_in_progress: true と報告された場合は、後で再試行する条件として扱います。

ガードレール

• .agent/tasks/<TASK_ID>/ をリポジトリ内に保持します。
• Codexのtodo/チェックリストUIを一時的な進捗のみとして扱います。永続的な状態は...