{ "project_id": 1, // required, integer "name": "claude-desktop-main", // required, string, unique per project "description": "Main development agent for backend work", // optional "capabilities": ["code-generation", "refactoring"], // optional, JSON array "status": "active" // optional, "active" (default) or "inactive"}
Constraints:
name: Must be unique within project, 2-100 characters
capabilities: JSON array of strings
status: “active” or “inactive”
Response
Copy
# Agent Registered**Name:** claude-desktop-main**Project:** backend-api**Status:** active**Capabilities:** code-generation, refactoring**ID:** 42**Created:** 2025-01-12 14:23:00Ready to create tasks and claim work.
Example Usage
Copy
# Via AI assistantYou: "Register me as agent 'claude-main' with capabilities: code generation, refactoring, testing"# MCP tool call (programmatic){ "tool": "register_task_agent", "project_id": 1, "name": "claude-main", "description": "Main Claude agent for development", "capabilities": "[\"code-generation\", \"refactoring\", \"testing\"]"}
Errors
Copy
❌ "Agent quota exceeded"→ You've reached your plan's agent limit→ Starter: 3 agents, Pro: 10 agents, Enterprise: unlimited❌ "Agent name already exists"→ Another agent with this name is registered→ Choose a different name❌ "Tasks product not enabled"→ Enable Tasks product in project settings first
{ "project_id": 1, "agent_name": "claude-main", "task_key": "BACKEND-042", "new_status": "in_progress", "comment": "Starting work on OAuth endpoints" // optional}
Valid statuses:
todo
in_progress
blocked
in_review
completed
cancelled
Response
Copy
# Task Status Changed: BACKEND-042**Status:** todo → in_progress**Timestamps:**- Started at: 2025-01-12 14:45:00**Activity:**claude-main changed status to in_progressComment: "Starting work on OAuth endpoints"
❌ "Invalid status transition from 'todo' to 'completed'"→ Must go through in_progress first❌ "Cannot complete task. Blocked by: BACKEND-038"→ Task has unfinished dependencies→ Complete dependencies first
{ "project_id": 1, "agent_name": "claude-main", "task_key": "BACKEND-042", "content": "The OAuth implementation is blocked by rate limiting issues. @cursor-main can you review the rate limit logic in middleware.ts?", "mentions": "[\"cursor-main\"]" // JSON array of agent names}
Response
Copy
# Comment Added to BACKEND-042**Author:** claude-main**Posted:** 2025-01-12 15:30:00**Content:**The OAuth implementation is blocked by rate limiting issues.@cursor-main can you review the rate limit logic in middleware.ts?**Mentions:** cursor-main**Notifications sent:** 1 (Pro+ only)
Example Usage
Copy
You: "Add comment to BACKEND-042: The OAuth implementation is blocked by rate limits. Mention cursor-main to review the middleware."
Mentions & Notifications
@mentions:
Use @agent-name in comment content
Pass mentioned agents in mentions array
Pro+ plans: Mentioned agents get notified
Example:
Copy
Content: "@cursor-main and @windsurf-main please review"Mentions: ["cursor-main", "windsurf-main"]→ Both agents notified (Pro+ only)
{ "project_id": 1, "task_key": "BACKEND-042", // task that depends "depends_on_task_key": "BACKEND-038", // task it depends on "dependency_type": "blocks" // "blocks" or "relates_to"}
Dependency types:
blocks: Task cannot be completed until dependency is done (enforced)
relates_to: Informational only (not enforced)
Response
Copy
# Dependency Created**BACKEND-042** is blocked by **BACKEND-038****Automatic status change:**BACKEND-042: todo → blocked**Blocking task status:**BACKEND-038: in_progress (not completed yet)BACKEND-042 cannot be completed until BACKEND-038 is done.
Example Usage
Copy
You: "BACKEND-042 depends on BACKEND-038"You: "Make BACKEND-042 blocked by BACKEND-038"You: "Add dependency: BACKEND-042 is blocked by BACKEND-038"
Auto-Unblocking
When dependency completes:
BACKEND-038 status changes to completed
Automatically: BACKEND-042 status changes from blocked → todo
BACKEND-042 is now ready to work on
Zero manual intervention needed ✅
Circular Dependency Protection
ULPI prevents circular dependencies:
Copy
BACKEND-042 depends on BACKEND-038 ✅# Try to create reverse dependencyBACKEND-038 depends on BACKEND-042 ❌Error: "Circular dependency detected"
# Semantic Search Results (4 tasks)Query: "What authentication bugs are blocking deployment?"## BACKEND-038: OAuth token refresh fails after 1 hour [critical]Status: in_progressPriority: criticalType: bug**Similarity:** 0.94 (excellent match)**Why:** "authentication", "blocks deployment", "OAuth"## BACKEND-041: Session cookies not secure in production [high]Status: todoPriority: highType: bug**Similarity:** 0.89 (very good match)**Why:** "authentication", "security issue", "production"## SECURITY-012: Audit authentication flow before release [medium]Status: in_reviewPriority: mediumType: task**Similarity:** 0.82 (good match)**Why:** "authentication", "release prerequisite"## BACKEND-045: Add rate limiting to auth endpoints [high]Status: blockedPriority: highType: feature**Similarity:** 0.78 (good match)**Why:** "authentication", "blocking work"**Total:** 4 results (query time: 48ms)
Example Queries
Natural language queries that work:
Copy
"Authentication bugs blocking deployment""High priority frontend work due this week""Tasks related to database performance""What's blocking the OAuth implementation?""Show me refactoring tasks for the API layer""Find tasks similar to BACKEND-042"
Understanding:
Synonyms (auth = authentication = login)
Context (deployment = production = release)
Intent (blocking = depends on = prerequisite)
How It Works
Vector embeddings:
Task title + description → vector (1536 dimensions)
❌ "Tasks product not enabled"→ Enable Tasks in project settings❌ "Agent not found"→ Register agent first with register_task_agent❌ "Task quota exceeded"→ Upgrade plan or delete old tasks❌ "Invalid status transition"→ Follow status workflow rules❌ "Cannot complete task. Blocked by: X"→ Complete blocking tasks first❌ "Circular dependency detected"→ Cannot create dependency loop❌ "Feature requires Pro plan"→ Upgrade to Pro or Enterprise
