cj-todo

Overview

The world's most lightweight repo-scoped todo app. A bundled bash script (todo.sh) does all the mechanical CRUD against <repo-root>/.plans/; your job is to (1) call it with the right command and (2) decide whether something is a quick todo or warrants a plan. Stay terse; the point is speed.

Storage (per git repo) is filesystem-first: plans are plain files, so hand-maintained .plans/ dirs work without conversion.

• .plans/TODO.md: open one-line todos (- [ ] checkboxes)
• .plans/DONE.md: completed todos, archived with a date
• .plans/<name>.md: one file per plan; the file is the unit of work
• .plans/done/: completed plans (files moved here)

todo lists every .plans/*.md file as a plan, whether the script created it or someone dropped it in by hand. It never parses prose bullets or numbered lists into todos, so a narrative TODO.md that just indexes or orders plan files is left untouched.

The script

Invoke the bundled script. If todo is on PATH use it directly; otherwise call the script by path (./todo.sh inside this skill folder, or wherever it's installed).

todo                  # list open todos & plans (default)
todo --all [--path <dir>] [--depth <n>]
                      # every repo's list under <dir> (default $PWD), <n> levels deep;
                      # grouped per repo, numbers are per repo (cd there to done/rm)
todo add "<text>"     # add a todo
todo plan "<name>"    # create a plan file (.plans/<slug>.md); prints the path
todo done <n> [n...]  # complete #n (todo → DONE.md, plan file → .plans/done/)
todo rm <n> [n...]    # delete #n (todo line, or plan file)
todo log              # show completed todos & plans
todo where            # print the .plans directory
todo -g <cmd> ...     # same commands against the global store (~/brain/todos), not the repo
todo install          # symlink the script as `todo` on PATH (~/.local/bin)

Item numbers come straight from todo / todo list output. List first if you need a number you do not already have.

Completing several at once: numbers are list positions, so they renumber after every removal. To finish multiple items from one listing, pass them all to a single call (todo done 2 3 4); they are resolved against one snapshot, so nothing drifts. Never fire todo done <n> repeatedly off the same original listing; either batch them or re-list between calls.

Todo vs. plan: the one judgment call

Default to a todo (todo add). Reach for a plan (todo plan) only when:

• the user explicitly says "plan", "make a plan", "write a plan", or similar, or
• the work is large/multi-step enough that it should be thought through before doing it (e.g. "rewrite the auth layer", "migrate to the new API") rather than a single action.

When in doubt, add a todo. Promoting later is cheaper than over-ceremony on a one-liner.

Workflow

1. Add a todo: todo add "<concise task>". Keep the text short and imperative.
2. Add a plan: todo plan "<name>" creates .plans/<slug>.md; open the printed file and fill in the ## Goal / ## Steps / ## Notes sections with a real, actionable plan based on what the user described. Leave a useful skeleton, not lorem ipsum. (Completing a plan later moves the whole file into .plans/done/.)
3. Complete / remove: run todo to see numbers, then todo done <n> (or rm).
4. Review: todo for open work, todo log for finished work.

Guardrails

• Do not hand-edit TODO.md / DONE.md for add/done/rm; use the script so numbering and archiving stay consistent. A plan's own .plans/<name>.md is free to edit.
• todo rm <n> on a plan deletes the file; todo done <n> archives it to .plans/done/. Prefer done unless the user wants it gone for good.
• When the action is a plain list (no-arg invocation, or todo list): always print the full list verbatim in your text response, since that is the output the user wants to see.
• For all other actions (add, done, rm, plan): confirm in a line or two; do not restate the full list unless asked.
• The store is per-repo (resolved via git rev-parse --show-toplevel, falling back to the current directory). If the user expects a list and it is empty, they may be in the wrong repo; say so rather than assuming.