Task Dependency Patterns

Overview

Claude Code 2.1.16 introduces a native Task Management System with four tools:

TaskCreate: Create new tasks with subject, description, and activeForm
TaskUpdate: Update status (pending → in_progress → completed), set dependencies
TaskGet: Retrieve full task details including blockers
TaskList: View all tasks with status and dependency summary

Tasks enable structured work tracking, parallel coordination, and clear progress visibility.

When to Use

Breaking down complex multi-step implementations
Coordinating parallel work across multiple files
Tracking progress on large features
Managing dependencies between related changes
Providing visibility into work status

Key Patterns

1. Task Decomposition

Break complex work into atomic, trackable units:

Feature: Add user authentication

Tasks:
#1. [pending] Create User model
#2. [pending] Add auth endpoints (blockedBy: #1)
#3. [pending] Implement JWT tokens (blockedBy: #2)
#4. [pending] Add auth middleware (blockedBy: #3)
#5. [pending] Write integration tests (blockedBy: #4)

2. Dependency Chains

Use addBlockedBy to create execution order:

// Task #3 cannot start until #1 and #2 complete
{"taskId": "3", "addBlockedBy": ["1", "2"]}

3. Status Workflow

pending → in_progress → completed
   ↓           ↓
(unblocked)  (active)

pending/in_progress → deleted (CC 2.1.20)

pending: Task created but not started
in_progress: Actively being worked on
completed: Work finished and verified
deleted: Task removed (CC 2.1.20) - permanently removes the task

Task Deletion (CC 2.1.20)

CC 2.1.20 adds status: "deleted" to permanently remove tasks:

// Delete a task
{"taskId": "3", "status": "deleted"}

When to delete:

Orphaned tasks whose blockers have all failed
Tasks superseded by a different approach
Duplicate tasks created in error
Tasks from a cancelled pipeline

When NOT to delete:

Tasks that might be retried later (keep as pending)
Tasks with useful history (mark completed instead)
Tasks blocked by in_progress work (wait for resolution)

4. activeForm Pattern

Provide present-continuous form for spinner display:

subject (imperative)	activeForm (continuous)
Run tests	Running tests
Update schema	Updating schema
Fix authentication	Fixing authentication

Agent Teams (CC 2.1.33+)

CC 2.1.33 introduces Agent Teams for multi-agent coordination with shared task lists and peer-to-peer messaging.

Team Workflow

1. TeamCreate("my-feature")           → Creates team + shared task list
2. TaskCreate(subject, description)    → Add tasks to shared list
3. Task(prompt, team_name, name)       → Spawn teammates
4. TaskUpdate(owner: "teammate-name")  → Assign tasks
5. SendMessage(type: "message")        → Direct teammate communication
6. SendMessage(type: "shutdown_request") → Graceful shutdown

When to Use Teams vs Task Tool

Criteria	Task Tool (subagents)	Agent Teams
Independent tasks	Yes	Overkill
Cross-cutting changes	Limited	Yes
Agents need to talk	No (star topology)	Yes (mesh)
Cost sensitivity	Lower (~1x)	Higher (~2.5x)
Complexity < 3.0	Yes	No
Complexity > 3.5	Possible	Recommended

Team Task Patterns

# Spawn teammate into shared task list
Task(
  prompt="You are the backend architect...",
  team_name="my-feature",
  name="backend-architect",
  subagent_type="backend-system-architect"
)

# Teammate claims and works tasks
TaskList → find unblocked, unowned tasks
TaskUpdate(taskId, owner: "backend-architect", status: "in_progress")
# ... do work ...
TaskUpdate(taskId, status: "completed")
TaskList → find next task

Peer Messaging

# Direct message between teammates
SendMessage(type: "message", recipient: "frontend-dev",
  content: "API contract ready: GET /users/:id returns {...}",
  summary: "API contract shared")

# Broadcast to all (use sparingly)
SendMessage(type: "broadcast",
  content: "Breaking change: auth header format changed",
  summary: "Breaking auth change")

Anti-Patterns

Creating tasks for trivial single-step work
Circular dependencies (A blocks B, B blocks A)
Leaving tasks in_progress when blocked
Not marking tasks completed after finishing
Using broadcast for messages that only concern one teammate
Spawning teams for simple sequential work (use Task tool instead)

Related Skills

ork:implement - Implementation workflow with task tracking and progress updates
ork:verify - Verification tasks and completion checklists
ork:fix-issue - Issue resolution with hypothesis-based RCA tracking
ork:brainstorming - Design exploration with parallel agent tasks

task-dependency-patterns