Task Dependency Patterns Skill

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 |

Agent Skills: Task Dependency Patterns

Install this agent skill to your local

Skill Files