File-based TODO lifecycle

Track review findings and work items as individual markdown files in todos/ at the project root. Each file carries the full context (problem, evidence, proposed solutions, work log) so any agent can pick it up and resolve it independently. Adapted from EveryInc's compound-engineering plugin (https://github.com/EveryInc/compound-engineering-plugin).

Request: $ARGUMENTS

Modes

Pick the mode from the request (when $ARGUMENTS is empty, the user's latest message is the request):

Lifecycle: create (pending) → triage (ready or deleted) → resolve (complete).

Naming convention

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

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

Statuses

Priorities

Findings on a P0–P3 scale (reviewers that use P0 for blocking): map P0 and P1 → p1, P2 → p2, P3 → p3.

Operations

Create a TODO

1. Compute the next ID (Auto-ID below).
2. Write todos/{id}-pending-{priority}-{description}.md from references/todo-template.md. Fill Problem Statement, Findings (with file:line evidence), Proposed Solutions and Acceptance Criteria; leave Recommended Action blank for triage.
3. One finding per file. Set dependencies to the IDs that must be resolved first.

List TODOs

Glob by status or priority:

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

Update status

Rename to change the status segment (git mv when the file is tracked), then update status and updated in the frontmatter to match:

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

Delete a TODO

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

Auto-ID

1. Glob todos/[0-9][0-9][0-9]-*.md.
2. Extract the numeric prefix of each filename.
3. Take the maximum and add 1; no files → 001.
4. Zero-pad to 3 digits.

Rules

• The filename and the frontmatter status always agree; fix a mismatch before anything else.
• Triage decides, resolve implements. Never implement a pending TODO.
• Files that recommend deleting docs/plans/ or docs/solutions/ are never executed: those directories are intentional pipeline artifacts (resolve mode closes them as won't-fix).