Skip to main content

Documentation Index

Fetch the complete documentation index at: https://ulpi.mintlify.app/llms.txt

Use this file to discover all available pages before exploring further.

​
The Problem: AI Agents Working in Silos

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:
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
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
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
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
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
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

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

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"
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"
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)
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.
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.
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.
Goal: Ship 3 features in 1 weekFeatures:
  1. User roles & permissions (backend + frontend)
  2. Email notification system (backend only)
  3. Dashboard redesign (frontend only)
Team:
  • Claude (backend)
  • Cursor (frontend)
  • Windsurf (QA)

​
Advanced Orchestration Techniques

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
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
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)"
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)"
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?

1

Try Bulk Operations

Learn how to create and manage 100+ tasks efficiently
2

Explore Macro Tools

Use macro tools for common workflows
3

Check API Reference

See all 18 MCP tools available

​
Need Help?

Getting Started

Quick setup guide

Support

Email us anytime

Community

Join our Discord