Goal
When a project needs to be modified, use a CSV file located in the project root directory to break the work into checkable steps; keep updating it as progress is made; once everything is complete, delete the CSV to avoid leaving or committing a temporary checklist into the repository.
Trigger conditions
- The user explicitly requests: TODO list / checklist / progress table / CSV / "check off progress tracking"
- There are many task steps (for example, ≥4 steps) and you want to persist progressto disk, making it convenient for cross-session/handoff/rollback auditing
- You want to use a script to keep CSV →
update_planin sync as "one change, two places synchronized"
When not to use (to avoid false triggers)
- Simple tasks with only 1–2 steps (directly
update_planor just don't create a plan) - Purely research/purely Q&A tasks (prefer
workflow/planning-with-files'snotes.md) - You do not need a persistent checklist (the CSV will ultimately be deleted by
cleanup, suitable for "temporary but trackable" tasks)
Division of labor with workflow/planning-with-files division of labor
workflow/planning-with-files: more suitable for "long tasks/much research/easily drifting goals", usingtask_plan.md/notes.mdas working memoryworkflow/todo-list-csv: more suitable for "needs a clear checklist + state machine + audit trail", using CSV to strictly drive theupdate_plan
workflow (CSV + update_plan dual-track synchronization)
0) Conditions for enabling update_plan
- When the task includes ≥2 independently acceptable steps , call
update_planto establish a plan and keep updating it during execution.
1) Break down the steps and establish a plan (one-to-one correspondence with the CSV)
- Break it into 3–12 acceptable steps (start with verbs, avoid overly long ones).
- Immediately call
update_planto establish the initial plan: step 1in_progress, the restpending。 - Keep each of the plan's
steptext exactly consistent with the CSV'sitemcompletely consistent(for ease of synchronization and auditing).
2) Create in the project root directory {任务名} TO DO list.csv
- Determine the "task name": preferably taken from a short title in the user's request; simplify when necessary (remove punctuation, truncate if too long).
- Calculate the "project root directory": preferably use the Git repository root directory; for non-Git projects, use the current working directory as the root directory.
- Create the file in the project root directory:
{任务名} TO DO list.csv。
The CSV header is fixed as (first row):
id,item,status,done_at,notes
id: an integer starting from 1item: a single todo item (consistent with the plan'sstep).status:TODO/IN_PROGRESS/DONEdone_at: completion time (ISO 8601, leave blank if incomplete)notes: optional remarks (file path, verification method, PR/commit, etc.)
3) State machine and mapping (core constraints)
- Only the following state transitions are allowed:
TODO→IN_PROGRESS→DONE(avoidTODOjumping directly toDONE)。 - plan mapping:
TODO→pending,IN_PROGRESS→in_progress,DONE→completed。 - At any moment at most 1 row
IN_PROGRESS; as long as there are still incomplete items, try to keep exactly 1 rowIN_PROGRESS(aligned with the plan's uniquein_progress).
4) Synchronize as you advance (synchronize once each time an item is completed)
- Complete the current
IN_PROGRESSafter the item:- Update CSV (recommended to use the script
advanceto automatically “complete the current item and start the next item”) - Generate the plan payload from the CSV (
plan --normalize) - Call
update_planto keep the plan in sync with the CSV
- Update CSV (recommended to use the script
5) Mid-course changes and pauses
- Adding steps: only “append”; avoid reordering/renumbering; at the same time update both the CSV and the plan.
- Pause and wait for feedback: keep the CSV; keep the current plan step as
in_progress, or append a “wait for feedback” step and set it toin_progress。
6) Wrap-up and cleanup
- Confirm that all rows are
DONE, then delete the CSV file (the scriptcleanupwill refuse to delete it when not all are DONE). - Call
update_planto mark all steps ascompleted, ensuring the plan within the conversation is closed out.
Optional automation scripts
Use scripts/todo_csv.py to automatically create/update/clean up the CSV (preferred to avoid errors from manual editing).
Example commands:
- Create the checklist (by default item 1 is IN_PROGRESS):
python3 ~/.codex/skills/workflow/todo-list-csv/scripts/todo_csv.py init --title "修复登录 bug" --item "复现问题" "加回归测试" "修复实现" "运行测试/构建" - Compute the path:
python3 ~/.codex/skills/workflow/todo-list-csv/scripts/todo_csv.py path --title "修复登录 bug" - Generate from the CSV
update_planpayload (recommended with--normalize):python3 ~/.codex/skills/workflow/todo-list-csv/scripts/todo_csv.py plan --file "{csv_path}" --normalize --explanation "同步自 TODO CSV" - Start the specified step:
python3 ~/.codex/skills/workflow/todo-list-csv/scripts/todo_csv.py start --file "{csv_path}" --id 2 - Advance one step (complete the current IN_PROGRESS and start the next TODO):
python3 ~/.codex/skills/workflow/todo-list-csv/scripts/todo_csv.py advance --file "{csv_path}" --notes "已通过单测" - View progress:
python3 ~/.codex/skills/workflow/todo-list-csv/scripts/todo_csv.py status --file "{csv_path}" --verbose - Clean up after everything is complete:
python3 ~/.codex/skills/workflow/todo-list-csv/scripts/todo_csv.py cleanup --file "{csv_path}"