tasklist-conventions

# TaskList Conventions

## Overview

TaskList is a built-in Claude Code feature for tracking task execution. Tasks are stored in `~/.claude/tasks/[session-uuid]/` and can be shared across sessions using the `import-tasks` skill.

This skill documents conventions for using TaskList tools effectively. For importing tasks from another session, see the `import-tasks` skill.

## When to Use TaskList

**Use TaskList when:**
- Executing a plan with multiple steps
- Tracking dependencies between work items
- Coordinating work across multiple sessions or subagents
- Progress needs to be visible and trackable
- Work items have clear completion criteria

**Consider file-todos instead when:**
- Findings need detailed documentation (Problem Statement, Findings, Solutions)
- Work items need to be committed to the repository
- Team visibility is important
- Rich context with work logs is needed

**Use both when:**
- Review findings need documentation (file-todos) AND execution tracking (TaskList)
- Plan implementation needs progress tracking AND permanent record

## Built-in Tools

| Tool | Purpose |
|------|---------|
| `TaskCreate` | Create a new task with subject, description, activeForm |
| `TaskUpdate` | Update status, add dependencies, modify tasks |
| `TaskList` | View all tasks with status and blockers |
| `TaskGet` | Get full details of a specific task |

## Task Fields

**Required fields:**
- `subject`: Brief, actionable title in imperative form ("Implement user model")
- `description`: Detailed description of what needs to be done

**Recommended fields:**
- `activeForm`: Present continuous form shown in spinner ("Implementing user model")

**Set via TaskUpdate:**
- `status`: `pending` → `in_progress` → `completed`
- `addBlockedBy`: Task IDs that must complete before this task
- `addBlocks`: Task IDs that this task blocks

## Conventions

### Task Subjects

Use imperative form (like git commits):
- ✅ "Implement user authentication"
- ✅ "Add validation for email field"
-