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. Agent(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

Agent( 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")

Context Exhaustion Handling

When using Agent Teams, if context limit is reached mid-workflow:

• Collect partial results from completed teammates via TaskList

• Synthesize available outputs — prefer partial results over silent failure

• Log skipped tasks with TaskUpdate(status: "cancelled", note: "context limit")

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:brainstorm

• Design exploration with parallel agent tasks

References

Load on demand with Read("${CLAUDE_SKILL_DIR}/references/<file>") :

File Content

dependency-tracking.md

Dependency tracking patterns

status-workflow.md

Status workflow details

multi-agent-coordination.md

Multi-agent coordination