task-system

Task System

Experimental: Agent teams are disabled by default. Enable with CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS in your settings.json or environment.

Manage shared work items with dependencies, ownership, and status tracking across agent teams.

Related skills:

• Orchestrating - Primitives overview and quick reference
• Team Management - Creating and managing teams
• Messaging - Communicating about task progress
• Orchestration Patterns - Patterns that use tasks effectively
• Error Handling - Handling task failures

---

TaskCreate - Create Work Items

TaskCreate({
  subject: "Review authentication module",
  description: "Review all files in app/services/auth/ for security vulnerabilities",
  activeForm: "Reviewing auth module..."  // Shown in spinner when in_progress
})

Fields:

• subject - Brief, actionable title in imperative form (e.g., "Fix authentication bug")
• description - Detailed description with context and acceptance criteria
• activeForm - Present continuous form shown while task is in_progress (e.g., "Fixing authentication bug")

All tasks are created with status pending and no owner.

---

TaskList - See All Tasks

TaskList()

Returns summary of each task:

#1 [completed] Analyze codebase structure
#2 [in_progress] Review authentication module (owner: security-reviewer)
#3 [pending] Generate summary report [blocked by #2]

Fields returned:

• id - Task identifier
• subject - Brief description
• status - pending, in_progress, or completed
• owner - Agent name if assigned, empty if available
• blockedBy - List of task IDs that must complete first

When to check: After completing a task, to find newly unblocked work. Prefer tasks in ID order (lowest first) when multiple are available.

---

TaskGet - Get Task Details

TaskGet({ taskId: "2" })

Returns full task with description, status, blockedBy, blocks, etc.

---

TaskUpdate - Update Task Status

// Claim and start a task (combined)
TaskUpdate({ taskId: "2", owner: "security-reviewer", status: "in_progress" })

// Mark complete
TaskUpdate({ taskId: "2", status: "completed" })

// Set up dependencies
TaskUpdate({ taskId: "3", addBlockedBy: ["1", "2"] })

// Delete a task
TaskUpdate({ taskId: "4", status: "deleted" })

Status workflow: pending -> in_progress -> completed

Use deleted to permanently remove a task.

---

Task Dependencies

When a blocking task is completed, blocked tasks are automatically unblocked:

// Create pipeline
TaskCreate({ subject: "Step 1: Research" })        // #1
TaskCreate({ subject: "Step 2: Implement" })       // #2
TaskCreate({ subject: "Step 3: Test" })            // #3
TaskCreate({ subject: "Step 4: Deploy" })          // #4

// Set up dependencies
TaskUpdate({ taskId: "2", addBlockedBy: ["1"] })   // #2 waits for #1
TaskUpdate({ taskId: "3", addBlockedBy: ["2"] })   // #3 waits for #2
TaskUpdate({ taskId: "4", addBlockedBy: ["3"] })   // #4 waits for #3

// When #1 completes, #2 auto-unblocks
// When #2 completes, #3 auto-unblocks
// etc.

Fan-in dependencies (multiple blockers):

TaskUpdate({ taskId: "5", addBlockedBy: ["3", "4"] })  // #5 waits for BOTH #3 AND #4

---

Task Claiming and File Locking

Task claiming uses file locking to prevent race conditions when multiple teammates try to claim the same task simultaneously. This is handled automatically by TaskUpdate.

Self-claim workflow:

1. Call TaskList() to see available tasks
2. Find a task with status pending, no owner, and empty blockedBy
3. Claim and start it in one call: TaskUpdate({ taskId: "X", owner: "your-name", status: "in_progress" })
4. Do the work
5. Complete it: TaskUpdate({ taskId: "X", status: "completed" })

If two teammates try to claim the same task simultaneously, one will succeed and the other will see the task is already owned.

---

Task Status Lag

Known limitation: Teammates sometimes fail to mark tasks as completed, which blocks dependent tasks. If a task appears stuck, check whether the work is actually done and update the task status manually, or tell the lead to nudge the teammate.

---

Task File Structure

~/.claude/tasks/{team-name}/1.json:

{
  "id": "1",
  "subject": "Review authentication module",
  "description": "Review all files in app/services/auth/...",
  "status": "in_progress",
  "owner": "security-reviewer",
  "activeForm": "Reviewing auth module...",
  "blockedBy": [],
  "blocks": ["3"],
  "createdAt": 1706000000000,
  "updatedAt": 1706000001000
}

---

Task Sizing Best Practices

• Too small: coordination overhead exceeds the benefit
• Too large: teammates work too long without check-ins, increasing risk of wasted effort
• Just right: self-contained units that produce a clear deliverable (a function, a test file, a review)

Tip: Having 5-6 tasks per teammate keeps everyone productive and lets the lead reassign work if someone gets stuck.