todo-list-csv

在需要修改项目时，用一个位于项目根目录的 CSV 文件把工作拆成可勾选的步骤；在推进过程中持续更新；全部完成后删除该 CSV，避免把临时清单遗留或提交进仓库。

• 用户明确要求：TODO 清单 / checklist / 进度表 / CSV / “打勾追踪进度”
• 任务步骤较多（例如 ≥4 步）且你希望把进度落盘，便于跨会话/交接/回滚审计
• 你希望用脚本把 CSV → update_plan 保持“一处修改，两处同步”

• 只有 1–2 步的简单任务（直接 update_plan 或不建 plan 即可）
• 纯研究/纯问答任务（优先用 workflow/planning-with-files 的 notes.md）
• 你不需要持久化清单（CSV 最终会被 cleanup 删除，适合“临时但可追踪”的任务）

• workflow/planning-with-files：更适合“长任务/研究多/目标易漂移”，用 task_plan.md/notes.md 做工作记忆
• workflow/todo-list-csv：更适合“需要明确 checklist + 状态机 + 审计痕迹”，用 CSV 严格驱动 update_plan

0) 启用 update_plan 的条件

• 当任务包含 ≥2 个可独立验收步骤 时，调用 update_plan 建立计划并在执行过程中持续更新。

1) 拆解步骤并建立 plan（与 CSV 一一对应）

• 拆成 3–12 条可验收步骤（动词开头，避免过长）。
• 立即调用 update_plan 建立初始 plan：第 1 步 in_progress，其余 pending。
• 保持 plan 的每个 step 文案与 CSV 的 item 完全一致（便于同步与审计）。

2) 在项目根目录创建 `{任务名} TO DO list.csv`

• 确定“任务名”：优先取自用户请求的短标题；必要时做简化（去掉标点、过长截断）。
• 计算“项目根目录”：优先使用 Git 仓库根目录；非 Git 项目则使用当前工作目录作为根目录。
• 在项目根目录创建文件：{任务名} TO DO list.csv。

CSV 表头固定为（首行）：

id,item,status,done_at,notes

• id：从 1 开始的整数
• item：单条待办（与 plan 的 step 一致）
• status：TODO / IN_PROGRESS / DONE
• done_at：完成时间（ISO 8601，未完成留空）
• notes：可选备注（文件路径、验证方式、PR/commit 等）

3) 状态机与映射（核心约束）

• 仅允许状态流转：TODO → IN_PROGRESS → DONE（避免 TODO 直跳 DONE）。
• plan 映射：TODO→pending，IN_PROGRESS→in_progress，DONE→completed。
• 任意时刻 最多 1 行 IN_PROGRESS；只要仍有未完成项，尽量保持 恰好 1 行 IN_PROGRESS（与 plan 的唯一 in_progress 对齐）。

4) 推进时同步（每完成一项就同步一次）

• 完成当前 IN_PROGRESS 项后：

1) 更新 CSV（推荐用脚本 advance 自动“完成当前项并启动下一项”）

2) 从 CSV 生成 plan payload（plan --normalize）

3) 调用 update_plan 使 plan 与 CSV 同步

5) 中途变更与暂停

• 新增步骤：只做“追加”，避免重排/重编号；同时更新 CSV 与 plan。
• 暂停等待反馈：保留 CSV；plan 当前步骤保持 in_progress，或追加“等待反馈”步骤并置为 in_progress。

6) 收尾与清理

• 确认所有行均为 DONE，再删除该 CSV 文件（脚本 cleanup 会在未全 DONE 时拒绝删除）。
• 调用 update_plan 将所有步骤标记为 completed，确保对话内计划闭环。

使用 scripts/todo_csv.py 自动创建/更新/清理 CSV（优先用于避免手工编辑出错）。

示例命令：

• 创建清单（默认第 1 条为 IN_PROGRESS）：python3 ~/.codex/skills/workflow/todo-list-csv/scripts/todo_csv.py init --title "修复登录 bug" --item "复现问题" "加回归测试" "修复实现" "运行测试/构建"
• 计算路径：python3 ~/.codex/skills/workflow/todo-list-csv/scripts/todo_csv.py path --title "修复登录 bug"
• 从 CSV 生成 update_plan payload（推荐带 --normalize）：python3 ~/.codex/skills/workflow/todo-list-csv/scripts/todo_csv.py plan --file "{csv_path}" --normalize --explanation "同步自 TODO CSV"
• 启动指定步骤：python3 ~/.codex/skills/workflow/todo-list-csv/scripts/todo_csv.py start --file "{csv_path}" --id 2
• 推进一步（完成当前 IN_PROGRESS 并启动下一条 TODO）：python3 ~/.codex/skills/workflow/todo-list-csv/scripts/todo_csv.py advance --file "{csv_path}" --notes "已通过单测"
• 查看进度：python3 ~/.codex/skills/workflow/todo-list-csv/scripts/todo_csv.py status --file "{csv_path}" --verbose
• 全部完成后清理：python3 ~/.codex/skills/workflow/todo-list-csv/scripts/todo_csv.py cleanup --file "{csv_path}"