todo-list-csv

Original：🇨🇳 Chinese

Translated

1 scriptsChecked / no sensitive code detected

Use this skill when you need to modify a project (add, delete, or modify files) and want to organically synchronize update_plan with CSV: Create a `{Task Name} TO DO list.csv` file in the project root directory, use TODO/IN_PROGRESS/DONE statuses to drive the pending/in_progress/completed status of the plan, advance tasks synchronously, and delete the file after all tasks are completed.

3installs

Sourcehjdyzy/aicoding-cookbook

Added on2026-04-02

NPX Install

npx skill4agent add hjdyzy/aicoding-cookbook todo-list-csv

SKILL.md Content (Chinese)

View Translation Comparison →

Todo List CSV

Objective

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

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

Workflow (CSV + update_plan dual-track synchronization)

0) Conditions for enabling update_plan

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

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

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) Create

{Task Name} TO DO list.csv

in the project root directory

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) State Machine and Mapping (Core Constraints)

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) Synchronization during advancement (synchronize once each time an item is completed)

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) Mid-term changes and suspension

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) Finalization and cleanup

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

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}"