Todo List

Purpose

Display a summary of all active todos, sorted by priority and due date, with options to take action on specific items.

Execution Flow

Phase 1: Locate Todos Directory

• Search for Todos/ directory in the current working directory or its parents

• Check Todos/active/ for todo files

• If not found: "No Todos directory found. You can create one using /todo-add."

Phase 2: Read Active Todos

Use Glob to find all .md files in Todos/active/ :

Todos/active/*.md

(Exclude README.md)

For each todo file, read and parse frontmatter:

• title

• status

• priority

• due_date

• created_at

• source_file

• dependencies

Phase 3: Sort Todos

Sort order (primary to tertiary):

• Priority: high → medium → low

• Due Date: overdue → today → this week → later → no date

• Created Date: oldest first (to surface forgotten items)

Phase 4: Format Output

Display as formatted table:

Active Todos

Summary

• Total: 3 active todos
• High Priority: 1
• Overdue: 0
• Blocked: 0 (dependencies not met)

Overdue Items

(none)

Due Today

(none)

Due This Week

• Reply to client email (2025-01-15)

Phase 5: Display Status Legend

Status:

• pending: Not started
• in_progress: Currently working on
• blocked: Waiting for dependencies

Priority:

• 🔴 High: Urgent/time-sensitive
• 🟡 Medium: Normal priority
• 🟢 Low: When time permits

Phase 6: Offer Actions

Ask user what they want to do next:

{ "question": "What would you like to do?", "header": "Actions", "options": [ {"label": "View details of a todo", "description": "Read the full content of a specific todo"}, {"label": "Mark a todo complete", "description": "Complete and archive a todo"}, {"label": "Update a todo", "description": "Change priority, due date, or status"}, {"label": "Nothing, just viewing", "description": "Close this view"} ], "multiSelect": false }

If user selects an action, follow up with todo selection:

{ "question": "Which todo?", "header": "Select Todo", "options": [ {"label": "#1 Reply to client email", "description": "High priority, due 2025-01-15"}, {"label": "#2 Review design docs", "description": "Medium priority, in progress"}, {"label": "#3 Update documentation", "description": "Low priority, no deadline"} ], "multiSelect": false }

Output Formats

Standard View (default)

Table format as shown above.

Compact View

If there are many todos (>10):

Active Todos (15 items)

🔴 High Priority (3)

1. Reply to client email - due 2025-01-15
2. Fix critical bug - due today ⚠️
3. Submit report - overdue ❌

🟡 Medium Priority (7)

4. Review design docs - in progress
5. Update API docs ...

🟢 Low Priority (5)

12. Refactor utils ...

Blocked Items

If any todos have unmet dependencies:

⏸️ Blocked Todos

• Prepare client presentation (blocked) Waiting for: Review design docs, Get approval

Empty State

If no active todos:

Active Todos

No active todos! 🎉

You can:

• Add a new todo with /todo-add
• Check completed todos in Todos/completed/

Error Handling

Corrupted Frontmatter

If a todo file has invalid frontmatter:

• Log warning: "Warning: [filename] has invalid frontmatter"

• Skip the file in listing

• Mention at the end: "1 todo file could not be parsed"

Missing Directory

If Todos/active/ doesn't exist but Todos/ does:

• Offer to create the directory structure

• Or report "No active todos found"