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"
✅ "Write integration tests"
❌ "Implementing authentication" (use for activeForm)
❌ "User auth" (too vague)

ActiveForm

Use present continuous for progress visibility:

Subject: "Run database migrations"
ActiveForm: "Running database migrations"

Status Workflow

pending → in_progress → completed

pending: Task created, not yet started
in_progress: Currently being worked on
completed: Work finished and verified

Dependencies

Set dependencies when tasks must complete in order:

TaskCreate: "Implement User model" → #1
TaskCreate: "Add authentication service" → #2
TaskCreate: "Write integration tests" → #3

TaskUpdate: #2 addBlockedBy [#1]  # Service needs model
TaskUpdate: #3 addBlockedBy [#1, #2]  # Tests need both

Task Granularity

Good tasks are:

Completable in a focused session (1-4 hours of work)
Specific enough to know when done
Independent or with clear dependencies
Verifiable (you can confirm completion)

Examples:

✅ "Implement UserService.authenticate method"
✅ "Add unit tests for password validation"
❌ "Do the backend" (too vague)
❌ "Fix everything" (not specific)

Creating Tasks from a Plan

When executing a plan, create tasks for each major work item:

# From plan acceptance criteria:
# - [ ] User model with email, password_hash
# - [ ] Authentication service with JWT
# - [ ] Login/logout endpoints
# - [ ] Integration tests

TaskCreate:
  subject: "Implement User model"
  description: "Create User model with email, password_hash fields. Add validations and password hashing."
  activeForm: "Implementing User model"

TaskCreate:
  subject: "Add authentication service"
  description: "Create AuthService with JWT token generation. Implement authenticate() and verify() methods."
  activeForm: "Adding authentication service"

# Set dependency - service needs model
TaskUpdate: #2 addBlockedBy [#1]

Creating Tasks from Review Findings

When review findings need execution tracking:

# From synthesized review findings:
# - P1: SQL injection in search endpoint
# - P2: N+1 query in user listing
# - P3: Unused import in helpers

TaskCreate:
  subject: "Fix SQL injection in search endpoint"
  description: "Parameterize query in SearchController#index. See todos/001-pending-p1-sql-injection.md"
  activeForm: "Fixing SQL injection vulnerability"

TaskCreate:
  subject: "Resolve N+1 query in user listing"
  description: "Add includes(:posts) to User.all query. See todos/002-pending-p2-n-plus-one.md"
  activeForm: "Resolving N+1 query"

Link tasks to file-todos for full context.

Execution Loop

Standard pattern for working through tasks:

while TaskList shows pending tasks:
  # 1. Check available work
  TaskList  # Shows tasks with status and blockers

  # 2. Claim next unblocked task
  TaskUpdate: #X status=in_progress

  # 3. Execute the work
  # ... implementation ...

  # 4. Mark complete
  TaskUpdate: #X status=completed

Cross-Session Coordination

Getting TaskList ID

After creating tasks, get the session UUID:

task_list_id=$(ls -t ~/.claude/tasks/ | head -1)
echo "TaskList ID: $task_list_id"

Including in Plan Files

Add to YAML frontmatter for later import:

---
title: Add user authentication
type: feat
date: 2026-01-24
task_list_id: a69ce44f-1559-4052-89e2-66605323adca
---

Importing in Another Session

Use the import-tasks skill:

skill: import-tasks a69ce44f-1559-4052-89e2-66605323adca

Parallel Subagent Execution

Multiple agents can work on the same TaskList:

# Main session creates tasks
TaskCreate: "Task A" → #1
TaskCreate: "Task B" → #2
TaskCreate: "Task C" → #3

# Get TaskList ID
task_list_id=$(ls -t ~/.claude/tasks/ | head -1)

# Spawn subagents
Task(python-coder): "Import tasks from $task_list_id, work on #1"
Task(python-coder): "Import tasks from $task_list_id, work on #2"

Subagents:

Import using skill: import-tasks [id]
Claim tasks with TaskUpdate: status=in_progress
Complete and mark status=completed

Relationship to Other Systems

System	Storage	Purpose	Persistence
TaskList (this)	`~/.claude/tasks/`	Execution tracking	Session-scoped
file-todos	`todos/` in repo	Detailed documentation	Git-committed
TodoWrite tool	In-memory	Temporary tracking	None

Recommended combination:

Use file-todos for detailed findings with Problem Statement, Solutions, Work Log
Use TaskList for execution tracking with dependencies and status
Link them via description references: "See todos/001-pending-p1-issue.md"

tasklist-conventions