taskmaster

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Taskmaster — v5 Task Protocol

Taskmaster — v5 任务协议

Purpose

设计目的

Taskmaster is the default execution protocol for multi-step Codex work. v5 keeps the existing Debug-First core while expanding the skill into three task shapes:

Single Task — one deliverable, one shared context
Epic Task — multiple child tasks with dependencies
Batch Task — homogeneous row-level work executed through
```
spawn_agents_on_csv
```

Taskmaster是多步骤Codex工作的默认执行协议。v5保留了现有调试优先的核心能力，同时将支持的任务形态扩展为三类：

单任务：一个交付物，一个共享上下文
史诗任务：带依赖关系的多个子任务
批量任务：通过
```
spawn_agents_on_csv
```
执行的同构行级工作

Core Principles

核心原则

The current truth artifact on disk wins over memory.
No step, subtask, or batch row becomes
```
DONE
```
without explicit validation.
Keep verbose reasoning in
```
PROGRESS.md
```
,
```
EPIC.md
```
, or batch output files, not in the chat.
Keep failures visible. Do not silently downgrade to manual or serial execution.
Keep planning CSVs and batch worker CSVs separate.
Build for Codex-only recovery: a cold restart must be resumable from files alone.

磁盘上的当前真值工件优先级高于内存。
任何步骤、子任务或批量行没有经过明确校验都不能标记为
```
DONE
```
。
详细推理过程记录在
```
PROGRESS.md
```
、
```
EPIC.md
```
或批量输出文件中，不要放在对话里。
故障要公开可见，不要静默降级为手动或串行执行。
规划CSV和批量工作CSV要分开存储。
支持纯Codex恢复：冷重启必须仅通过文件就能恢复执行。

Shape Router

形态路由

Shape	Use when	Truth artifacts	Example
Single Task	One deliverable with shared context	`TODO.csv` or `SPEC.md + TODO.csv + PROGRESS.md`	Fix one OAuth redirect bug
Epic Task	Multiple deliverables, modules, or dependency chains	`EPIC.md + SUBTASKS.csv + PROGRESS.md`	Ship billing dashboard across API, UI, docs
Batch Task	Same instruction template across independent rows	`TODO.csv + batch/BATCH.md + workers-input.csv + workers-output.csv`	Audit 80 Markdown files for frontmatter

形态	适用场景	真值工件	示例
单任务	一个交付物，共享上下文	`TODO.csv` 或 `SPEC.md + TODO.csv + PROGRESS.md`	修复一个OAuth重定向bug
史诗任务	多个交付物、模块或依赖链	`EPIC.md + SUBTASKS.csv + PROGRESS.md`	跨API、UI、文档上线计费仪表盘
批量任务	独立行使用相同的指令模板	`TODO.csv + batch/BATCH.md + workers-input.csv + workers-output.csv`	审计80个Markdown文件的前言元数据

Router Rules

路由规则

Start with Single Task when the user wants one deliverable and progress can stay in one shared context.
Promote to Epic Task when one
```
TODO.csv
```
starts carrying phases, subprojects, or independent deliverables.
Use Batch Task only when rows are independent, share one instruction template, and success can be expressed in structured output fields.
An Epic Task can contain
```
single-compact
```
,
```
single-full
```
, or
```
batch
```
child tasks.
A Batch Task must not be used for heterogeneous roles, cross-row dependencies, or shared write scopes.

当用户只需要一个交付物，进度可以在一个共享上下文中维护时，优先使用单任务。
当一个
```
TODO.csv
```
开始包含阶段、子项目或独立交付物时，升级为史诗任务。
仅当行之间相互独立、共享同一个指令模板、执行结果可以用结构化输出字段表达时，才使用批量任务。
史诗任务可以包含
```
single-compact
```
、
```
single-full
```
或
```
batch
```
类型的子任务。
批量任务不能用于异构角色、跨行依赖或共享写入范围的场景。

Single Task

单任务

Single Task preserves backward compatibility with the old LITE/FULL behavior by supporting two execution profiles.

单任务支持两种执行配置，保留了与旧版LITE/FULL行为的向后兼容性。

Compact Single

精简单任务

Use Compact Single when the task is short, linear, and does not need recovery logs or cached research artifacts.

Files: project-root
```
TODO.csv
```
only
Template: compact_todo_template.csv
Status set:
```
TODO | IN_PROGRESS | DONE
```
Best for: short documentation edits, tiny cleanup passes, quick rename tasks

Compact Single example:

csv

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

当任务简短、线性，不需要恢复日志或缓存调研工件时使用精简单任务。

文件：仅项目根目录的
```
TODO.csv
```
模板：compact_todo_template.csv
状态集：
```
TODO | IN_PROGRESS | DONE
```
适用场景：简短文档编辑、小型清理工作、快速重命名任务

精简单任务示例：

csv

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

Full Single

完整单任务

Use Full Single for all code changes, long-running tasks, or any work that must survive a context reset. This is the default single-task path.

Files:

.codex-tasks/<task-name>/SPEC.md

TODO.csv

PROGRESS.md

raw/

Templates:
- SPEC_TEMPLATE.md
- PROGRESS_TEMPLATE.md
- todo_template.csv
- perf_todo_template.csv
Status set:
```
TODO | IN_PROGRESS | DONE | FAILED
```
Best for: code implementation, bug fixes, refactors, multi-hour work

Full Single directory example:

text

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

所有代码变更、长时运行任务或任何需要在上下文重置后仍可恢复的工作都使用完整单任务，这是单任务的默认路径。

文件：

.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
```
适用场景：代码实现、bug修复、重构、数小时级别的长时工作

完整单任务目录示例：

text

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

Single Task Rules

单任务规则

Re-read the active
```
TODO.csv
```
before every new step.
Keep
```
TODO.csv
```
leaf-level only. Do not store phases, child projects, or batch rows there.
Use
```
echo SKIP
```
only when validation cannot be automated, and record why.
If retries hit 5, change strategy explicitly or promote the task shape.

每执行新步骤前都要重新读取当前的
```
TODO.csv
```
。
```
TODO.csv
```
仅存储叶子节点任务，不要存储阶段、子项目或批量行。
仅当校验无法自动化时使用
```
echo SKIP
```
，并记录原因。
如果重试次数达到5次，明确调整策略或升级任务形态。

Epic Task

史诗任务

Epic Task is the parent coordination shape for large work that spans multiple deliverables or dependency chains.

Files:

```
.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>/...

Templates:
- EPIC_TEMPLATE.md
- subtasks_template.csv
Status set:
```
TODO | IN_PROGRESS | DONE | FAILED
```
Best for: multi-module features, staged refactors, long projects with clear child deliverables

Epic directory example:

text

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

Epic workflow:

Define the global goal and delivery boundary in
```
EPIC.md
```
.
Register child tasks in
```
SUBTASKS.csv
```
with
```
task_type
```
, dependencies, and
```
task_dir
```
.
- ```
depends_on
```
  : use
```
;
```
  to list multiple dependency IDs (e.g.,
```
1;2
```
  ). Empty means no dependency.
Execute each child task with its own Single or Batch protocol.
Bubble child validation back to
```
SUBTASKS.csv
```
and parent
```
PROGRESS.md
```
.
Close the Epic only when all child rows are
```
DONE
```
and the final validation passes.

Use Epic instead of a single

TODO.csv

when one task file starts reading like project management instead of execution.

史诗任务是跨越多个交付物或依赖链的大型工作的父级协调形态。

文件：

```
.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
```
适用场景：多模块功能、分阶段重构、有明确子交付物的长期项目

史诗目录示例：

text

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

史诗工作流：

在
```
EPIC.md
```
中定义全局目标和交付边界。
在
```
SUBTASKS.csv
```
中注册子任务，包含
```
task_type
```
、依赖关系和
```
task_dir
```
。
- ```
depends_on
```
  ：使用
```
;
```
  列出多个依赖ID（例如
```
1;2
```
  ），为空表示无依赖。
每个子任务使用各自的单任务或批量协议执行。
子任务的校验结果同步回
```
SUBTASKS.csv
```
和父级
```
PROGRESS.md
```
。
仅当所有子任务行都标记为
```
DONE
```
且最终校验通过时，关闭史诗任务。

当单个

TODO.csv

的内容更偏向项目管理而非执行记录时，使用史诗任务替代单任务。

Batch Task

批量任务

Batch Task is for homogeneous row-level work that should be executed through

spawn_agents_on_csv

. It can be a standalone task or a child inside an Epic.

Files:

```
.codex-tasks/<task-name>/SPEC.md
```
```
.codex-tasks/<task-name>/TODO.csv
```
for 3-5 high-level steps
```
.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/
```

Templates:
- BATCH_TEMPLATE.md
- workers_input_template.csv
- workers_output_template.csv
Best for: bulk file audits, bulk metadata updates, structured per-row analysis

Batch directory example:

text

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

批量任务适用于需要通过

spawn_agents_on_csv

执行的同构行级工作，可以是独立任务，也可以是史诗任务的子任务。

文件：

```
.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
适用场景：批量文件审计、批量元数据更新、结构化逐行分析

批量目录示例：

text

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

Batch Eligibility Checklist

批量任务适用检查清单

Only use Batch Task when all of the following are true:

One instruction template can describe every row.
Rows are independent and can be retried independently.
Output can be expressed as structured fields in
```
output_schema
```
.
Writes are disjoint, or the batch is read-only.

仅当满足以下所有条件时才使用批量任务：

同一个指令模板可以描述所有行的执行要求。
行之间相互独立，可以单独重试。
输出可以通过
```
output_schema
```
定义的结构化字段表达。
写入范围不重叠，或者批量任务是只读的。

Batch Lifecycle

批量任务生命周期

Identify a parent
```
TODO.csv
```
step that is truly row-level and homogeneous.

Create

batch/BATCH.md

and define:

instruction template
```
id_column
```
```
output_schema
```
```
max_workers
```
```
max_runtime_seconds
```
```
output_csv_path
```

Build
```
workers-input.csv
```
from real artifacts, not from plan steps.

Run

spawn_agents_on_csv

with explicit

id_column

output_schema

max_workers

max_runtime_seconds

, and

output_csv_path

Inspect
```
workers-output.csv
```
. Failed rows remain visible and may be retried with a filtered input CSV.
Merge the aggregate result into parent
```
PROGRESS.md
```
and only then mark the parent step
```
DONE
```
.

Example Batch step sequence:

csv

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,

识别父级
```
TODO.csv
```
中属于纯行级同构工作的步骤。

创建

batch/BATCH.md

并定义：

指令模板
```
id_column
```
```
output_schema
```
```
max_workers
```
```
max_runtime_seconds
```
```
output_csv_path
```

基于真实工件构建
```
workers-input.csv
```
，不要基于规划步骤生成。

运行

spawn_agents_on_csv

，传入明确的

id_column

、

output_schema

、

max_workers

、

max_runtime_seconds

和

output_csv_path

参数。

检查
```
workers-output.csv
```
，失败的行保持可见，可以通过过滤后的输入CSV重试。
将聚合结果合并到父级
```
PROGRESS.md
```
中，之后才能将父级步骤标记为
```
DONE
```
。

批量任务步骤序列示例：

csv

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,

Mixed Shapes

混合形态

A Single Task can promote to Epic when one execution stream stops being coherent.
A Single or Epic child step can delegate homogeneous work to Batch.
Use the current layer's truth file only:
- ```
TODO.csv
```
  for step planning
- ```
SUBTASKS.csv
```
  for child-task state
- ```
workers-output.csv
```
  for row results

当执行流不再连贯时，单任务可以升级为史诗任务。
单任务或史诗任务的子步骤可以将同构工作委托给批量任务。
仅使用当前层级的真值文件：
- ```
TODO.csv
```
  用于步骤规划
- ```
SUBTASKS.csv
```
  用于子任务状态管理
- ```
workers-output.csv
```
  用于行级结果存储

Mid-Task Shape Promotion

任务中形态升级

When complexity outgrows the current shape, promote in-place:

当复杂度超出当前形态的承载能力时，就地升级：

Single → Epic

单任务 → 史诗任务

Create
```
.codex-tasks/<task-name>/EPIC.md
```
from the existing
```
SPEC.md
```
goal.
Convert remaining
```
TODO.csv
```
rows into child task entries in
```
SUBTASKS.csv
```
.

Move the original

SPEC.md

TODO.csv

PROGRESS.md

into

tasks/<original-task>/

as the first child.

Create new child directories for the additional deliverables.
Log the promotion reason in the parent
```
PROGRESS.md
```
.

基于现有
```
SPEC.md
```
的目标创建
```
.codex-tasks/<task-name>/EPIC.md
```
。
将剩余的
```
TODO.csv
```
行转换为
```
SUBTASKS.csv
```
中的子任务条目。
将原始的
```
SPEC.md
```
、
```
TODO.csv
```
、
```
PROGRESS.md
```
移动到
```
tasks/<original-task>/
```
作为第一个子任务。
为额外的交付物创建新的子任务目录。
在父级
```
PROGRESS.md
```
中记录升级原因。

Single/Epic Step → Batch

单任务/史诗任务步骤 → 批量任务

Identify the
```
TODO.csv
```
or
```
SUBTASKS.csv
```
row that is actually N homogeneous items.
Replace it with a 3-step Batch sequence: build input → run workers → merge results.
Create
```
batch/
```
directory with
```
BATCH.md
```
and
```
workers-input.csv
```
.
The parent step stays
```
IN_PROGRESS
```
until the batch merge completes.
Log the delegation in
```
PROGRESS.md
```
.

识别
```
TODO.csv
```
或
```
SUBTASKS.csv
```
中实际包含N个同构项的行。
将其替换为3步批量序列：构建输入 → 运行工作流 → 合并结果。
创建
```
batch/
```
目录，包含
```
BATCH.md
```
和
```
workers-input.csv
```
。
父级步骤保持
```
IN_PROGRESS
```
状态，直到批量合并完成。
在
```
PROGRESS.md
```
中记录委托操作。

Validation Rules

校验规则

Re-read the active truth file before every new step.
No parent task can claim success while a child subtask or batch row still fails its merge criteria.
Keep retry counts explicit.
Keep raw fetched material under
```
raw/
```
for Full, Epic, and Batch shapes.
If the work is heterogeneous, use a dedicated multi-agent flow instead of forcing it into Batch.

每执行新步骤前重新读取当前的真值文件。
只要子任务或批量行未通过合并标准，父任务就不能标记为成功。
明确记录重试次数。
完整单任务、史诗任务、批量任务的原始抓取材料都存储在
```
raw/
```
目录下。
如果工作是异构的，使用专用的多Agent流程，不要强行适配批量任务。

Context Recovery Protocol

上下文恢复协议

Use the smallest artifact set that fully restores state:

Compact Single: read
```
TODO.csv
```
, resume from the first non-
```
DONE
```
row.
Full Single: read
```
SPEC.md
```
,
```
TODO.csv
```
, then the
```
PROGRESS.md
```
recovery block.
Epic Task: read
```
EPIC.md
```
,
```
SUBTASKS.csv
```
, parent
```
PROGRESS.md
```
, then the current child task directory.

Batch Task: read

SPEC.md

TODO.csv

batch/BATCH.md

batch/workers-output.csv

, then the

PROGRESS.md

recovery block.

Every recovery message must include:

```
任务:
```
goal

形态:

single-compact | single-full | epic | batch

```
进度:
```
X/Y
```
当前:
```
current step, child task, or failed row set
```
文件:
```
active truth artifact path
```
下一步:
```
exact next action

使用可以完全恢复状态的最小工件集：

精简单任务：读取
```
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

的恢复块。

每条恢复消息必须包含：

```
任务:
```
目标

形态:

single-compact | single-full | epic | batch

```
进度:
```
X/Y
```
当前:
```
当前步骤、子任务或失败行集合
```
文件:
```
活跃真值工件路径
```
下一步:
```
明确的后续操作

Output Contract

输出约定

Every status update must include:

```
任务:
```
one-line goal
```
形态:
```
current task shape
```
进度:
```
X/Y steps or rows complete
```
当前:
```
active step, child task, or batch stage
```
验证:
```
latest validation command and result
```
文件:
```
active task directory or truth artifact

每条状态更新必须包含：

```
任务:
```
单行目标描述
```
形态:
```
当前任务形态
```
进度:
```
已完成X/Y个步骤或行
```
当前:
```
活跃步骤、子任务或批量阶段
```
验证:
```
最新校验命令和结果
```
文件:
```
活跃任务目录或真值工件路径

References

参考文档

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

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