todo-list-csv

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Todo List CSV

目标

Objective

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

When you need to modify a project, split the work into checkable steps using a CSV file located in the project root directory. Update the file continuously as work progresses, and delete the CSV after all tasks are completed to avoid leaving the temporary checklist behind or committing it to the repository.

触发条件

Trigger Conditions

开始执行任何会改动项目内容的任务（新增/修改/删除文件、调整配置、修复 bug、实现功能等）
任务具有多个可独立验收的小步骤，且需要显式跟踪完成状态

You start any task that will modify project content (adding/modifying/deleting files, adjusting configurations, fixing bugs, implementing features, etc.)
The task has multiple independently verifiable small steps, and the completion status needs to be explicitly tracked

工作流（CSV + update_plan 双轨同步）

Workflow (CSV + update_plan dual-track synchronization)

0) 启用 update_plan 的条件

0) Conditions for enabling update_plan

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

When a task includes ≥2 independently verifiable steps, call
```
update_plan
```
to create a plan and update it continuously during execution.

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

1) Split steps and create a plan (one-to-one correspondence with CSV)

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

Split into 3–12 verifiable steps (start with a verb, avoid excessive length).
Immediately call
```
update_plan
```
to create the initial plan: set the first step to
```
in_progress
```
, and the rest to
```
pending
```
.
Keep the text of each
```
step
```
in the plan completely consistent with the
```
item
```
in the CSV (for easy synchronization and auditing).

2) 在项目根目录创建

{任务名} TO DO list.csv

2) Create

{Task Name} TO DO list.csv

in the project root directory

确定“任务名”：优先取自用户请求的短标题；必要时做简化（去掉标点、过长截断）。
计算“项目根目录”：优先使用 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 等）

Determine the "task name": Priority is given to the short title from the user's request; simplify if necessary (remove punctuation, truncate if too long).
Determine the "project root directory": Priority is given to the Git repository root directory; for non-Git projects, use the current working directory as the root directory.
Create the file
```
{Task Name} TO DO list.csv
```
in the project root directory.

The CSV header is fixed (first line):

id,item,status,done_at,notes

```
id
```
: Integer starting from 1
```
item
```
: Single to-do item (consistent with the
```
step
```
in the plan)
```
status
```
:
```
TODO
```
/
```
IN_PROGRESS
```
/
```
DONE
```
```
done_at
```
: Completion time (ISO 8601, leave blank if not completed)
```
notes
```
: Optional remarks (file path, verification method, PR/commit, etc.)

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

3) State Machine and Mapping (Core Constraints)

仅允许状态流转：
```
TODO
```
→
```
IN_PROGRESS
```
→
```
DONE
```
（避免
```
TODO
```
直跳
```
DONE
```
）。

plan 映射：

TODO

→

pending

，

IN_PROGRESS

→

in_progress

，

DONE

→

completed

。

任意时刻 最多 1 行
```
IN_PROGRESS
```
；只要仍有未完成项，尽量保持 恰好 1 行
```
IN_PROGRESS
```
（与 plan 的唯一
```
in_progress
```
对齐）。

Only allow state transition:
```
TODO
```
→
```
IN_PROGRESS
```
→
```
DONE
```
(avoid jumping directly from
```
TODO
```
to
```
DONE
```
).

Plan mapping:

TODO

→

pending

IN_PROGRESS

→

in_progress

DONE

→

completed

At any time, max 1 row can be in
```
IN_PROGRESS
```
status; as long as there are unfinished items, try to keep exactly 1 row in
```
IN_PROGRESS
```
status (aligned with the only
```
in_progress
```
step in the plan).

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

4) Synchronization during advancement (synchronize once each time an item is completed)

完成当前
```
IN_PROGRESS
```
项后：
1. 更新 CSV（推荐用脚本
```
advance
```
  自动“完成当前项并启动下一项”）
2. 从 CSV 生成 plan payload（
```
plan --normalize
```
  ）
3. 调用
```
update_plan
```
  使 plan 与 CSV 同步

After completing the current
```
IN_PROGRESS
```
item:
1. Update the CSV (it is recommended to use the
```
advance
```
  script to automatically "complete the current item and start the next item")
2. Generate plan payload from CSV (
```
plan --normalize
```
  )
3. Call
```
update_plan
```
  to synchronize the plan with the CSV

5) 中途变更与暂停

5) Mid-term changes and suspension

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

Add steps: Only "append" is allowed, avoid rearranging/renumbering; update both CSV and plan at the same time.
Pause waiting for feedback: Keep the CSV; keep the current step of the plan as
```
in_progress
```
, or append a "wait for feedback" step and set it to
```
in_progress
```
.

6) 收尾与清理

6) Finalization and cleanup

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

Confirm all rows are
```
DONE
```
before deleting the CSV file (the
```
cleanup
```
script will refuse to delete if not all items are DONE).
Call
```
update_plan
```
to mark all steps as
```
completed
```
to ensure the plan in the conversation is closed.

可选自动化脚本

Optional Automation Scripts

使用

scripts/todo_csv.py

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

示例命令：

创建清单（默认第 1 条为 IN_PROGRESS）：

python3 ~/.codex/skills/todo-list-csv/scripts/todo_csv.py init --title "修复登录 bug" --item "复现问题" "加回归测试" "修复实现" "运行测试/构建"

计算路径：

python3 ~/.codex/skills/todo-list-csv/scripts/todo_csv.py path --title "修复登录 bug"

从 CSV 生成

update_plan

payload（推荐带

--normalize

）：

python3 ~/.codex/skills/todo-list-csv/scripts/todo_csv.py plan --file "{csv_path}" --normalize --explanation "同步自 TODO CSV"

启动指定步骤：

python3 ~/.codex/skills/todo-list-csv/scripts/todo_csv.py start --file "{csv_path}" --id 2

推进一步（完成当前 IN_PROGRESS 并启动下一条 TODO）：

python3 ~/.codex/skills/todo-list-csv/scripts/todo_csv.py advance --file "{csv_path}" --notes "已通过单测"

查看进度：

python3 ~/.codex/skills/todo-list-csv/scripts/todo_csv.py status --file "{csv_path}" --verbose

全部完成后清理：

python3 ~/.codex/skills/todo-list-csv/scripts/todo_csv.py cleanup --file "{csv_path}"

Use

scripts/todo_csv.py

to automatically create/update/clean up CSV (preferred to avoid manual editing errors).

Sample commands:

Create a checklist (the first item is set to IN_PROGRESS by default):

python3 ~/.codex/skills/todo-list-csv/scripts/todo_csv.py init --title "修复登录 bug" --item "复现问题" "加回归测试" "修复实现" "运行测试/构建"

Get file path:

python3 ~/.codex/skills/todo-list-csv/scripts/todo_csv.py path --title "修复登录 bug"

Generate

update_plan

payload from CSV (recommended with

--normalize

python3 ~/.codex/skills/todo-list-csv/scripts/todo_csv.py plan --file "{csv_path}" --normalize --explanation "同步自 TODO CSV"

Start specified step:

python3 ~/.codex/skills/todo-list-csv/scripts/todo_csv.py start --file "{csv_path}" --id 2

Advance one step (complete current IN_PROGRESS item and start the next TODO):

python3 ~/.codex/skills/todo-list-csv/scripts/todo_csv.py advance --file "{csv_path}" --notes "已通过单测"

View progress:

python3 ~/.codex/skills/todo-list-csv/scripts/todo_csv.py status --file "{csv_path}" --verbose

Clean up after all tasks are completed:

python3 ~/.codex/skills/todo-list-csv/scripts/todo_csv.py cleanup --file "{csv_path}"

todo-list-csv

Original

Translation

Todo List CSV

Todo List CSV

目标

Objective

触发条件

Trigger Conditions

工作流（CSV + update_plan 双轨同步）

Workflow (CSV + update_plan dual-track synchronization)

0) 启用 update_plan 的条件

0) Conditions for enabling update_plan

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

1) Split steps and create a plan (one-to-one correspondence with CSV)

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

2) Create
`{Task Name} TO DO list.csv`
in the project root directory

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

3) State Machine and Mapping (Core Constraints)

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

4) Synchronization during advancement (synchronize once each time an item is completed)

5) 中途变更与暂停

5) Mid-term changes and suspension

6) 收尾与清理

6) Finalization and cleanup

可选自动化脚本

Optional Automation Scripts