File Todos

File-based TODO Lifecycle

Track review findings and work items as individual markdown files in todos/. Each file captures the full context — problem, evidence, proposed solutions, and work log — so any agent can pick it up and resolve it independently.

Naming Convention

{id}-{status}-{priority}-{description}.md

Full example: 001-pending-p1-missing-auth-middleware.md

Statuses

Priorities

Operations

Create a TODO

Find the highest existing ID in todos/ and increment by 1. Start at 001 if the directory is empty.

Use the Write tool to create the file at todos/{id}-pending-{priority}-{description}.md using the template in references/todo-template.md.

List TODOs

Use Glob to find TODOs by status:

• All pending: todos/*-pending-*.md
• All ready: todos/*-ready-*.md
• All complete: todos/*-complete-*.md
• All p1 critical: todos/*-*-p1-*.md

Update Status

Rename the file via Bash mv to change the status segment:

mv todos/001-pending-p1-missing-auth.md todos/001-ready-p1-missing-auth.md

Also update the status field in the YAML frontmatter to match.

Delete a TODO

Remove the file via Bash rm:

rm todos/001-pending-p3-minor-cleanup.md

Auto-ID

When creating a new TODO, determine the next ID:

1. Glob todos/[0-9][0-9][0-9]-*.md to find all existing TODOs
2. Extract the numeric prefix from each filename
3. Take the maximum and add 1
4. If no files exist, start at 001
5. Zero-pad to 3 digits

Template

See references/todo-template.md for the full TODO file structure.