Task Orchestration

The Problem: AI Agents Working in Silos

Before Task Orchestration
After Task Orchestration

Your AI agents create chaos:

Claude starts refactoring AuthController.php
Cursor simultaneously adds OAuth to AuthController.php
Merge conflict after 2 hours of work
No one knows who’s working on what
Features get implemented in wrong order
3 hours lost per conflict

Real example:Developer used 3 AI assistants to build a feature. Each agent modified the same 5 files. Result: 12 merge conflicts, 4 hours wasted resolving them manually.

Status Workflow

Valid Status Transitions

ULPI Tasks enforces a state machine to prevent invalid task states:

📝 todo → in_progress

When: Agent starts working on a taskExample:

Task: BACKEND-042 (Refactor AuthController)
Status: todo → in_progress

# Automatically sets:
started_at: 2025-01-12 14:23:00

Use case:

You: "Start working on BACKEND-042"
Claude: *marks task as in_progress*
        "Started BACKEND-042 at 2:23 PM"

Why it matters:

Signals to other agents: “I’m working on this, don’t touch it”
Tracks actual start time for metrics
Prevents duplicate work

🔄 in_progress → in_review

When: Work is done, needs reviewExample:

Task: BACKEND-042 (Refactor AuthController)
Status: in_progress → in_review

# Agent adds comment:
"Refactoring complete. Please review changes in PR #234"

Use case:

You: "I finished BACKEND-042, mark it for review"
Claude: *marks as in_review*
        *adds comment with PR link*

Why it matters:

Separates “done coding” from “fully complete”
Allows for code review step
Tracks review cycle time

✅ in_review → completed

When: Review passed, task is doneExample:

Task: BACKEND-042 (Refactor AuthController)
Status: in_review → completed

# Automatically sets:
completed_at: 2025-01-12 16:45:00

# Calculates:
Time to complete: 2.37 hours

Use case:

You: "Review looks good, mark BACKEND-042 complete"
Claude: *marks as completed*
        "BACKEND-042 completed in 2.4 hours"

        # If other tasks depend on this:
        "BACKEND-045 is now unblocked and ready to start"

Why it matters:

Unblocks dependent tasks automatically
Finalizes metrics (completion time, actual hours)
Provides closure and visibility

🚫 in_progress → blocked

When: Can’t continue due to external dependencyExample:

Task: BACKEND-042 (Implement OAuth)
Status: in_progress → blocked

# Agent adds comment:
"Blocked by BACKEND-038: Need OAuth credentials from DevOps"

Use case:

You: "I can't finish OAuth until DevOps gives us credentials"
Claude: "I'll mark BACKEND-042 as blocked and create a
         dependency on BACKEND-038"

Why it matters:

Prevents agents from waiting indefinitely
Makes blockers visible
Allows agent to work on other tasks

🔙 in_review → in_progress

When: Review found issues, need reworkExample:

Task: BACKEND-042 (Refactor AuthController)
Status: in_review → in_progress

# Reviewer comment:
"Found 3 issues in code review. Needs fixes before merge."

Use case:

Reviewer: "Code review found issues in BACKEND-042,
           send it back to in progress"
Claude: *marks as in_progress*
        "BACKEND-042 returned for rework"

Why it matters:

Clear signal: work isn’t done yet
Maintains review cycle integrity
Tracks rework time separately

❌ todo/in_progress/blocked → cancelled

When: Task is no longer neededExample:

Task: BACKEND-042 (Add feature X)
Status: in_progress → cancelled

# Comment explains why:
"Feature X cancelled. Product decided to go with feature Y instead."

Use case:

You: "We're not doing feature X anymore, cancel BACKEND-042"
Claude: *marks as cancelled*
        "BACKEND-042 cancelled. 1.5 hours of work recorded."

Why it matters:

Prevents incomplete tasks from cluttering the backlog
Preserves work history (soft delete)
Frees up resources/quota

Task Dependencies

Prevent work on tasks that will be blocked or cause conflicts.

Dependency Types

blocks
relates_to

Definition: Task A blocks Task B = Task B cannot be completed until Task A is doneExample:

BACKEND-038: Set up OAuth credentials
BACKEND-042: Implement OAuth login (blocked by BACKEND-038)

# Can't complete BACKEND-042 until BACKEND-038 is completed

Real-world scenario:

Feature: OAuth2 Implementation

BACKEND-050: Add OAuth database schema (Epic)
  ↓ blocks
BACKEND-051: Implement OAuth endpoints
  ↓ blocks
BACKEND-052: Add OAuth frontend UI
  ↓ blocks
BACKEND-053: Test OAuth flow

# Must be done in this exact order

Enforcement:

# Try to complete BACKEND-052 before BACKEND-051
❌ Error: "Cannot complete BACKEND-052.
           Blocked by: BACKEND-051"

# Must complete BACKEND-051 first
✅ Mark BACKEND-051 as completed
✅ Now BACKEND-052 can be completed

Auto-unblocking: When you complete BACKEND-051, ULPI automatically changes BACKEND-052 status from blocked → todo (ready to start)

Creating Dependencies

🔗 Add Dependency

Command:

"Add dependency: BACKEND-042 is blocked by BACKEND-038"
"Make BACKEND-052 depend on BACKEND-051"
"BACKEND-053 relates to FRONTEND-067"

Programmatic (MCP):

{
  "tool": "add_task_dependency",
  "task_key": "BACKEND-042",
  "depends_on_task_key": "BACKEND-038",
  "dependency_type": "blocks"
}

Result:

✅ Dependency created:
   BACKEND-042 is blocked by BACKEND-038

Status: BACKEND-042 automatically set to "blocked"

🔓 Remove Dependency

When: Dependency is no longer neededCommand:

"Remove dependency between BACKEND-042 and BACKEND-038"

Result:

✅ Dependency removed

Status: If BACKEND-042 was "blocked", changes to "todo"

🔍 View Dependencies

See what’s blocking a task:

"What is blocking BACKEND-042?"

# Returns:
BACKEND-042 is blocked by:
- BACKEND-038: Set up OAuth credentials (in_progress)

See what a task blocks:

"What tasks depend on BACKEND-038?"

# Returns:
BACKEND-038 blocks:
- BACKEND-042: Implement OAuth login (blocked)
- BACKEND-045: Add OAuth scopes (todo)

🚨 Circular Dependency Prevention

ULPI automatically prevents circular dependencies:

# Create dependency
BACKEND-042 depends on BACKEND-038 ✅

# Try to create reverse dependency
BACKEND-038 depends on BACKEND-042 ❌

Error: "Circular dependency detected"

Why it matters:

Prevents deadlock situations
Ensures tasks can actually be completed
Maintains workflow integrity

Multi-Agent Coordination Patterns

Pattern 1: Feature Decomposition

Break a large feature into sequenced tasks for multiple agents.

Scenario
Task Structure
Execution Flow
Benefits

Feature: Implement complete OAuth2 authenticationTeam:

Claude Desktop (backend specialist)
Cursor (frontend specialist)
Windsurf (testing specialist)

Timeline: 3 days

Pattern 2: Bug Triage Workflow

Coordinate bug fixes across multiple agents with priority handling.

Setup
Triage (Hour 1)
Execution (Hours 2-48)
Tracking

Team:

Claude (backend bugs)
Cursor (frontend bugs)
Windsurf (testing/verification)

Incoming bugs: 15 bugs reported in productionGoal: Triage and fix all bugs within 48 hours

Pattern 3: Parallel Feature Development

Multiple agents work on independent features simultaneously.

Scenario
Task Breakdown
Week Timeline
Coordination Magic

Goal: Ship 3 features in 1 weekFeatures:

User roles & permissions (backend + frontend)
Email notification system (backend only)
Dashboard redesign (frontend only)

Team:

Claude (backend)
Cursor (frontend)
Windsurf (QA)

Advanced Orchestration Techniques

🎯 Epic Tasks (Grouping)

Use case: Group related tasks under a parent epicExample:

# Create epic
EPIC-001: OAuth2 Implementation

# Create sub-tasks
BACKEND-051: Database schema (epic: EPIC-001)
BACKEND-052: Endpoints (epic: EPIC-001)
FRONTEND-067: Login UI (epic: EPIC-001)

# Tag all sub-tasks with epic ID in metadata

Track epic progress:

"What's the status of EPIC-001?"

Returns:
Epic: OAuth2 Implementation
Progress: 60% (3/5 tasks completed)
- ✅ BACKEND-051: Database schema
- ✅ BACKEND-052: Endpoints
- ✅ FRONTEND-067: Login UI
- 🔄 BACKEND-053: Token refresh (in progress)
- 📋 TEST-023: Integration tests (blocked)

Pro tip: Use task type epic and store sub-task references in metadata.subtasks array

🔄 Automatic Dependency Resolution

Let AI agents infer and create dependencies automatically.Example:

You: "Create tasks to implement OAuth2:
      1. Database schema
      2. Backend endpoints
      3. Frontend UI
      4. Integration tests"

Claude: "I'll create 4 tasks with automatic dependencies:

         BACKEND-051: Add OAuth database schema
         BACKEND-052: Implement OAuth endpoints
                     (depends on BACKEND-051)
         FRONTEND-067: OAuth login UI
                      (depends on BACKEND-052)
         TEST-023: OAuth integration tests
                   (depends on FRONTEND-067)

         Created dependency chain:
         BACKEND-051 → BACKEND-052 → FRONTEND-067 → TEST-023"

Why it works:

AI understands natural order (DB → API → UI → Tests)
Automatically creates blocks dependencies
Prevents manual dependency management

📊 Capacity Planning

Balance workload across multiple agents.Query:

"How many tasks does each agent have?"

Returns:
claude-main: 12 tasks (8 todo, 3 in_progress, 1 blocked)
cursor-main: 5 tasks (3 todo, 2 in_progress)
windsurf-main: 3 tasks (1 todo, 2 in_review)

Recommendation: Assign new tasks to cursor-main or windsurf-main

Auto-assignment by capacity:

You: "Create a task to add error logging,
      assign to least busy agent"

Claude: "Created BACKEND-080: Add error logging
         Assigned to: windsurf-main (least busy, 3 tasks)"

⏰ Due Date Enforcement

Prioritize tasks by deadline.Example:

# Create task with due date
BACKEND-042: Implement OAuth
Due: 2025-01-15 (3 days from now)

# Query what's due soon
"What tasks are due this week?"

Returns (sorted by due date):
1. BACKEND-042: Implement OAuth (due in 3 days) ⚠️
2. FRONTEND-067: Mobile redesign (due in 5 days)
3. BACKEND-050: Add logging (due in 6 days)

# Overdue detection
"What tasks are overdue?"

Returns:
2 tasks overdue:
- BACKEND-038: Fix auth bug (2 days overdue) 🔴
- FRONTEND-056: Update docs (5 days overdue) 🔴

Auto-prioritization:

You: "What should I work on next?"

Claude: "Priority order:
         1. BACKEND-038 (overdue, critical)
         2. BACKEND-042 (due in 3 days, high priority)
         3. FRONTEND-067 (due in 5 days, medium priority)"

🔍 Smart Task Discovery

Use semantic search to find related work.Example:

# Agent starting OAuth work
You: "What tasks are related to authentication?"

Claude: "Found 6 tasks:
         - BACKEND-042: Implement OAuth (todo)
         - BACKEND-038: Fix session timeout (in_progress)
         - FRONTEND-067: Login UI redesign (blocked)
         - BACKEND-028: Add 2FA support (completed)
         - SECURITY-012: Audit auth flow (todo)
         - BACKEND-056: Token refresh logic (completed)

         Suggested order:
         1. BACKEND-038 (in progress, finish first)
         2. BACKEND-042 (blocked by BACKEND-038)
         3. FRONTEND-067 (blocked by BACKEND-042)"

Why it matters:

Discover tasks you didn’t know existed
Avoid duplicate work
Learn from completed tasks

Best Practices

1. Break Large Features Into Small Tasks

Bad:

BACKEND-001: Implement entire OAuth2 system

Good:

BACKEND-051: Add OAuth database schema
BACKEND-052: Implement OAuth endpoints
FRONTEND-067: Create OAuth login UI
TEST-023: OAuth integration tests

Why: Smaller tasks = better progress tracking, easier parallelization

2. Use Descriptive Task Titles

Bad:

BACKEND-001: Fix bug
BACKEND-002: Update code

Good:

BUG-001: Fix authentication bypass in OAuth flow
IMPROVE-002: Optimize database query performance in user search

Why: Clear titles make search and discovery effective

3. Set Dependencies Early

Best practice:

Create all tasks for a feature at once
Set dependencies immediately
Let AI agents suggest dependency order

Why: Prevents agents from starting work that will be blocked

4. Use Comments for Context

Add context that helps other agents:

BACKEND-042: Implement OAuth

Comment: "Use library X (v2.3+) for OAuth.
          See BACKEND-028 for similar implementation.
          Config file: config/oauth.php"

Why: Future agents can quickly understand the task

5. Tag Tasks for Organization

Example:

BACKEND-042: Implement OAuth
Tags: ["authentication", "backend", "oauth", "security"]

# Later: search by tag
"Show all authentication tasks"
→ Returns all tasks tagged with "authentication"

Why: Makes filtering and reporting easier

6. Track Estimates vs. Actuals

Set estimates:

BACKEND-042: Implement OAuth
Estimate: 4 hours

Compare with actual:

Actual: 6 hours
Variance: +2 hours (+50%)

Why: Improve future estimates, identify bottlenecks

What’s Next?

Try Bulk Operations

Learn how to create and manage 100+ tasks efficiently

Explore Macro Tools

Use macro tools for common workflows

Check API Reference

See all 18 MCP tools available

Need Help?

Getting Started

Quick setup guide

Support

Email us anytime

Community

Join our Discord

Getting Started

Documentation

Skills

Coordination

Memory

Hooks

Tasks

Help & Security

The Problem: AI Agents Working in Silos

Status Workflow

Valid Status Transitions

Task Dependencies

Dependency Types

Creating Dependencies

Multi-Agent Coordination Patterns

Pattern 1: Feature Decomposition

Pattern 2: Bug Triage Workflow

Pattern 3: Parallel Feature Development

Advanced Orchestration Techniques

Best Practices

1. Break Large Features Into Small Tasks

2. Use Descriptive Task Titles

3. Set Dependencies Early

4. Use Comments for Context

5. Tag Tasks for Organization

6. Track Estimates vs. Actuals

What’s Next?

Need Help?

Getting Started

Support

Community

Getting Started

Documentation

Skills

Coordination

Memory

Hooks

Tasks

Help & Security

​The Problem: AI Agents Working in Silos

​Status Workflow

​Valid Status Transitions

​Task Dependencies

​Dependency Types

​Creating Dependencies

​Multi-Agent Coordination Patterns

​Pattern 1: Feature Decomposition

​Pattern 2: Bug Triage Workflow

​Pattern 3: Parallel Feature Development

​Advanced Orchestration Techniques

​Best Practices

1. Break Large Features Into Small Tasks

2. Use Descriptive Task Titles

3. Set Dependencies Early

4. Use Comments for Context

5. Tag Tasks for Organization

6. Track Estimates vs. Actuals

​What’s Next?

​Need Help?

Getting Started

Support

Community

The Problem: AI Agents Working in Silos

Status Workflow

Valid Status Transitions

Task Dependencies

Dependency Types

Creating Dependencies

Multi-Agent Coordination Patterns

Pattern 1: Feature Decomposition

Pattern 2: Bug Triage Workflow

Pattern 3: Parallel Feature Development

Advanced Orchestration Techniques

Best Practices

What’s Next?

Need Help?