taskmaster

Taskmaster — v5 任务协议

目的

Taskmaster 是多步骤 Codex 工作的默认执行协议。v5 保留了现有的 Debug-First 核心，同时将此技能扩展为三种任务形态：

• 单项任务 — 一个交付成果，共享一个上下文
• 史诗任务 — 多个存在依赖关系的子任务
• 批量任务 — 通过 spawn_agents_on_csv 执行同类的逐行工作

核心原则

1. 磁盘上的当前真实记录优先于记忆。
2. 未经明确验证，任何步骤、子任务或批次行都不能标记为 DONE。
3. 详细推理应记录在 PROGRESS.md、EPIC.md 或批次输出文件中，而不是聊天中。
4. 让失败清晰可见。不要悄悄改为手动或串行执行。
5. 规划用 CSV 与批量工作器用 CSV 必须分开。
6. 以仅依靠 Codex 恢复为目标：冷启动后必须能仅凭文件继续工作。

形态路由

形态	适用场景	真实记录	示例
单项任务	一个交付成果，共享上下文	TODO.csv 或 SPEC.md + TODO.csv + PROGRESS.md	修复一个 OAuth 重定向错误
史诗任务	多个交付成果、模块或依赖链	EPIC.md + SUBTASKS.csv + PROGRESS.md	跨 API、UI、文档交付计费仪表板
批量任务	对相互独立的行应用相同的指令模板	TODO.csv + batch/BATCH.md + workers-input.csv + workers-output.csv	审核 80 个 Markdown 文件的 frontmatter

路由规则

• 用户需要一个交付成果，且进度可在一个共享上下文中跟踪时，从单项任务开始。
• 当一个 TODO.csv 开始包含多个阶段、子项目或独立交付成果时，升级为史诗任务。
• 只有在各行相互独立、共用一个指令模板，且成功结果可用结构化输出字段表示时，才使用批量任务。
• 一个史诗任务可包含 single-compact、single-full 或 batch 子任务。
• 批量任务不得用于角色不同、跨行存在依赖关系或写入范围共享的情况。

单项任务

单项任务通过支持两种执行配置，保持与旧版 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。

当单个 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 任务：

• 一份指令模板可以描述每一行。
• 各行相互独立，且可以单独重试。
• 输出可以表示为 output_schema 中的结构化字段。
• 写入内容互不重叠，或该批次为只读。

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,

混合形式

• 当单个执行流不再连贯时，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 中记录升级原因。

单步／Epic 步骤 → 批处理

1. 找出 TODO.csv 或 SUBTASKS.csv 中实际代表 N 个同类项目的行。
2. 将其替换为 3 步批处理序列：构建输入 → 运行工作者 → 合并结果。
3. 创建 batch/ 目录，其中包含 BATCH.md 和 workers-input.csv。
4. 在批处理合并完成前，父步骤保持 IN_PROGRESS。
5. 在 PROGRESS.md 中记录任务委派情况。

验证规则

• 每个新步骤开始前，重新读取当前有效的事实文件。
• 只要子任务或批处理行仍未通过合并标准，父任务就不能宣告成功。
• 明确记录重试次数。
• 对 Full、Epic 和 Batch 形态的任务，将获取的原始材料保存在 raw/ 下。
• 如果工作内容不一致，请使用专用的多 Agent 工作流，而不是强行将其纳入批处理。

上下文恢复协议

使用能够完整恢复状态的最小文件集：

• 精简单项任务：读取 TODO.csv，从第一条非 DONE 行继续。
• 完整单项任务：依次读取 SPEC.md、TODO.csv，然后读取 PROGRESS.md 中的恢复区块。
• Epic 任务：依次读取 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. 任务: 一行目标
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