---

name: task description: Manage tasks across nested projects. Use with /task list, /task complete [id], /task update [id], /task show [id], /task validate. argument-hint: [list|list-all|complete|update|show|validate|new] [task-id]

Task Management

This skill provides task tracking across nested projects with strict formatting for reliable automation.

Arguments received: $ARGUMENTS

---

Slash Command Routing

Based on the argument, run the appropriate action:

Command	Action
/task or /task list	Run scripts/list-tasks.sh and copy output into response
/task list-all	Run scripts/list-tasks.sh --include-completed and copy output into response
/task complete <id>	Run scripts/complete-task.sh <id>
/task update <id> [--status <v>] [--priority <v>] [--title <v>]	Run scripts/update-task.sh <id> [flags]
/task show <id>	Read the task from the appropriate TODO.md or COMPLETED.md
/task validate	Run scripts/validate-todos.py
/task new	Follow the "Creating a New Task" workflow below

All script paths are relative to .claude/skills/task-management/.

⛔ NEVER during list commands:

• Run validation checks
• Fix TODO.md files
• Add extra summaries after the script output

---

File Structure

Each project has two files:

File	Purpose	Edit By
TODO.md	Active tasks only	Scripts + manual
COMPLETED.md	Completed tasks only	complete-task.sh script only

---

Strict Format Specification

Task Boundaries (MANDATORY)

Every task is wrapped in explicit markers:

<!-- TASK:123 -->
### 123. Task Title
| Field | Value |
|-------|-------|
| **id** | 123 |
| **status** | in_progress |
| **priority** | high |

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

Rules:

• Opening marker: <!-- TASK:{id} -->
• Closing marker: <!-- END TASK:{id} -->
• One blank line before opening marker
• Content between markers is the task body

Metadata Table (MANDATORY)

All tasks MUST have this exact table format:

| Field | Value |
|-------|-------|
| **id** | 123 |
| **status** | pending | in_progress | blocked | complete |
| **priority** | critical | high | medium | low |
| **created** | 2026-02-08 |

Allowed Values (STRICT):

Field	Allowed Values
status	pending, in_progress, blocked, complete
priority	critical, high, medium, low

NO synonyms, NO emojis in data values.

Description Section (MANDATORY)

**Description**
Task description goes here. Can be multiple lines.

Optional Sections

**Notes**
Additional notes.

**Files**
- `path/to/file.rs`
- `path/to/other.rs`

**Depends On**
- Task 45
- Task 67

**Acceptance Criteria**
- [ ] Criterion one
- [ ] Criterion two

---

Quick Reference Section (AUTO-GENERATED)

The Quick Reference table is generated by scripts, never edited manually.

## Quick Reference

| ID | Title | Status | Priority |
|----|-------|--------|----------|
| 122 | Contact Import | 🟡 In Progress | 🟠 High |
| 123 | Profile Export | 📋 Pending | 🟡 Medium |

*Auto-generated. Last updated: 2026-02-08T15:30:00Z*

Status Emojis (rendering only):

• pending → 📋
• in_progress → 🟡
• blocked → 🚫
• complete → ✅

Priority Emojis (rendering only):

• critical → 🔴
• high → 🟠
• medium → 🟡
• low → 🟢

---

File Header Template

TODO.md Template

<!--
TODO.md - Active Tasks for [Project]

⚠️ IMPORTANT: This file uses strict formatting. See:
  .claude/skills/task-management/SKILL.md

Generated sections are marked - DO NOT EDIT MANUALLY.
-->

# [Project] Tasks

*Active tasks only. See [COMPLETED.md](./COMPLETED.md) for history.*

**Quick Links**: [Active Tasks](#quick-reference) | [Completed Tasks](./COMPLETED.md)

---

## Quick Reference

<!-- QR-START (AUTO-GENERATED - DO NOT EDIT) -->
| ID | Title | Status | Priority |
|----|-------|--------|----------|

<!-- QR-END -->

---

## Tasks

<!-- TASKS-START -->

<!-- Put new tasks here -->

<!-- TASKS-END -->

COMPLETED.md Template

<!--
COMPLETED.md - Completed Tasks for [Project]

⚠️ IMPORTANT: This file is APPEND-ONLY at the top.
Newest completed tasks go in "## Current Month" section.
See SKILL.md for completion workflow.
-->

# Completed Tasks - [Project]

**Stats**: 47 total | [Current Year]: 12

---

## Current Month (2026-02)

<!-- New completed tasks go HERE (at the top) -->

---

## Previous Months

### 2026-01

<!-- Completed tasks from January -->

## 2025

### 2025-12

<!-- Completed tasks from December 2025 -->

---

Task ID System

• Sequential IDs: Start at 1, increment across ALL subprojects
• No ranges: IDs are simply sequential (1, 2, 3, 49, 50, etc.)
• Cross-project: Task 1 in one folder and Task 2 in another - IDs are unique across all projects
• Never reuse: If task 5 is deleted, next task is 6 (not 5)

---

User Commands

Command	Action
/task or /task list	Run scripts/list-tasks.sh
/task list-all	Run scripts/list-tasks.sh --include-completed
/task show 51	Read task from appropriate TODO.md
/task complete 51	Run scripts/complete-task.sh 51
/task update 51 --status in_progress	Run scripts/update-task.sh 51 --status in_progress
/task validate	Run scripts/validate-todos.py
/task new	Create a new task using the workflow below

---

Workflows

Creating a New Task

1. Find the next available task ID (shown at the bottom of list output):

   .claude/skills/task-management/scripts/list-tasks.sh
   

2. Determine the correct file:

   • Single-project task → cli/TODO.md, contracts/TODO.md, etc.
   • Cross-project task (spans 2+ projects) → Root TODO.md

3. Add task with proper format:

   <!-- TASK:126 -->
   ### 126. Task Title
   | Field | Value |
   |-------|-------|
   | **id** | 126 |
   | **status** | pending |
   | **priority** | high |
   | **created** | 2026-02-08 |
   
   **Description**
   Task description here.
   <!-- END TASK:126 -->
   

4. Regenerate Quick Reference:

   .claude/skills/task-management/scripts/regenerate-qr.sh cli/TODO.md
   

5. Validate:

   .claude/skills/task-management/scripts/validate-todos.py
   

Completing a Task (USE THE SCRIPT)

ALWAYS use the completion script - never manually move tasks:

.claude/skills/task-management/scripts/complete-task.sh 122

This script will:

1. Find task 122 in TODO.md files
2. Update status to complete
3. Add completed date field
4. Move task to appropriate COMPLETED.md (top of current month)
5. Remove from TODO.md
6. Regenerate Quick Reference
7. Validate the result

Why use the script?

• Ensures consistent formatting
• Prevents mistakes in date formats
• Maintains proper ordering in COMPLETED.md
• Keeps Quick Reference in sync

Updating a Task

ALWAYS use the update script - never manually edit task metadata:

.claude/skills/task-management/scripts/update-task.sh 3 --status in_progress
.claude/skills/task-management/scripts/update-task.sh 7 --priority critical --title "Urgent fix"

This script will:

1. Find the task in TODO.md files
2. Validate the new field values
3. Apply updates (status, priority, and/or title)
4. Show before/after for changed fields
5. Regenerate Quick Reference
6. Validate the result

Note: To mark a task as complete, use complete-task.sh instead.

---

Task Location Rules

File	What Goes Here
Root TODO.md	Cross-project tasks only (spans 2+ subprojects)
cli/TODO.md	CLI-only tasks
contracts/TODO.md	Contract-only tasks
discovery/TODO.md	Discovery service tasks

If a task is in the wrong file:

• Move it to the correct file
• Run regenerate-qr.sh on both files
• Run validate-todos.py to verify

---

Validation Script

The validation script checks:

1. Task boundaries: Every <!-- TASK:{id} --> has matching <!-- END TASK:{id} -->
2. Required fields: Every task has id, status, priority, description
3. Enum values: status and priority use allowed values only
4. ID uniqueness: No duplicate task IDs across all files
5. ID matching: Task marker ID matches metadata table ID
6. QR section: Quick Reference markers are present
7. No completed in TODO: Tasks with status: complete are in COMPLETED.md
8. QR accuracy: Quick Reference contains all active tasks, no extras

Run validation:

.claude/skills/task-management/scripts/validate-todos.py

With verbose output:

.claude/skills/task-management/scripts/validate-todos.py --verbose

---

Script Reference

Script	Purpose
list-tasks.sh	List all active tasks
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>] [--priority <v>] [--title <v>]	Update task fields in TODO.md
validate-todos.py	Validate all TODO.md files
regenerate-qr.sh <file>	Regenerate Quick Reference for one file
regenerate-qr.sh --all	Regenerate all Quick References

---

Common Issues

"Task boundary mismatch"

A <!-- TASK:{id} --> marker doesn't have a matching <!-- END TASK:{id} -->. Check the task formatting.

"Missing required field"

The metadata table is missing id, status, priority, or description. Add the missing field.

"Invalid status value"

Status must be exactly: pending, in_progress, blocked, or complete. No spaces, no emojis, no variations.

"Duplicate task ID"

The same ID exists in multiple files. Tasks must have unique IDs across all projects.

"Completed task in TODO.md"

A task with status: complete is still in a TODO.md file. Run complete-task.sh to move it to COMPLETED.md.

---

File Organization

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