SuperAPI AI Directory

todo-list-csv

General & other

View repository

Updated 10-16 08:44

About this skill

Todo List CSV

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_plan in sync as "one change, two places synchronized"

When not to use (to avoid false triggers)

  • Simple tasks with only 1–2 steps (directly update_plan or just don't create a plan)
  • Purely research/purely Q&A tasks (prefer workflow/planning-with-files 's notes.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", using task_plan.md/notes.md as working memory
  • workflow/todo-list-csv: more suitable for "needs a clear checklist + state machine + audit trail", using CSV to strictly drive the update_plan

workflow (CSV + update_plan dual-track synchronization)

0) Conditions for enabling update_plan

  • When the task includes ≥2 independently acceptable steps , call update_plan to 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_plan to establish the initial plan: step 1 in_progress, the rest pending。
  • Keep each of the plan's step text exactly consistent with the CSV's item completely 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 1
  • item: a single todo item (consistent with the plan's step ).
  • status:TODO / IN_PROGRESS / DONE
  • done_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(avoid TODO jumping directly to DONE)。
  • 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 row IN_PROGRESS(aligned with the plan's unique in_progress ).

4) Synchronize as you advance (synchronize once each time an item is completed)

  • Complete the current IN_PROGRESS after the item:
    1. Update CSV (recommended to use the script advance to automatically “complete the current item and start the next item”)
    2. Generate the plan payload from the CSV (plan --normalize)
    3. Call update_plan to keep the plan in sync with the CSV

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 to in_progress。

6) Wrap-up and cleanup

  • Confirm that all rows are DONE, then delete the CSV file (the script cleanup will refuse to delete it when not all are DONE).
  • Call update_plan to mark all steps as completed, 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_plan payload (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}"