Task Coordination

The task system (TaskCreate, TaskUpdate, TaskList, TaskGet) provides structured tracking for multi-step projects. Use it to break down complex work, manage dependencies, assign owners, and track progress.

When to Use

• User has a complex feature with multiple implementation steps
• Multiple agents need coordinated work assignment
• User asks about task tracking, dependencies, or progress
• Project requires sequential phases with blocking dependencies
• User wants visibility into what is done and what remains

Core Patterns

Creating a Task Breakdown

Break complex work into discrete, actionable tasks:

TaskCreate:
  subject: "Set up database schema for user profiles"
  description: "Create migration files for users table with fields:
    id, email, name, avatar_url, created_at, updated_at.
    Use the existing migration framework in src/db/migrations/"
  status: "pending"

TaskCreate:
  subject: "Implement user profile API endpoints"
  description: "Create CRUD endpoints: GET/POST/PUT/DELETE /api/users/:id
    Follow existing route patterns in src/api/routes/"
  status: "pending"
  blockedBy: ["1"]  # Depends on database schema

TaskCreate:
  subject: "Add user profile UI components"
  description: "Create ProfileCard, ProfileEditor, AvatarUpload components
    in src/components/profile/"
  status: "pending"
  blockedBy: ["2"]  # Depends on API endpoints

Task Dependencies with blocks/blockedBy

Use addBlocks and addBlockedBy to express ordering constraints:

# Task 1: Database migration
# Task 2: API endpoints (blocked by 1)
# Task 3: UI components (blocked by 2)
# Task 4: E2E tests (blocked by 2 and 3)

TaskCreate:
  subject: "Write E2E tests for user profiles"
  status: "pending"
  blockedBy: ["2", "3"]  # Needs both API and UI

# Task 4 cannot start until tasks 2 AND 3 are completed.

Alternatively, set dependencies from the blocking task's side:

TaskUpdate:
  taskId: "1"
  addBlocks: ["2", "3"]  # Task 1 blocks tasks 2 and 3

Status Tracking Workflow

Tasks follow a clear lifecycle:

pending  -->  in_progress  -->  completed
                                    |
                               (or deleted)

Claim and start a task:

TaskUpdate:
  taskId: "1"
  status: "in_progress"
  owner: "CoreWorkflow"
  activeForm: "Creating database migration"

Complete a task:

TaskUpdate:
  taskId: "1"
  status: "completed"

Owner Assignment for Multi-Agent Teams

Assign tasks to specific agents or team members:

TaskUpdate:
  taskId: "1"
  owner: "DatabaseAgent"
  status: "in_progress"

TaskUpdate:
  taskId: "2"
  owner: "APIAgent"
  status: "pending"  # Still blocked, but assigned

TaskUpdate:
  taskId: "3"
  owner: "FrontendAgent"
  status: "pending"

Checking Progress

Use TaskList to see overall status:

TaskList:
  # Returns:
  # #1 [completed] Set up database schema (DatabaseAgent)
  # #2 [in_progress] Implement user profile API (APIAgent)
  # #3 [pending] Add user profile UI (FrontendAgent) - blocked by #2
  # #4 [pending] Write E2E tests - blocked by #2, #3

Use TaskGet for full details on a specific task:

TaskGet:
  taskId: "2"
  # Returns full description, comments, status, owner, blockers

Active Form for Spinner Display

Set activeForm to show what is happening during in_progress:

TaskUpdate:
  taskId: "2"
  activeForm: "Implementing GET /api/users/:id endpoint"

This shows a spinner with "Implementing GET /api/users/:id endpoint" in the UI.

Post-Completion Flow

After completing a task, check for newly unblocked work:

# 1. Complete current task
TaskUpdate:
  taskId: "2"
  status: "completed"

# 2. Check what is now unblocked
TaskList:
  # #3 [pending] Add user profile UI - no longer blocked!
  # #4 [pending] Write E2E tests - still blocked by #3

# 3. Claim the next available task
TaskUpdate:
  taskId: "3"
  status: "in_progress"
  owner: "FrontendAgent"

Task Granularity Guidelines

Right-sized tasks are:

• Completable in one focused session (15-60 minutes of work)
• Specific enough to verify completion
• Independent enough to have clear boundaries

# TOO COARSE:
"Build the entire authentication system"

# TOO FINE:
"Add import statement for bcrypt"

# RIGHT SIZE:
"Implement password hashing utility with bcrypt"
"Create login endpoint with JWT token generation"
"Add auth middleware for protected routes"

Anti-Patterns

• No dependencies: Creating 10 tasks without dependency relationships leads to out-of-order execution. Always express ordering constraints.
• Marking incomplete work as completed: Never set status to "completed" if tests fail, implementation is partial, or errors remain unresolved. Keep as "in_progress" and create a new blocking task for the issue.
• Skipping TaskList after completion: Always check TaskList after completing a task. Dependencies may have unblocked new work that should be claimed immediately.
• Monolithic tasks: A single task covering an entire feature provides no progress visibility. Break it into 3-7 subtasks with clear completion criteria.
• Orphaned tasks: Tasks with no owner and no blocker that sit in "pending" forever. After creating tasks, assign owners or claim them.

Quick Reference

Status flow: pending -> in_progress -> completed (or deleted) Dependencies: Use blockedBy/addBlocks to express ordering After completion: Always run TaskList to find unblocked work Task size: 15-60 minutes of focused work per task