file-todos

salavender's avatarfrom salavender

Manage file-based todo tracking in the todos/ directory

⭐29stars🔀7forks📁View on GitHub🕐Updated Dec 27, 2025
[Project Management]

When & Why to Use This Skill

The file-todos skill is a specialized task management system designed for developers and power users who prefer a 'tasks-as-code' approach. It enables efficient tracking of work items directly within a project's directory using markdown files. By leveraging structured naming conventions, YAML frontmatter for metadata, and dependency tracking, it provides a lightweight yet powerful alternative to heavy project management software, allowing for version-controlled task history and CLI-integrated workflows.

Use Cases

  • 1. Repository-Integrated Task Tracking: Manage software bugs, feature requests, and technical debt directly within the codebase, ensuring that task updates are committed and versioned alongside code changes.
  • 2. Dependency-Aware Workflow Management: Handle complex projects by defining blockers and dependencies between tasks using YAML metadata, allowing for clear visualization of the critical path.
  • 3. Automated Triage and Reporting: Use shell-based commands and scripts to programmatically filter tasks by priority, count items by status, and automate the lifecycle transition from pending to complete.
  • 4. Local-First Productivity: Maintain a high-performance, offline-capable todo list that integrates seamlessly with terminal-based editors and developer environments.
namefile-todos
descriptionManage file-based todo tracking in the todos/ directory

File-Based Todo Tracking

Provides workflows for creating, managing, and completing todos stored as markdown files.

Overview

The todos/ directory contains markdown files with YAML frontmatter for tracking work items.

File Naming Convention

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

Examples:
001-pending-p1-security-fix.md
002-ready-p2-performance-opt.md
003-complete-p3-cleanup.md

Status Lifecycle

pending → ready → complete
   ↓
(deleted if skipped)

What do you want to do?

  1. Create a todo → See "Creating Todos" below
  2. Triage pending items → Use /triage
  3. Work on todos → Use /resolve_todo
  4. Check dependencies → See "Dependency Management" below

Instrumentation

# Log usage when using this skill
./scripts/log-skill.sh "file-todos" "manual" "$$"

Creating Todos

# Get next ID
next_id=$(ls todos/*.md 2>/dev/null | grep -o '[0-9]\+' | sort -n | tail -1 | awk '{printf "%03d", $1+1}')
[ -z "$next_id" ] && next_id="001"

# Copy template
cp todos/todo-template.md todos/${next_id}-pending-{priority}-{description}.md

Dependency Management

# In YAML frontmatter
dependencies: ["001", "002"]  # Blocked by these issues
dependencies: []               # No blockers

Check blockers:

grep "dependencies:" todos/{file}.md

Quick Commands

# List by status
ls todos/*-pending-*.md
ls todos/*-ready-*.md
ls todos/*-complete-*.md

# List by priority
ls todos/*-p1-*.md

# Count by status
for s in pending ready complete; do
  echo "$s: $(ls todos/*-$s-*.md 2>/dev/null | wc -l)"
done