> ## Documentation Index
> Fetch the complete documentation index at: https://ulpi.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Task Orchestration

> Master workflows, dependencies, and multi-agent coordination patterns

## The Problem: AI Agents Working in Silos

<Tabs>
  <Tab title="Before 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**

    <Warning>
      **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.
    </Warning>
  </Tab>

  <Tab title="After Task Orchestration">
    **Your AI agents coordinate like a real team:**

    * ✅ Task dependencies prevent conflicting work
    * ✅ Status workflow enforces proper sequencing
    * ✅ Agents know what others are working on
    * ✅ Complex features broken into ordered tasks
    * ✅ **Zero merge conflicts**

    <Check>
      **Results:**

      Same developer, same 3 AI assistants, same feature complexity:

      * **0 merge conflicts** (down from 12)
      * **2.5 hours saved** (no conflict resolution)
      * **40% faster** feature delivery
    </Check>
  </Tab>
</Tabs>

***

## Status Workflow

### Valid Status Transitions

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

```mermaid theme={null}
stateDiagram-v2
    [*] --> todo
    todo --> in_progress
    todo --> cancelled

    in_progress --> blocked
    in_progress --> in_review
    in_progress --> completed
    in_progress --> cancelled

    blocked --> in_progress
    blocked --> cancelled

    in_review --> in_progress
    in_review --> completed
    in_review --> cancelled

    completed --> [*]
    cancelled --> [*]
```

<AccordionGroup>
  <Accordion title="📝 todo → in_progress" icon="play">
    **When:** Agent starts working on a task

    **Example:**

    ```bash theme={null}
    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
  </Accordion>

  <Accordion title="🔄 in_progress → in_review" icon="magnifying-glass">
    **When:** Work is done, needs review

    **Example:**

    ```bash theme={null}
    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
  </Accordion>

  <Accordion title="✅ in_review → completed" icon="check">
    **When:** Review passed, task is done

    **Example:**

    ```bash theme={null}
    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
  </Accordion>

  <Accordion title="🚫 in_progress → blocked" icon="hand">
    **When:** Can't continue due to external dependency

    **Example:**

    ```bash theme={null}
    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
  </Accordion>

  <Accordion title="🔙 in_review → in_progress" icon="rotate-left">
    **When:** Review found issues, need rework

    **Example:**

    ```bash theme={null}
    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
  </Accordion>

  <Accordion title="❌ todo/in_progress/blocked → cancelled" icon="xmark">
    **When:** Task is no longer needed

    **Example:**

    ```bash theme={null}
    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
  </Accordion>
</AccordionGroup>

***

## Task Dependencies

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

### Dependency Types

<Tabs>
  <Tab title="blocks">
    **Definition:** Task A **blocks** Task B = Task B cannot be completed until Task A is done

    **Example:**

    ```bash theme={null}
    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:**

    ```bash theme={null}
    # 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
    ```

    <Check>
      **Auto-unblocking:** When you complete BACKEND-051, ULPI automatically changes BACKEND-052 status from `blocked` → `todo` (ready to start)
    </Check>
  </Tab>

  <Tab title="relates_to">
    **Definition:** Informational relationship. Task A **relates to** Task B = working on related code/feature

    **Example:**

    ```bash theme={null}
    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:**

    ```bash theme={null}
    # 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
  </Tab>
</Tabs>

### Creating Dependencies

<AccordionGroup>
  <Accordion title="🔗 Add Dependency" icon="link">
    **Command:**

    ```bash theme={null}
    "Add dependency: BACKEND-042 is blocked by BACKEND-038"
    "Make BACKEND-052 depend on BACKEND-051"
    "BACKEND-053 relates to FRONTEND-067"
    ```

    **Programmatic (MCP):**

    ```json theme={null}
    {
      "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"
    ```
  </Accordion>

  <Accordion title="🔓 Remove Dependency" icon="link-slash">
    **When:** Dependency is no longer needed

    **Command:**

    ```bash theme={null}
    "Remove dependency between BACKEND-042 and BACKEND-038"
    ```

    **Result:**

    ```
    ✅ Dependency removed

    Status: If BACKEND-042 was "blocked", changes to "todo"
    ```
  </Accordion>

  <Accordion title="🔍 View Dependencies" icon="magnifying-glass">
    **See what's blocking a task:**

    ```bash theme={null}
    "What is blocking BACKEND-042?"

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

    **See what a task blocks:**

    ```bash theme={null}
    "What tasks depend on BACKEND-038?"

    # Returns:
    BACKEND-038 blocks:
    - BACKEND-042: Implement OAuth login (blocked)
    - BACKEND-045: Add OAuth scopes (todo)
    ```
  </Accordion>

  <Accordion title="🚨 Circular Dependency Prevention" icon="circle-exclamation">
    **ULPI automatically prevents circular dependencies:**

    ```bash theme={null}
    # 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
  </Accordion>
</AccordionGroup>

***

## Multi-Agent Coordination Patterns

### Pattern 1: Feature Decomposition

**Break a large feature into sequenced tasks for multiple agents.**

<Tabs>
  <Tab title="Scenario">
    **Feature:** Implement complete OAuth2 authentication

    **Team:**

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

    **Timeline:** 3 days
  </Tab>

  <Tab title="Task Structure">
    ```
    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)
    ```
  </Tab>

  <Tab title="Execution Flow">
    **Day 1 (Claude - Backend):**

    ```bash theme={null}
    09:00 - Claude starts BACKEND-051 (database tables)
    11:00 - BACKEND-051 completed → BACKEND-052 unblocked
    11:30 - Claude starts BACKEND-052 (OAuth config)
    14:00 - BACKEND-052 completed → BACKEND-053 unblocked
    14:30 - Claude starts BACKEND-053 (endpoints)
    ```

    **Day 2 (Claude + Cursor - Parallel):**

    ```bash theme={null}
    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):**

    ```bash theme={null}
    10:00 - Cursor completes FRONTEND-068
          → TEST-023 fully unblocked

    10:30 - Windsurf starts TEST-023 (integration tests)
    14:00 - TEST-023 completed → TEST-024 unblocked
    14:30 - Windsurf starts TEST-024 (E2E tests)
    17:00 - TEST-024 completed
          → Epic BACKEND-050 fully complete ✅
    ```
  </Tab>

  <Tab title="Benefits">
    ✅ **Zero merge conflicts**

    * Each agent works on different files
    * Dependencies prevent overlapping work

    ✅ **Parallel execution where possible**

    * BACKEND-054 and FRONTEND-067 run simultaneously
    * 20% faster than sequential

    ✅ **Clear coordination**

    * Every agent knows what to work on next
    * No manual task assignment needed

    ✅ **Visibility**

    * Ask any agent: "What's the status of OAuth2?"
    * Get real-time progress for entire epic
  </Tab>
</Tabs>

***

### Pattern 2: Bug Triage Workflow

**Coordinate bug fixes across multiple agents with priority handling.**

<Tabs>
  <Tab title="Setup">
    **Team:**

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

    **Incoming bugs:** 15 bugs reported in production

    **Goal:** Triage and fix all bugs within 48 hours
  </Tab>

  <Tab title="Triage (Hour 1)">
    **Create all bug tasks with priorities:**

    ```bash theme={null}
    # 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:**

    ```bash theme={null}
    # 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)
    ```
  </Tab>

  <Tab title="Execution (Hours 2-48)">
    **Claude (backend bugs):**

    ```bash theme={null}
    # Start with critical
    10:00 - Start BUG-001 (DB pool exhausted)
    11:30 - Complete BUG-001 → mark for review
    11:45 - Start BUG-002 (auth bypass)
    13:00 - Complete BUG-002 → mark for review

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

    **Cursor (frontend bugs - parallel):**

    ```bash theme={null}
    # Start with high priority
    10:00 - Start BUG-004 (iOS layout)
    12:00 - Complete BUG-004 → mark for review
    13:00 - Start BUG-006 (dashboard charts)
    ```

    **Windsurf (verification):**

    ```bash theme={null}
    # 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
    ```
  </Tab>

  <Tab title="Tracking">
    **Real-time status query:**

    ```bash theme={null}
    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:**

    ```bash theme={null}
    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"
    ```
  </Tab>
</Tabs>

***

### Pattern 3: Parallel Feature Development

**Multiple agents work on independent features simultaneously.**

<Tabs>
  <Tab title="Scenario">
    **Goal:** Ship 3 features in 1 week

    **Features:**

    1. User roles & permissions (backend + frontend)
    2. Email notification system (backend only)
    3. Dashboard redesign (frontend only)

    **Team:**

    * **Claude** (backend)
    * **Cursor** (frontend)
    * **Windsurf** (QA)
  </Tab>

  <Tab title="Task Breakdown">
    ```
    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
    ```
  </Tab>

  <Tab title="Week Timeline">
    **Monday-Tuesday (Claude):**

    ```bash theme={null}
    # 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):**

    ```bash theme={null}
    # 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):**

    ```bash theme={null}
    # 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):**

    ```bash theme={null}
    Thu - Test all 3 features
    Fri - Fix any bugs found, final deployment
    ```
  </Tab>

  <Tab title="Coordination Magic">
    **Key insight:** Claude and Cursor work on separate features simultaneously

    **Without task orchestration:**

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

    **With task orchestration:**

    ```bash theme={null}
    # 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
  </Tab>
</Tabs>

***

## Advanced Orchestration Techniques

<AccordionGroup>
  <Accordion title="🎯 Epic Tasks (Grouping)" icon="layer-group">
    **Use case:** Group related tasks under a parent epic

    **Example:**

    ```bash theme={null}
    # 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:**

    ```bash theme={null}
    "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)
    ```

    <Info>
      **Pro tip:** Use task type `epic` and store sub-task references in `metadata.subtasks` array
    </Info>
  </Accordion>

  <Accordion title="🔄 Automatic Dependency Resolution" icon="wand-magic-sparkles">
    **Let AI agents infer and create dependencies automatically.**

    **Example:**

    ```bash theme={null}
    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
  </Accordion>

  <Accordion title="📊 Capacity Planning" icon="chart-gantt">
    **Balance workload across multiple agents.**

    **Query:**

    ```bash theme={null}
    "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:**

    ```bash theme={null}
    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)"
    ```
  </Accordion>

  <Accordion title="⏰ Due Date Enforcement" icon="calendar-check">
    **Prioritize tasks by deadline.**

    **Example:**

    ```bash theme={null}
    # 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:**

    ```bash theme={null}
    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)"
    ```
  </Accordion>

  <Accordion title="🔍 Smart Task Discovery" icon="sparkles">
    **Use semantic search to find related work.**

    **Example:**

    ```bash theme={null}
    # 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
  </Accordion>
</AccordionGroup>

***

## Best Practices

<CardGroup cols={2}>
  <Card title="1. Break Large Features Into Small Tasks" icon="scissors">
    **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
  </Card>

  <Card title="2. Use Descriptive Task Titles" icon="heading">
    **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
  </Card>

  <Card title="3. Set Dependencies Early" icon="link">
    **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
  </Card>

  <Card title="4. Use Comments for Context" icon="comments">
    **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
  </Card>

  <Card title="5. Tag Tasks for Organization" icon="tags">
    **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
  </Card>

  <Card title="6. Track Estimates vs. Actuals" icon="clock">
    **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
  </Card>
</CardGroup>

***

## What's Next?

<Steps>
  <Step title="Try Bulk Operations">
    [Learn how to create and manage 100+ tasks efficiently](/tasks/parallel-execution)
  </Step>

  <Step title="Explore Macro Tools">
    [Use macro tools for common workflows](/tasks/workflows)
  </Step>

  <Step title="Check API Reference">
    [See all 18 MCP tools available](/tasks/api-reference)
  </Step>
</Steps>

***

## Need Help?

<CardGroup cols={3}>
  <Card title="Getting Started" icon="rocket" href="/tasks/getting-started">
    Quick setup guide
  </Card>

  <Card title="Support" icon="life-ring" href="mailto:support@ulpi.io">
    Email us anytime
  </Card>

  <Card title="Community" icon="discord" href="https://discord.gg/ulpi">
    Join our Discord
  </Card>
</CardGroup>