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)

Definition: Informational relationship. Task A relates to Task B = working on related code/featureExample:

BACKEND-042: Implement OAuth login
FRONTEND-067: Add OAuth login UI (relates to BACKEND-042)

# No blocking. Just informational link.

Use cases:

Link frontend and backend tasks for same feature
Group tasks by epic/theme
Show related bugs/improvements

No enforcement:

# Can complete tasks in any order
✅ Complete FRONTEND-067 first (no error)
✅ Complete BACKEND-042 second

Why use it:

Helps agents discover related work
Provides context for code reviews
Groups tasks in reporting/analytics

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

Epic: BACKEND-050 (OAuth2 Implementation)
├── Phase 1: Infrastructure (Claude)
│   ├── BACKEND-051: Add OAuth database tables
│   └── BACKEND-052: Set up OAuth provider config
│       (depends on BACKEND-051)
│
├── Phase 2: Backend Logic (Claude)
│   ├── BACKEND-053: Implement OAuth endpoints
│   │   (depends on BACKEND-052)
│   └── BACKEND-054: Add token refresh logic
│       (depends on BACKEND-053)
│
├── Phase 3: Frontend (Cursor)
│   ├── FRONTEND-067: Create OAuth login UI
│   │   (depends on BACKEND-053)
│   └── FRONTEND-068: Handle OAuth callbacks
│       (depends on FRONTEND-067)
│
└── Phase 4: Testing (Windsurf)
    ├── TEST-023: Integration tests
    │   (depends on BACKEND-054, FRONTEND-068)
    └── TEST-024: E2E OAuth flow test
        (depends on TEST-023)

Day 1 (Claude - Backend):

00 - Claude starts BACKEND-051 (database tables)
00 - BACKEND-051 completed → BACKEND-052 unblocked
30 - Claude starts BACKEND-052 (OAuth config)
00 - BACKEND-052 completed → BACKEND-053 unblocked
30 - Claude starts BACKEND-053 (endpoints)

Day 2 (Claude + Cursor - Parallel):

09:00 - Claude completes BACKEND-053
      → BACKEND-054 unblocked
      → FRONTEND-067 unblocked

09:30 - Claude starts BACKEND-054 (token refresh)
        Cursor starts FRONTEND-067 (login UI)
        [Working in parallel - no conflicts]

14:00 - Claude completes BACKEND-054
        Cursor completes FRONTEND-067
      → FRONTEND-068 unblocked
      → TEST-023 partially unblocked

15:00 - Cursor starts FRONTEND-068 (callbacks)

Day 3 (Windsurf - Testing):

00 - Cursor completes FRONTEND-068
      → TEST-023 fully unblocked

30 - Windsurf starts TEST-023 (integration tests)
00 - TEST-023 completed → TEST-024 unblocked
30 - Windsurf starts TEST-024 (E2E tests)
00 - TEST-024 completed
      → Epic BACKEND-050 fully complete ✅

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

Create all bug tasks with priorities:

# Critical bugs (fix immediately)
BUG-001: Database connection pool exhausted [critical]
BUG-002: Authentication bypass in OAuth [critical]

# High priority (fix today)
BUG-003: Session timeout too aggressive [high]
BUG-004: Mobile layout broken on iOS [high]
BUG-005: API rate limit not enforced [high]

# Medium priority (fix this week)
BUG-006: Dashboard charts load slowly [medium]
BUG-007: Email notifications delayed [medium]
...

Assign to specialists:

# Backend bugs → Claude
assign BUG-001 to claude-main
assign BUG-002 to claude-main
assign BUG-003 to claude-main
assign BUG-005 to claude-main

# Frontend bugs → Cursor
assign BUG-004 to cursor-main
assign BUG-006 to cursor-main

# All bugs → Windsurf for verification (after fix)

Claude (backend bugs):

# Start with critical
00 - Start BUG-001 (DB pool exhausted)
30 - Complete BUG-001 → mark for review
45 - Start BUG-002 (auth bypass)
00 - Complete BUG-002 → mark for review

# Move to high priority
00 - Start BUG-003 (session timeout)
30 - Complete BUG-003 → mark for review

Cursor (frontend bugs - parallel):

# Start with high priority
00 - Start BUG-004 (iOS layout)
00 - Complete BUG-004 → mark for review
00 - Start BUG-006 (dashboard charts)

Windsurf (verification):

# As bugs are marked "in_review"
11:45 - Review BUG-001
        → Tests pass → mark completed
13:15 - Review BUG-002
        → Found issue → send back to in_progress
13:30 - Review BUG-004
        → Tests pass → mark completed

Real-time status query:

You: "What's the status of bug fixes?"

Claude: "Bug Fix Progress (15 total):
         ✅ Completed: 8 bugs (53%)
         🔄 In Progress: 3 bugs (20%)
         👀 In Review: 2 bugs (13%)
         📋 Todo: 2 bugs (13%)

         Critical: 2/2 completed ✅
         High: 3/5 completed
         Medium: 3/8 in progress

         ETA: 6 hours (all high priority done)"

Bottleneck detection:

You: "Are any bugs blocked?"

Claude: "1 bug is blocked:
         BUG-010: Can't test payment flow
         Blocked by: BUG-002 (auth bypass fix)

         BUG-002 status: in_review (Windsurf testing)
         ETA for unblock: 30 minutes"

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)

Feature 1: User Roles (Claude + Cursor)
├── BACKEND-070: Add roles table
├── BACKEND-071: Implement RBAC middleware
│   (depends on BACKEND-070)
├── FRONTEND-080: Role management UI
│   (depends on BACKEND-071)
└── FRONTEND-081: Permission guards
    (depends on BACKEND-071)

Feature 2: Email Notifications (Claude only)
├── BACKEND-075: Set up email service
├── BACKEND-076: Notification templates
│   (depends on BACKEND-075)
└── BACKEND-077: Queue processor
    (depends on BACKEND-076)

Feature 3: Dashboard Redesign (Cursor only)
├── FRONTEND-085: New dashboard layout
├── FRONTEND-086: Chart components
└── FRONTEND-087: Responsive design

Monday-Tuesday (Claude):

# Feature 1: User Roles
Mon 09:00 - BACKEND-070 (roles table)
Mon 14:00 - BACKEND-071 (RBAC middleware)

# Feature 2: Email Notifications
Tue 09:00 - BACKEND-075 (email service)
Tue 14:00 - BACKEND-076 (templates)

Monday-Tuesday (Cursor - PARALLEL):

# Feature 3: Dashboard (independent)
Mon 09:00 - FRONTEND-085 (new layout)
Mon 16:00 - FRONTEND-086 (charts)
Tue 09:00 - FRONTEND-087 (responsive)

Wednesday (Claude + Cursor):

# Feature 2: Emails (Claude)
Wed 09:00 - BACKEND-077 (queue processor)
Wed 14:00 - Feature 2 complete ✅

# Feature 1: Roles UI (Cursor)
Wed 09:00 - FRONTEND-080 (role management)
Wed 14:00 - FRONTEND-081 (permission guards)
Wed 17:00 - Feature 1 complete ✅

# Feature 3: Already done ✅

Thursday-Friday (Windsurf - QA):

Thu - Test all 3 features
Fri - Fix any bugs found, final deployment

Key insight: Claude and Cursor work on separate features simultaneouslyWithout task orchestration:

Both agents might edit same files
No visibility into what’s done
Manual coordination needed
Risk of merge conflicts

With task orchestration:

# Each agent knows their lane
Claude: "What should I work on?"
        → BACKEND-070 (roles), then BACKEND-075 (email)

Cursor: "What's available for me?"
        → FRONTEND-085 (dashboard) - independent work

# Dependencies prevent premature work
Cursor: "Can I start FRONTEND-080 (role UI)?"
        → No, blocked by BACKEND-071 (not done yet)
        → Work on dashboard instead

✅ Result: 3 features in 5 days, zero conflicts

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

​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?