task-graph-basics

Task Graph Basics

Foundation skill providing shared patterns, tool reference, and connection workflow for task-graph-mcp.

This skill is automatically referenced by all other task-graph skills.

Coordination patterns (roles, phases, states, gates) are defined by workflow configs (workflow-solo.yaml, workflow-hierarchical.yaml, etc.) loaded at connect time. This skill covers the tools and patterns that are common across all workflows.

---

Quick Start

# First thing in any session - connect as a worker
connect(tags=["code", "image-in"])
  Returns worker_id (SAVE THIS for all subsequent calls)

# Find work
list_tasks(ready=true, worker_id=worker_id)

# Claim and work
claim(worker_id=worker_id, task=task_id)
thinking(worker_id=worker_id, thought="Working on X...")
update(worker_id=worker_id, task=task_id, state="completed")

---

Connection Workflow

Every worker MUST connect before using task-graph tools:

1. CONNECT
   connect(
     worker_id="worker-17",   # Only if assigned!
     tags=["code", "audio-out"], # Capabilities
   )
    Returns: worker_id
    SAVE THIS ID for all subsequent calls

2. WORK (use worker_id in all calls)
   list_tasks, claim, thinking, update, etc.

3. DISCONNECT (when done)
   disconnect(worker_id=worker_id)
    Releases all claims and locks

Choosing a worker_id:

• Only provide a worker_id if you've been assigned one that seems unique
• "claude" -> BAD (too generic, will collide)
• "coordinator" -> Likely OK (role-based, probably unique)
• "worker-17" -> Good (explicitly assigned)
• If you don't have an assigned name, omit worker_id entirely -- a unique petname will be generated for you automatically

Tags enable task affinity:

• agent_tags_all on tasks: Worker must have ALL (AND logic)
• agent_tags_any on tasks: Worker must have AT LEAST ONE (OR logic)

---

CLI Agent Delegation

When running as a coordinator (MCP agent), you can spawn background CLI agents for parallel work. CLI agents use task-graph-mcp agent subcommands instead of MCP tool calls.