taskmaster

Taskmaster — v5 タスクプロトコル

目的

Taskmaster は、複数ステップにわたる Codex 作業のデフォルト実行プロトコルです。v5 では既存の Debug-First コアを維持しながら、スキルを次の 3 つのタスク形式に拡張します。

• 単一タスク — 成果物 1 つ、共有コンテキスト 1 つ
• エピックタスク — 依存関係のある複数の子タスク
• バッチタスク — spawn_agents_on_csv を通じて実行する、同質な行単位の作業

コア原則

1. ディスク上の最新の真実を示す成果物を、メモリより優先します。
2. 明示的な検証なしに、ステップ、サブタスク、バッチ行を DONE にしてはいけません。
3. 詳細な推論はチャットではなく、PROGRESS.md、EPIC.md、またはバッチ出力ファイルに記録します。
4. 失敗を見える状態に保ちます。手動実行や逐次実行へ、黙って切り替えてはいけません。
5. 計画用 CSV とバッチワーカー用 CSV は分けて管理します。
6. Codex のみで復旧できるようにします。コールドリスタート後も、ファイルだけで再開できなければなりません。

形式ルーター

形式	使用する場面	真実を示す成果物	例
単一タスク	共有コンテキストで成果物を 1 つ作る場合	TODO.csv または SPEC.md + TODO.csv + PROGRESS.md	OAuth リダイレクトのバグを 1 件修正する
エピックタスク	複数の成果物、モジュール、依存関係チェーンがある場合	EPIC.md + SUBTASKS.csv + PROGRESS.md	API、UI、ドキュメントにわたる請求ダッシュボードをリリースする
バッチタスク	独立した各行に同じ指示テンプレートを適用する場合	TODO.csv + batch/BATCH.md + workers-input.csv + workers-output.csv	80 個の Markdown ファイルの frontmatter を監査する

ルーターのルール

• ユーザーが成果物を 1 つ求めており、進捗を 1 つの共有コンテキスト内に保てる場合は、単一タスクから始めます。
• 1 つの TODO.csv にフェーズ、サブプロジェクト、または独立した成果物が含まれるようになったら、エピックタスクに切り替えます。
• バッチタスクを使うのは、各行が独立していて、1 つの指示テンプレートを共有し、成功を構造化出力フィールドで表現できる場合に限ります。
• エピックタスクには、single-compact、single-full、または batch の子タスクを含められます。
• バッチタスクを、異種の役割、行をまたぐ依存関係、または共有書き込み範囲がある場合に使ってはいけません。

単一タスク

単一タスクでは、2 つの実行プロファイルをサポートすることで、従来の LITE/FULL の動作との後方互換性を維持します。

コンパクト単一タスク

短く直線的で、復旧ログやキャッシュされた調査成果物を必要としないタスクには、コンパクト単一タスクを使います。

• ファイル：プロジェクトルートの TODO.csv のみ
• テンプレート：compact_todo_template.csv
• ステータスセット：TODO | IN_PROGRESS | DONE
• 最適な用途：短いドキュメント編集、小規模な整理、簡単な名前変更タスク

コンパクト単一タスクの例：

id,task,status,completed_at,notes
1,Locate root cause,IN_PROGRESS,,
2,Implement fix,TODO,,
3,Run verification,TODO,,

フル単一タスク

すべてのコード変更、長時間かかるタスク、またはコンテキストのリセット後も継続する必要がある作業には、フル単一タスクを使います。これは単一タスクのデフォルトの方法です。

• ファイル：.codex-tasks/<task-name>/SPEC.md、TODO.csv、PROGRESS.md、raw/
• テンプレート：
  • SPEC_TEMPLATE.md
  • PROGRESS_TEMPLATE.md
  • todo_template.csv
  • perf_todo_template.csv
• ステータスセット：TODO | IN_PROGRESS | DONE | FAILED
• 最適な用途：コード実装、バグ修正、リファクタリング、数時間にわたる作業

フル単一タスクのディレクトリ例：

.codex-tasks/20260313-auth-fix/
├── SPEC.md
├── TODO.csv
├── PROGRESS.md
└── raw/

単一タスクのルール

• 新しいステップを始める前に、作業中の TODO.csv を読み直します。
• TODO.csv はリーフレベルのタスクのみを記載します。フェーズ、子プロジェクト、バッチ行を保存してはいけません。
• 検証を自動化できない場合に限り echo SKIP を使い、その理由を記録します。
• 再試行が 5 回に達した場合は、明示的に戦略を変更するか、タスク形式を切り替えます。

Epic タスク

Epic タスクは、複数の成果物や依存関係の連鎖にまたがる大規模な作業を調整するための親タスクの形式です。

• ファイル：
  • .codex-tasks/<epic-name>/EPIC.md
  • .codex-tasks/<epic-name>/SUBTASKS.csv
  • .codex-tasks/<epic-name>/PROGRESS.md
  • .codex-tasks/<epic-name>/tasks/<child-task>/...
• テンプレート：
  • EPIC_TEMPLATE.md
  • subtasks_template.csv
• ステータス：TODO | IN_PROGRESS | DONE | FAILED
• 最適な用途：複数モジュールにまたがる機能、段階的なリファクタリング、明確な子タスクの成果物がある長期プロジェクト

Epic ディレクトリの例：

.codex-tasks/20260313-billing-epic/
├── EPIC.md
├── SUBTASKS.csv
├── PROGRESS.md
└── tasks/
    ├── 20260313-api/
    ├── 20260313-frontend/
    └── 20260313-docs/

Epic のワークフロー：

1. EPIC.md で全体目標と成果物の範囲を定義します。
2. SUBTASKS.csv に子タスクを登録し、task_type、依存関係、task_dir を指定します。
   • depends_on：複数の依存関係 ID を列挙するには ; を使用します（例：1;2）。空欄の場合、依存関係はありません。
3. 各子タスクを、それぞれ独自の Single または Batch プロトコルで実行します。
4. 子タスクの検証結果を SUBTASKS.csv と親の PROGRESS.md に反映します。
5. すべての子タスクの行が DONE になり、最終検証に合格した場合にのみ Epic を完了します。

1 つのタスクファイルが実行計画ではなくプロジェクト管理のようになり始めたら、単一の TODO.csv ではなく Epic を使用してください。

Batch タスク

Batch タスクは、spawn_agents_on_csv を通じて実行する、一貫性のある行単位の作業向けです。単独のタスクとしても、Epic 内の子タスクとしても使用できます。

• ファイル：
  • .codex-tasks/<task-name>/SPEC.md
  • .codex-tasks/<task-name>/TODO.csv（大まかな手順を3～5個記載）
  • .codex-tasks/<task-name>/PROGRESS.md
  • .codex-tasks/<task-name>/batch/BATCH.md
  • .codex-tasks/<task-name>/batch/workers-input.csv
  • .codex-tasks/<task-name>/batch/workers-output.csv
  • .codex-tasks/<task-name>/raw/
• テンプレート：
  • BATCH_TEMPLATE.md
  • workers_input_template.csv
  • workers_output_template.csv
• 最適な用途：大量のファイル監査、大量のメタデータ更新、行ごとの構造化分析

Batch ディレクトリの例：

.codex-tasks/20260313-doc-audit/
├── SPEC.md
├── TODO.csv
├── PROGRESS.md
├── batch/
│   ├── BATCH.md
│   ├── workers-input.csv
│   └── workers-output.csv
└── raw/

Batch の適格性チェックリスト

以下のすべてに当てはまる場合にのみ、Batch タスクを使用してください。

• 1つの指示テンプレートですべての行を記述できる。
• 各行は独立しており、個別に再試行できる。
• 出力を output_schema の構造化フィールドで表現できる。
• 書き込み対象が重複しない、または Batch が読み取り専用である。

Batch のライフサイクル

1. 親の TODO.csv から、真に行単位で一貫性のある手順を特定します。
2. batch/BATCH.md を作成し、以下を定義します。
   • 指示テンプレート
   • id_column
   • output_schema
   • max_workers
   • max_runtime_seconds
   • output_csv_path
3. 計画手順ではなく、実際の成果物から workers-input.csv を作成します。
4. id_column、output_schema、max_workers、max_runtime_seconds、output_csv_path を明示して、spawn_agents_on_csv を実行します。
5. workers-output.csv を確認します。失敗した行はそのまま残し、フィルタリングした入力 CSV を使って再試行できます。
6. 集約結果を親の PROGRESS.md に反映し、その後でのみ親の手順を DONE にします。

Batch 手順の例：

id,task,status,acceptance_criteria,validation_command,completed_at,retry_count,notes
1,Build workers-input.csv,IN_PROGRESS,batch/workers-input.csv exists,test -f batch/workers-input.csv,,0,
2,Run spawn_agents_on_csv,TODO,batch/workers-output.csv exists,test -f batch/workers-output.csv,,0,
3,Merge row results,TODO,Failed rows are handled and summary is written,test -f PROGRESS.md,,0,

混合形式

• 1つの実行ストリームに一貫性がなくなった場合、Single タスクを Epic に昇格できます。
• Single または Epic の子タスクの手順から、一貫性のある作業を Batch に委任できます。
• 現在のレイヤーの正となるファイルのみを使用します。
  • 手順の計画には TODO.csv
  • 子タスクの状態には SUBTASKS.csv
  • 行ごとの結果には workers-output.csv

タスク途中での形式昇格

複雑さが現在の形式で対応しきれなくなった場合、その場で昇格します。

Single → Epic

1. 既存の SPEC.md の目標をもとに、.codex-tasks/<task-name>/EPIC.md を作成します。
2. 残りの TODO.csv の行を SUBTASKS.csv の子タスク項目に変換します。
3. 元の SPEC.md、TODO.csv、PROGRESS.md を最初の子タスクとして tasks/<original-task>/ に移動します。
4. 追加の成果物用に新しい子タスクディレクトリを作成します。
5. 昇格した理由を親の PROGRESS.md に記録します。

単一／エピックのステップ → バッチ

1. TODO.csv または SUBTASKS.csv の行を確認し、実際には同質の N 個の項目である行を特定します。
2. その行を、「入力を作成 → ワーカーを実行 → 結果を統合」という3ステップのバッチシーケンスに置き換えます。
3. BATCH.md と workers-input.csv を含む batch/ ディレクトリを作成します。
4. バッチの統合が完了するまで、親ステップは IN_PROGRESS のままにします。
5. 委任内容を PROGRESS.md に記録します。

検証ルール

• 新しいステップを開始する前に、アクティブな正本ファイルを読み直します。
• 子サブタスクまたはバッチの行が統合基準を満たしていない場合、親タスクは成功を宣言できません。
• 再試行回数を明示します。
• Full、Epic、Batch の各形式では、取得した生データを raw/ に保持します。
• 作業が異種の場合は、無理に Batch にせず、専用のマルチエージェントフローを使用します。

コンテキスト復元プロトコル

状態を完全に復元できる最小限の成果物セットを使用します。

• コンパクトな単一タスク：TODO.csv を読み、最初の DONE 以外の行から再開します。
• 完全な単一タスク：SPEC.md、TODO.csv、次に PROGRESS.md の復旧ブロックを読みます。
• エピックタスク：EPIC.md、SUBTASKS.csv、親の PROGRESS.md、次に現在の子タスクディレクトリを読みます。
• バッチタスク：SPEC.md、TODO.csv、batch/BATCH.md、batch/workers-output.csv、次に PROGRESS.md の復旧ブロックを読みます。

すべての復旧メッセージには、次の項目を含める必要があります。

1. 任务: 目標
2. 形态: single-compact | single-full | epic | batch
3. 进度: X/Y
4. 当前: 現在のステップ、子タスク、または失敗した行のセット
5. 文件: アクティブな正本成果物のパス
6. 下一步: 次に行う具体的なアクション

出力要件

すべてのステータス更新には、次の項目を含める必要があります。

1. 任务: 1行で示す目標
2. 形态: 現在のタスク形式
3. 进度: 完了したステップまたは行の数（X/Y）
4. 当前: アクティブなステップ、子タスク、またはバッチ段階
5. 验证: 最新の検証コマンドと結果
6. 文件: アクティブなタスクディレクトリまたは正本成果物

参照資料

• SPEC_TEMPLATE.md
• PROGRESS_TEMPLATE.md
• todo_template.csv
• perf_todo_template.csv
• compact_todo_template.csv
• EPIC_TEMPLATE.md
• BATCH_TEMPLATE.md
• subtasks_template.csv
• workers_input_template.csv
• workers_output_template.csv
• EXAMPLES.md