todo-md

todo-md

Manage a repo-local TODO.md that is co-owned by a pi coding agent running the pi-todo-md extension. The goal is zero format drift: every change you make must be byte-identical to what pi would write, so the two agents never fight over the file.

To guarantee that, do not hand-edit TODO.md for mutations. Drive all changes through todo.mjs, which calls pi's own engine (the exact same executeTodoActionOnFile code path pi uses). Reading is fine to do directly.

Usage

todo.mjs lives in this skill's own directory (the same directory as this SKILL.md). Run it with that path — $SKILL_DIR/todo.mjs below stands for that directory (e.g. ~/.claude/skills/todo-md/ for a global install, or .claude/skills/todo-md/ for a project install). Run from the directory where the work is happening (the TODO.md is auto-located: nearest one up the tree, else created at the git repo root):

node "$SKILL_DIR/todo.mjs" <action> '<json-params>'

<action> is positional; the JSON object holds the rest of the params. Examples:

node "$SKILL_DIR/todo.mjs" list
node "$SKILL_DIR/todo.mjs" add '{"text":"publish the plugin","priority":"high"}'
node "$SKILL_DIR/todo.mjs" bulk_add '{"items":["write docs","record demo","publish"]}'
node "$SKILL_DIR/todo.mjs" add '{"text":"triage bug","section":"In Progress","index":1}'
node "$SKILL_DIR/todo.mjs" check '{"id":3}'
node "$SKILL_DIR/todo.mjs" focus_task '{"id":2}'
node "$SKILL_DIR/todo.mjs" set_priority '{"id":2,"priority":"high"}'
node "$SKILL_DIR/todo.mjs" append_note '{"id":2,"text":"publish after docs land"}'
node "$SKILL_DIR/todo.mjs" add_subtask '{"id":2,"text":"write README"}'
node "$SKILL_DIR/todo.mjs" check_subtask '{"id":2,"subtask":1}'
node "$SKILL_DIR/todo.mjs" move '{"id":3,"section":"In Progress"}'
node "$SKILL_DIR/todo.mjs" archive_done

file and whether anything actually changed.

Actions

index and subtask are 1-based. id is the stable number shown in list (stored in a hidden <!-- pi-todo-md:id=N --> comment).

File format (for reading)

When you read TODO.md directly, this is the canonical shape the engine maintains:

# TODO
<!-- pi-todo-md:schema=1 -->

## Tasks
- [ ] ship the plugin [focus] [high] <!-- pi-todo-md:id=1 -->
  - note: publish after trusted publishing works
  - [ ] write docs
  - [x] publish package
- [x] read the docs <!-- pi-todo-md:id=2 -->

## In Progress
- [ ] package it for sharing <!-- pi-todo-md:id=3 -->

## Archive
- [x] initial release <!-- pi-todo-md:id=4 -->

• •[focus] then priority ([low|medium|high]) are the metadata markers, in that order.
• •Notes use - note: ...; subtasks use - [ ] ... (two-space indent, no id).
• •Archive is special: focus/next ignore it. Default section is Tasks.
• •The hidden id and schema comments must be preserved — that's how pi keeps IDs

stable. The CLI handles all of this; never renumber or strip markers by hand.

Co-op notes

• •Pi rewrites the whole file in canonical form on each of its actions. Because this CLI

uses the same engine, your writes match exactly, so diffs stay minimal and neither agent clobbers the other's formatting.

• •Before a batch of edits, list first to get current IDs (pi may have changed them).
• •For a quick glance you may cat/Read TODO.md, but route every mutation through the CLI.