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>：新たに検証を実行し、必要に応じて problems.md とともに verdict.json を書き込みます
• 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 "User task text"

初期化スクリプトは次の処理を行います。

• リポジトリのルートを特定します
• .agent/tasks/<TASK_ID>/ を作成します
• raw/ 内のプレースホルダーを含む、必要なすべての成果物を作成します
• プロジェクト単位のサブエージェントファイルをインストールします
• AGENTS.md とリポジトリの Claude ガイドファイルにある、管理対象のワークフローブロックを挿入または更新します

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

Claude Code の場合、初期化スクリプトは管理対象のワークフローブロックをリポジトリルートの CLAUDE.md に保持します。Claude Code は .claude/CLAUDE.md、.claude/rules/*.md、CLAUDE.local.md にも対応していますが、このスキルでは、Claude が直接参照するリポジトリルートの CLAUDE.md を主要なプロジェクトガイドとして扱います。

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. 新しい検証担当のサブエージェントをもう一度起動します
8. 検証担当が PASS を返すか、ユーザーがループの停止を指示するまで、手順6～7を繰り返します

Codex の適応型ファンアウト

Codex への委任をユーザーが明示的に承認しており、タスクの範囲が十分に広く、制限付きの並行作業が有効な場合にのみ使用してください。範囲が狭いタスクには、上記のよりシンプルな順次手順を使用してください。

適しているケース：

• 仕様が固まる前に、独立した複数のコードベースに関する質問への回答が必要な場合
• 実装を、互いに重複しない書き込み範囲に分割できる場合
• 複数の異なる箇所で、独立した読み取り専用の確認を行う必要がある場合

Codex のパターン：

1. init は順次実行のままにします。
2. タスクに曖昧さが残っている場合は、組み込みの explorer 子エージェントを最大 3 つ並行して起動します。それぞれに、質問、サブシステム、またはパスの範囲を 1 つだけ割り当てます。子エージェントからの応答を待ってから、仕様を確定します。
3. 仕様を確定する子エージェントを 1 つ起動し、その完了を待ちます。
4. 統合の責任者として task-builder 子エージェントを 1 つ起動します。
5. 実装を明確に分割できる場合、親エージェントは組み込みの worker 子エージェントを、制限を設けて並行して起動してもかまいません。各ワーカーには、担当するファイルまたはモジュールを明示し、evidence.md、evidence.json、verdict.json、problems.md への書き込みを禁止します。
6. send_input または同等のフォローアップ機能を使い、証拠の取りまとめが済むまで統合ビルダーを稼働させておきます。証拠バンドルの責任者は、引き続きビルダー 1 つだけとします。
7. 追加の検証が必要な場合、親エージェントは読み取り専用の explorer 子エージェントを少数に限定して起動し、互いに重複しない確認の再実行や、別々の検証不足箇所の調査を並行して行ってもかまいません。これらの子エージェントは、コマンド、出力、調査結果を報告できますが、verdict.json への書き込みは行いません。
8. 検証パスごとに、必ず新しい検証用子エージェントを 1 つだけ実行します。

プラットフォームの動作

• Codex では、init の後は通常の手順を直列で進め、自動モードを優先してください。作業に実質的な影響がない限り、委任の内部事情は表に出さないでください。
• Codex では、ユーザーがサブエージェント、委任、またはエージェントによる並列作業を明示的に求めた場合に限り、範囲を限定したサブエージェントを起動してください。
• Codex では、委任が許可されたら、スキル側で適切な子エージェントの役割と、1体ずつ進めるか範囲を限定して並列実行するかを選択できます。ユーザーが特定の子エージェントの役割やスラッシュコマンドを指定する必要はありません。
• Codex では、子エージェントの起動は引き続き親オーケストレーターが明示的に行う操作です。現在の Codex の環境で委任がブロックされている場合は、作業に実質的な影響があるときに限り、その旨を簡潔に伝えたうえで、直列で進めてください。
• Codex では、タスクツリーを浅く保ってください。親セッションが調査、構築、修正、検証の子エージェントを直接起動し、カスタムタスク用の子エージェントにさらに子エージェントのオーケストレーションを依頼しないでください。
• 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 のメインセッションは、タスクの依頼、サブエージェントの説明、現在のコンテキストに基づいて振り分けるため、各段階のプロンプトは自然言語で明確にしてください。既定では、証拠の段階でも同じビルダーの子エージェントを再利用してください。元のビルダーセッションが利用できない場合、または意図的に破棄した場合に限り、証拠専用モードで新しいビルダーを起動してください。現在の Claude セッション中に init が .claude/agents/* を更新したばかりの場合は、更新されたエージェントがすぐに利用可能になると想定せず、メインスレッドまたはすでに表示されているエージェントを使用してください。
• Claude Code では、オーケストレーションをフラットに保ってください。メインセッションによる自動委任は問題ありませんが、証明ループのワークフローエージェント自体は、下位の役割としてください。カスタムタスク用のエージェントに別のエージェントを起動させるのではなく、親セッションが証明ループの段階間の移行を管理してください。
• 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
• .agent/tasks/<TASK_ID>/problems.md（総合判定が PASS でない場合のみ）

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>

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

簡単なサマリーについては、次を実行してください。

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

status は、安定したタスク状態が必要な場合、init が完全に終了した後のみ実行してください。init_in_progress: true と報告された場合は、後で再試行する条件として扱ってください。

ガードレール

• .agent/tasks/<TASK_ID>/ をリポジトリ内に保つ
• Codex の todo/チェックリスト UI は一時的な進捗のみとして扱う。永続的なワークフロー状態は .agent/tasks/<TASK_ID>/ に存在する
• すべての受け入れ基準が PASS でない限り、タスク完了を主張しない
• 評価者と修正者の役割を分離する
• Codex のファンアウトは浅く、かつ境界を設けて保つ。並列ヘルパーは証明ループに情報を提供してもよいが、エビデンスは依然として 1 人のビルダーが所有し、判定は依然として 1 人の新鮮な検証者が所有する
• 検証者を新鮮に保つ
• 修正時は、防御可能な最小の差分を優先する
• AGENTS.md およびリポジトリが選択した Claude ガイドファイル内の管理対象ブロックの外側にある、既存のユーザーガイダンスを保持する