mcpField
F
file-todos

file-todos

github.com/iliaalProductivity45143 installsUpdated 5d ago
Repository

About file-todos

file-todos is a file-based task-tracking skill for developers and agents. It organizes project work in Markdown files using statuses, priorities, and dependencies.

Key features

  1. 01Filename convention for ID, status, and priority
  2. 02YAML metadata for todo files
  3. 03Sections for problems and acceptance criteria
  4. 04Validation of IDs and status fields

Use cases

  1. 01Track development tasks and dependencies
  2. 02Record pending, approved, and completed work

Install

Copy the command and run it in a terminal.

$npx skills add https://github.com/iliaal/ai-skills --skill file-todos

After installing, type/file-todosin Claude Code to confirm it loaded.

Bundled files

References and scripts installed along with SKILL.md.

SPEC.md
agents/
openai.yaml
assets/
todo-template.md
references/
quick-reference.md
workflows.md

Details

From the project README

File-based todo tracking

File naming convention

{issue_id}-{status}-{priority}-{description}.md
  • issue_id: Sequential number (001, 002, 003...) -- never reused
  • status: pending (needs triage), ready (approved), complete (done)
  • priority: p1 (critical), p2 (important), p3 (nice-to-have). Mapping from the ia-code-review severity scale: Critical→p1, Important→p2, Medium→p3, Minor→p3.
  • description: kebab-case, brief description

Examples: 001-pending-p1-mailer-test.md, 002-ready-p1-fix-n-plus-1.md, 005-complete-p2-refactor-csv.md

File Structure

Use todo-template.md as a starting point. YAML frontmatter:

---
status: ready              # pending | ready | complete
priority: p1               # p1 | p2 | p3
issue_id: "002"
tags: [typescript, performance, database]
dependencies: ["001"]      # Issue IDs this is blocked by
---

Required sections: Problem Statement, Findings, Proposed Solutions, Recommended Action, Acceptance Criteria, Work Log

Optional sections: Technical Details, Resources, Notes

Key Distinctions

File-todos system (this skill): Markdown files in todos/ directory for development/project tracking. Used by humans and agents.

Application Todo model: Database model for user-facing task management. Different from this file-based system.

TodoWrite tool: In-memory task tracking during agent sessions. Temporary, not persisted to disk.

Verify

Before considering a todo file correctly written, confirm:

  • issue_id is unique and sequentially the next number in todos/ (never reused).
  • All required frontmatter fields are present: status, priority, issue_id.
  • status and priority values match the filename and their enums (pending|ready|complete, p1|p2|p3).

References

Comments

Markdown supported