todo-doc-executor

name	todo-doc-executor
description	按顺序执行用户指定的 TODO、检查清单、路线图或计划文档，把条目转化为真实完成的工作，并用诚实的进度跟踪和验证证明结果。当 Codex 被要求跟随 TODO.md 文件、逐项完成任务列表、尽可能诚实地完成清单条目，或避免走捷径、虚假完成、跳过验证、乱序执行时使用。

执行 TODO 文档

当用户指向 TODO 风格文档，并希望实际执行而不是总结时，遵循此工作流。

语言要求

• 默认用中文进行任务分析、计划、进度更新和最终回答。
• 内部执行记录、阻塞说明和完成证据也优先使用中文表述。
• 代码、命令、文件路径、测试输出、错误信息、API 名称和原文引用保持原文。
• 如果用户明确要求其他语言，则按用户要求回答。

读取正确输入

• 首先读取用户指定的 TODO 文档。
• 编辑任何文件前，读取附近的执行约束：AGENTS.md、相关 README、构建/测试文档和任务相关设计说明。
• 如果用户没有给出确切文件，检查工作区中最可能的活跃 TODO 文档，例如 TODO.md、todo.md、PLAN.md、ROADMAP.md、CHECKLIST.md 或 issue 跟踪类 Markdown 文件。简要说明你的假设，然后继续执行。

构建有序任务列表

• 保留文档自身顺序。把标题视为阶段，把每个阶段中的列表项视为有序工作。
• 对 Markdown TODO 文档，运行 python3 scripts/todo_outline.py <todo-path> 提取带行号和标题上下文的可执行条目。
• 把未勾选复选框视为未完成任务。
• 即使文档没有使用复选框，只要编号项或项目符号项表达的是要执行的工作，也应视为可执行条目。
• 将信息性备注和可执行条目分开，不要假装每个列表项都可执行。

顺序执行

• 从第一个未完成的可执行条目开始。
• 完成当前任务后，才能声称成功并移动到下一项。
• 如果某个任务自然展开出若干必要的小型隐含子任务，应立即完成这些子任务，确保该项真正完成。
• 不要为了增加完成数量而跳过困难任务。
• 如果当前任务确实被外部依赖、缺失决策或上游失败阻塞，清楚记录阻塞原因，然后只继续执行不依赖该阻塞项的后续任务。

标记完成前先验证

• 用最小但有说服力的证据证明完成：定向测试、构建、lint、生成产物、源码检查或产物检查。
• 当实现、文档或任务所需验证仍缺失时，绝不能把任务标记为完成。
• 只有在用户要求同步 TODO 文档，且实际工作已经完成时，才更新复选框状态。
• 当 TODO 文件需要保持同步时，使用 python3 scripts/todo_progress.py check <todo-path> --line <n> 或 --item <n>，不要手动编辑复选框。
• 宁可做较小但正确的改动，也不要做范围更大但不稳妥的改动。

最大化诚实吞吐

• 完成一个任务后，立即继续下一个未阻塞任务。
• 在有帮助时可以批量收集上下文，但不要批量声称“完成”；每个已完成条目都需要独立证据。
• 选择能完全满足当前条目的最小可行实现路径，保持推进节奏。
• 只有遇到真实阻塞、高风险歧义、导致下游无效的失败前置条件或用户改向时才停止。

诚实汇报

• 用简短证据总结已完成条目。
• 对阻塞或部分完成的条目，指出准确阻塞原因。
• 指出文档顺序中的下一个条目，方便用户立即继续。
• 当用户需要新的剩余任务快照时，运行 python3 scripts/todo_progress.py summary <todo-path>。
• 当你需要更严格的完成定义、阻塞处理或防作弊检查时，读取 references/execution-rubric.md。

使用捆绑资源

• 使用 scripts/todo_outline.py 将 Markdown TODO 文件转换为带行号的有序大纲。
• 使用 scripts/todo_progress.py check 按行号或大纲序号标记已完成的复选框条目。
• 使用 scripts/todo_progress.py summary 按标题分组打印剩余可执行条目。
• 当任务措辞含糊、完成标准有争议，或需要判断某个阻塞是否足以继续推进时，读取 references/execution-rubric.md。