agentleFS
jsvillalbatjsvillalbat/sevito-skills/skills/file-todos/SKILL.md

file-todos

Skill0 starsChanged 3 months agoMITView on GitHub

Tracks review findings and work items as individual markdown files whose filename encodes lifecycle state — {id}-{status}-{priority}-{description}.md, status pending to ready to complete — so the queue is visible with plain `ls`, survives crashes, and needs no database. Use when findings need to persist and be triaged across sessions rather than fixed immediately, or when items should be reviewed one at a time and then fixed independently, possibly in parallel.

4 other projects use a version of this.

Adopted by

Most recently taken up by

The file

Files
SKILL.md

File TODOs

A backlog that only lives in chat history disappears when the session ends. This skill stores each item as its own markdown file with the lifecycle state baked into the filename, so the queue is inspectable with ls, greppable, diffable, and survives a crash mid-triage without losing state.

When to use this

  • A batch of findings (a code review, a bug bash, an audit) that shouldn't all be fixed immediately and need triage first.
  • Work items should persist across sessions, not just this conversation.
  • Multiple items need to be worked through independently, possibly in parallel, by whoever/whatever picks them up next.
  • Don't use this for an immediate one-off fix — just fix it. Creating a todo file for something you're about to fix in the next two minutes is pure ceremony.

Instructions

Directory and filename convention

Store items under todos/, one file per item:

todos/{id}-{status}-{priority}-{description}.md
  • id — a short, stable identifier (an incrementing number is simplest, e.g. 007) so renames never collide.
  • status — one of pending (needs triage) → ready (approved, queued for work) → complete (resolved and verified).
  • priority — p1 (critical/blocking) through p3 (nice-to-have).
  • description — a short kebab-case slug.

Example: 007-pending-p1-race-condition-in-cache.md. Moving between states is a filename rename (status segment only) — the file's content and id stay put.

File content

Each file must be fully self-contained — anyone picking it up later (including a fresh agent with none of this session's context) needs everything in the file, not in someone's memory. Use references/template.md: Problem, Evidence, Proposed fix, Priority rationale.

Triage: pending → ready

Go through pending files one at a time, not a batch skim. For each, decide:

  • Ready — valid, worth fixing → rename status to ready.
  • Dismiss — not worth it, duplicate, or won't-fix → delete the file, or rename to a dismissed status with a one-line reason added to the file first.

This is a deliberate gate: nothing enters the work queue without individual judgment. Skipping straight from pending to complete defeats the point of triage.

Resolve: ready → complete

ready files can be picked up in any order, independently, possibly by parallel workers — each is self-contained by design. For each:

  1. Fix it.
  2. Verify the fix — actually confirm it per verify-before-done's evidence ladder, don't just mark it complete because a plausible-looking change was made.
  3. Rename status to complete.

Checking status at a glance

ls todos/ | sort              # id-ordered view of the whole queue
ls todos/*-pending-*          # what still needs triage
ls todos/*-ready-p1-*         # what's queued and critical

Reference files

  • references/template.md — the blank todo-file template.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.