--- 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 ` | Run `scripts/complete-task.sh ` | | `/task update [--status ] [--priority ] [--title ]` | Run `scripts/update-task.sh [flags]` | | `/task show ` | 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: ```markdown ### 123. Task Title | Field | Value | |-------|-------| | **id** | 123 | | **status** | in_progress | | **priority** | high | **Description** Task description here. ``` **Rules:** - Opening marker: `` - Closing marker: `` - One blank line before opening marker - Content between markers is the task body ### Metadata Table (MANDATORY) All tasks MUST have this exact table format: ```markdown | 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) ```markdown **Description** Task description goes here. Can be multiple lines. ``` ### Optional Sections ```markdown **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. ```markdown ## 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 ```markdown # [Project] Tasks *Active tasks only. See [COMPLETED.md](./COMPLETED.md) for history.* **Quick Links**: [Active Tasks](#quick-reference) | [Completed Tasks](./COMPLETED.md) --- ## Quick Reference | ID | Title | Status | Priority | |----|-------|--------|----------| --- ## Tasks ``` ### COMPLETED.md Template ```markdown # Completed Tasks - [Project] **Stats**: 47 total | [Current Year]: 12 --- ## Current Month (2026-02) --- ## Previous Months ### 2026-01 ## 2025 ### 2025-12 ``` --- ## 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): ```bash .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: ```markdown ### 126. Task Title | Field | Value | |-------|-------| | **id** | 126 | | **status** | pending | | **priority** | high | | **created** | 2026-02-08 | **Description** Task description here. ``` 4. Regenerate Quick Reference: ```bash .claude/skills/task-management/scripts/regenerate-qr.sh cli/TODO.md ``` 5. Validate: ```bash .claude/skills/task-management/scripts/validate-todos.py ``` ### Completing a Task (USE THE SCRIPT) **ALWAYS use the completion script** - never manually move tasks: ```bash .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: ```bash .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 `` has matching `` 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: ```bash .claude/skills/task-management/scripts/validate-todos.py ``` With verbose output: ```bash .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 ` | Mark task complete and move to COMPLETED.md | | `update-task.sh [--status ] [--priority ] [--title ]` | Update task fields in TODO.md | | `validate-todos.py` | Validate all TODO.md files | | `regenerate-qr.sh ` | Regenerate Quick Reference for one file | | `regenerate-qr.sh --all` | Regenerate all Quick References | --- ## Common Issues ### "Task boundary mismatch" A `` marker doesn't have a matching ``. 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 ```

task

Scan your own AI components