task-list-md
Parse and manage tasks list in a markdown file using checklist format (tasks.md, checklist.md)
When & Why to Use This Skill
The task-list-md skill is a robust CLI-based utility designed to transform standard Markdown files into dynamic, hierarchical task management systems. It solves the problem of tracking complex project progress within documentation by providing automated status updates, dependency validation, and detailed progress statistics. By supporting nested task structures and time-bound tracking conditions, it allows developers and project managers to maintain a single source of truth for their workflows without leaving their text-based environment.
Use Cases
- Managing complex software development roadmaps where tasks have strict hierarchical relationships and technical dependencies.
- Automating progress reporting for open-source projects by parsing 'tasks.md' files to generate completion percentages and status histories.
- Implementing time-bound sprint goals by setting expiration conditions on specific task IDs to ensure timely delivery.
- Identifying 'ready-to-work' tasks in large backlogs by filtering for pending items whose dependencies have all been satisfied.
- Exporting project metadata to JSON format for integration with external dashboarding tools or custom reporting scripts.
| name | task-list-md |
|---|---|
| description | Parse and manage tasks list in a markdown file using checklist format (tasks.md, checklist.md) |
task-list-md
Task List MD CLI (scripts/task_list_md.py) parses hierarchical checklists, maintains task metadata, and tracks progress for markdown task files.
Status Mapping
[ ]→pending(yellow)[-]→in-progress(blue)[x]→done(green)[+]→review(cyan)[*]→deferred(red)
Progress Tracking
- Persists statistics in
.tasks.local.json(auto-created next to the CLI). - Records totals, completion percentage, per-task history, and optional tracking conditions.
- Status changes automatically append timestamped history entries.
File Resolution
- Every command accepts an optional
fileargument. If omitted, the CLI auto-selects the most recently modified entry from.tasks.local.jsonand echoes the selection. - The parser detects misplaced file paths in other arguments (for example, if a path is passed instead of
task_id) and reassigns them tofile.
Task Identifiers
- IDs must be digits with optional dot-separated hierarchy:
1,2.1,3.2.4, etc. - Parent/child relationships are inferred from dot notation; indentation in the markdown follows the same hierarchy.
Command Reference
list-tasks
python3 scripts/task_list_md.py list-tasks [file]
- Prints all tasks in hierarchical order with colored statuses when supported by the terminal.
- Shows descriptions, requirements, dependencies, and nested structure.
show-task
python3 scripts/task_list_md.py show-task [file] <task_id>
- Displays the specified task plus its sub-tasks, requirements, dependencies, and status history.
- Requires a valid task ID.
set-status
python3 scripts/task_list_md.py set-status [file] <task_id1> [task_id2 ...] <status>
- Updates one or many tasks to
pending,in-progress,done,review, ordeferred. - Enforces hierarchy rules: sub-tasks cannot move from
pendingwhile their parent ispendingordone. - Automatically updates parent tasks when all sub-tasks share the same status.
- Records status transitions in
.tasks.local.json.
add-task
python3 scripts/task_list_md.py add-task [file] <task_id> "<description>" [--dependencies dep1 dep2 ...] [--requirements req1 req2 ...]
- Creates a new pending task inserted in ID order.
- Validates uniqueness of
task_idand existence of referenced dependency IDs. - Optional
_Requirements:_and_Dependencies:_lines are written under the task.
update-task
python3 scripts/task_list_md.py update-task [file] <task_id> [--add-dependencies dep ...] [--add-requirements req ...] [--remove-dependencies dep ...] [--remove-requirements req ...] [--clear-dependencies] [--clear-requirements]
- Modifies dependency and requirement lists in place.
--clear-*cannot be combined with the corresponding--add-*or--remove-*flags.- Rewrites the markdown block for the task and refreshes cached statistics.
delete-task
python3 scripts/task_list_md.py delete-task [file] <task_id1> [task_id2 ...]
- Removes the specified tasks and any nested sub-tasks.
- Refuses to delete when other tasks (not in the deletion list) depend on the target.
get-next-task
python3 scripts/task_list_md.py get-next-task [file] [--wait DURATION]
- Suggests the next actionable task from PENDING tasks only (excludes IN_PROGRESS tasks)
- Honors dependencies and parent constraints
- Prefers sub-tasks when the parent is
in-progress - Surfaces context (dependencies, parent, sub-tasks)
- Distinguishes between two scenarios:
- "All tasks have been completed!" - when all tasks are done/review
- "No tasks available to work on..." - when tasks exist but are blocked or in-progress/deferred
- Optional
--wait DURATIONparameter:- Waits for specified duration when no task is available
- Duration format:
30(30 minutes),30m(30 minutes),2h(2 hours),90s(90 seconds) - Units:
sfor seconds,mfor minutes,hfor hours (defaults to minutes if no unit specified) - Periodically checks for available tasks (every 10 seconds)
- Automatically reloads task file to detect status changes
- Examples:
--wait 30m,--wait 2h,--wait 120s
check-dependencies
python3 scripts/task_list_md.py check-dependencies [file]
- Validates that every dependency exists, is not self-referential, and does not create circular relationships.
- Lists violations or confirms success.
show-progress
python3 scripts/task_list_md.py show-progress [file]
- Refreshes statistics, then prints totals, completion percentages, status counts, last-modified timestamp, and per-task status history.
filter-tasks
python3 scripts/task_list_md.py filter-tasks [file] [--status STATUS] [--requirements req ...] [--dependencies dep ...]
- Returns tasks matching all provided filters.
--requirementsand--dependenciesrequire tasks to include every supplied value.
search-tasks
python3 scripts/task_list_md.py search-tasks [file] <keyword1> [keyword2 ...]
- Case-insensitive search across task IDs, descriptions, requirements, dependencies, and captured content.
- Maintains hierarchy in the output for readability.
ready-tasks
python3 scripts/task_list_md.py ready-tasks [file]
- Lists pending tasks whose dependencies are all complete (
doneorreview). - Excludes sub-tasks whose parent is still
pendingor alreadydone.
export
python3 scripts/task_list_md.py export [file] [--output output.json]
- Emits a JSON document containing statistics, task metadata, hierarchy, and status history.
- Writes to
stdoutwhen--outputis omitted, enabling piping to other tooling.
track-progress
Manage time-bound completion conditions stored in .tasks.local.json.
track-progress add
python3 scripts/task_list_md.py track-progress add [file] <task_id1> [task_id2 ...] [--valid-for DURATION] [--complete-more N]
- Creates a tracking condition with an expiration.
--valid-foraccepts integers (seconds) or values ending withh,m, ors(default2h).--complete-moreexpects an integer that adds to the current completed count; the CLI validates it against the total tasks.
track-progress check
python3 scripts/task_list_md.py track-progress check [file]
- Evaluates all active conditions and reports unmet tasks or completion targets to stderr.
- Exit codes:
0when all conditions are satisfied,2when conditions remain unmet, and1for errors.
track-progress clear
python3 scripts/task_list_md.py track-progress clear [file] [--yes]
- Clears every stored condition after confirmation.
- Use
--yesto skip the interactive prompt (helpful in scripted environments).
Examples
is the path to the markdown file contain the task list
Basic Usage:
- python3 scripts/task_list_md.py list-tasks
- python3 scripts/task_list_md.py show-task
- python3 scripts/task_list_md.py set-status [task_id2...]
- python3 scripts/task_list_md.py get-next-task
- python3 scripts/task_list_md.py check-dependencies
- python3 scripts/task_list_md.py show-progress
Task Management:
- python3 scripts/task_list_md.py add-task "" [--dependencies dep1 dep2] [--requirements req1 req2]
- python3 scripts/task_list_md.py update-task [--add-dependencies dep1 dep2] [--add-requirements req1 req2] [--remove-dependencies dep1] [--remove-requirements req1] [--clear-dependencies] [--clear-requirements]
- python3 scripts/task_list_md.py delete-task [task_id2...]
Advanced Filtering & Search:
- python3 scripts/task_list_md.py filter-tasks [--status pending] [--requirements req1] [--dependencies dep1]
- python3 scripts/task_list_md.py search-tasks keyword1 [keyword2...]
- python3 scripts/task_list_md.py ready-tasks
Export:
- python3 scripts/task_list_md.py export [--output filename.json]
Importance
Replace the script path scripts/task_list_md.py with ${CLAUDE_PLUGIN_ROOT}/skills/task-list-md/scripts/task_list_md.py when execute script in this skill.