task-dependency-patterns

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

• pending: Task created but not started
• in_progress: Actively being worked on
• completed: Work finished and verified
• deleted: Task removed — permanently removes the task

Task Deletion

Use 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

Agent Teams provides 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