flowcode-executor

name	flowcode-executor
description	按照已有 vibe coding todo list 逐项执行开发任务。如果任务列表文档不存在，自动调用 flowcode_todo 根据需求生成任务列表后再执行。Use when Codex 需要从现有 todos.md、任务清单或 wiki 生成的 todo list 中选择未完成任务，读取关联 wiki/文档，明确验收标准，做最小代码修改，运行验证，并在通过后更新 todo 状态；适用于"按照 todo list 执行""继续下一个任务""完成 Txx""批量执行前 N 个 todo"等场景。

Vibe Coding Todo Executor

使用目标

按照已有 todo list 执行 vibe coding 任务，把任务从"计划"推进到"已验证完成"。

核心原则：自动运行，自主找方案，实在不能运行就停止。

• 遇到问题时先自行分析并尝试解决，不等待用户介入。
• 多个方案可选时，选择最优方案直接执行。
• 只有确认无法继续时才停止任务并说明原因。

必须遵守：

• 全程使用中文汇报，除非用户明确要求其他语言。
• 默认一次只执行一个未完成任务；只有用户明确要求批量时才连续执行。
• 不创建临时文件、总结文档、变更日志或额外计划文件，除非用户明确要求。
• 不扩展 todo 之外的需求，不重构无关代码，不格式化无关文件。
• 验证通过后才勾选 todo；验证失败、未运行或任务不清晰时不要标记完成。
• 如果发现用户已有未提交改动，必须保护这些改动，不要回滚或覆盖。

路径策略

把路径视为可推断参数：

todoFile       任务清单文件
wikiIndex      wiki 总索引
linkedDocs     当前任务引用的 wiki 或文档

推断顺序：

1. 优先使用用户明确给出的 todo 文件或任务编号。
2. 如果用户只说"按照 todo list 执行"，优先查找当前项目根目录的 todos.md。
3. 如果 todo 中引用了 wiki 链接，只读取当前任务相关链接；不要一次性加载整个 wiki。
4. 如果 todo 没有引用文档，但项目存在明显的 docs/wiki/README.md，可把它作为索引辅助定位。
5. 如果存在多个候选 todo 文件且无法判断，按以下决策顺序处理：分析各候选文件的上下文与当前任务相关性，推断最优候选并执行；无法推断则停止任务并说明原因。

任务列表前置检查

在执行任何任务之前，必须先确认 todoFile 是否存在：

1. 如果 todoFile（默认 todos.md）已存在 → 直接进入执行流程。
2. 如果 todoFile 不存在：
   • 先分析项目根目录或用户指定的 sourceDocsDir 中是否有需求文档（Markdown 文件）。
   • 如果有需求文档，调用 flowcode_todo 生成任务列表。
     • flowcode_todo 会根据需求文档自动判断是否需要先调用 flowcode_wiki 和/或 flowcode_ui，最终产出 todoFile。
     • 等待 flowcode_todo 完成后，读取生成的 todoFile，再进入执行流程。
   • 如果没有需求文档，分析项目现有代码结构推断可能的任务；无法推断则停止任务并说明缺少 todoFile 且无可用需求文档。

执行流程

1. 选择任务

1. 读取 todoFile。
2. 选择任务：
   • 用户指定 Txx 时执行该任务。
   • 未指定时选择第一个未勾选任务。
   • 批量执行时按 todo 顺序逐个处理，遇到失败或不清晰立即停止。
3. 检查依赖：
   • 如果当前任务明显依赖尚未完成的前置任务，先分析是否可顺序执行，能推断则按最优方案执行，无法判断则停止任务并说明阻塞原因。
   • 如果任务目标、验收标准或引用文档缺失且无法合理推断，停止任务并说明缺失信息。

2. 建立上下文

执行前必须先看：

• 当前 todo 的完整文本。
• 当前 todo 引用的 docs/wiki/文档。
• 与任务直接相关的代码、配置、测试和接口定义。

对用户说明简短计划：

1. 读取任务与引用文档 -> 验证：确认目标和验收标准
2. 修改最小代码范围 -> 验证：运行相关测试/编译/lint
3. 更新 todo 状态 -> 验证：只在通过后勾选

计划应包含已知假设；如果假设风险高但可自行验证，先验证再继续；无法自行验证则停止任务并说明风险。

3. 实现

实现时遵守：

• 只修改完成当前 todo 必需的文件。
• 优先沿用项目现有架构、命名、错误处理和测试风格。
• 不为单次需求新增抽象、配置项或扩展点。
• 不删除或改写用户已有改动。
• 如果发现 todo 设计与现有代码冲突，先说明冲突和可选处理方式。

4. 验证

按风险选择最小但可信的验证：

• 有测试时，优先运行相关测试。
• 没有测试但有编译命令时，运行相关模块编译。
• 前端改动优先运行 lint/typecheck/test/build 中最贴近项目现有习惯的命令。
• 无法运行验证时，说明原因和残余风险，不要勾选 todo。

如果验证失败：

• 先修复与当前改动直接相关的问题并重跑验证。
• 如果失败来自无关既有问题，说明证据，并不要扩大修改范围。
• 仍无法通过时，保留代码改动但不要勾选 todo，向用户汇报阻塞点。

5. 更新 todo

只有满足验收标准且验证通过后，才把当前任务从 [ ] 改为 [x]。

更新规则：

• 保留原任务文本、编号、链接和层级。
• 不额外追加总结段落，除非 todo 文件原本就有固定的完成记录格式。
• 批量执行时每完成一个任务就更新一次对应勾选状态。
• 如果验证未通过、未运行或用户需要确认，不更新为完成。

汇报格式

完成后简短说明：

• 执行的任务编号和目标。
• 修改的文件。
• 验证命令和结果。
• todo 是否已勾选。
• 下一个建议执行的未完成任务。