task

name	task
description	Task management system for tracking work across nested projects with TODO.md files

Task Management Skill

This skill helps agents understand and work with the task management system.

Overview

The task management system tracks work using TODO.md and COMPLETED.md files across nested projects:

• Each subproject can have its own TODO.md
• Cross-project tasks go in the root TODO.md
• Sequential IDs across all projects (1, 2, 3, ...)

File Structure

project/
├── TODO.md              # Cross-project tasks
├── COMPLETED.md         # Cross-project completed
├── cli/
│   ├── TODO.md         # CLI-specific tasks
│   └── COMPLETED.md    # CLI completed
└── .opencode/skills/task/
    ├── SKILL.md        # This file
    └── scripts/
        ├── list-tasks.sh
        ├── complete-task.sh
        ├── update-task.sh
        ├── validate-todos.py
        └── regenerate-qr.sh

Task Format

Each task uses strict formatting with markers:

<!-- TASK:123 -->
### 123. Task Title
| Field | Value |
|-------|-------|
| **id** | 123 |
| **status** | pending | in_progress | blocked | complete |
| **priority** | critical | high | medium | low |
| **created** | 2026-02-08 |

**Description**
Task description here.
<!-- END TASK:123 -->

Available Scripts

All scripts are in .opencode/skills/task/scripts/:

Script	Purpose
list-tasks.sh	List all active tasks with priority sorting
list-tasks.sh --include-completed	List all tasks including completed
complete-task.sh <id>	Mark task complete and move to COMPLETED.md
update-task.sh <id> --status <v>	Update task status
update-task.sh <id> --priority <v>	Update task priority
update-task.sh <id> --title <v>	Update task title
validate-todos.py	Validate all TODO.md formatting
regenerate-qr.sh <file>	Regenerate Quick Reference table
regenerate-qr.sh --all	Regenerate all Quick References

When to Use

Use this skill when the user asks about:

• Listing tasks
• Creating new tasks
• Completing tasks
• Updating task status/priority
• Validating TODO.md files
• Understanding the task system

Creating a New Task

1. Run list-tasks.sh to find the next available ID
2. Determine the correct TODO.md file (root for cross-project, subdirectory for specific)
3. Add task with proper format (see Task Format above)
4. Run regenerate-qr.sh <file> to update Quick Reference
5. Run validate-todos.py to verify

Completing a Task

Always use the script:

.opencode/skills/task/scripts/complete-task.sh <task-id>

This will:

• Find the task in TODO.md files
• Update status to complete
• Add completion date
• Move to appropriate COMPLETED.md
• Regenerate Quick Reference
• Validate the result

Common Status Values

• pending - Not started
• in_progress - Currently being worked on
• blocked - Waiting on something else
• complete - Done (use complete-task.sh to set)

Common Priority Values

• critical - Urgent, blocking
• high - Important
• medium - Normal priority
• low - Nice to have