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.

Spawning a CLI Agent

# Start a background worker
task-graph-mcp agent connect my-worker-1 --tags build,test
# or auto-generate ID:
WORKER_ID=$(task-graph-mcp agent connect --format json | jq -r '.worker_id')

CLI Agent Workflow

task-graph-mcp agent list-tasks --ready
task-graph-mcp agent claim <worker-id> <task-id>
task-graph-mcp agent update <worker-id> <task-id> --status completed
task-graph-mcp agent prompts --status working    # Get state guidance
task-graph-mcp agent prompts --advisory           # List advisory topics
task-graph-mcp agent disconnect <worker-id>

Coordinator Responsibilities

• Create tasks and dependencies before spawning CLI agents
• Pass the database path if not using defaults: --database <path>
• Monitor progress: task-graph-mcp agent list-tasks --status working
• CLI agents should call thinking periodically for heartbeat

Tool Reference

Worker Management

Task CRUD

Claiming & Ownership

Ownership via `update`:

• update(state="working") -> Claims task (sets owner)
• update(state="pending") -> Releases task (clears owner)
• update(state="completed") -> Completes task (clears owner)
• Use force=true to take from another worker

Dependencies

Dependency types:

• blocks - blocker must complete before blocked starts
• follows - sequential ordering
• contains - parent-child relationship

File Coordination

Progress & Metrics

Attachments

Search

Search features:

• FTS5-based relevance ranking
• Searches task titles, descriptions, and optionally attachments
• Returns snippets with highlighted matches
• Filter by task status (e.g., status_filter="pending")

Workflows

MCP Resources

The server exposes resources that agents can read for live configuration, documentation, and database queries. Use list_resources / read_resource (or the equivalent MCP resource protocol) to access them.

Query Resources (live database)

Config Resources (active configuration)

Docs Resources (reference content)

Tip: Read config://current early in your session to understand the active state machine, available phases, and tag definitions without extra tool calls.

Task States

States and transitions are defined by the active workflow config. The default state machine (present in all workflows) is:

pending --> working --> completed
   |             |
   |             +--> failed --> pending (retry)
   |
   +--> cancelled

Workflows may add additional states (e.g., assigned, consult). See the loaded workflow for the full state machine. Before adding custom states or phases, consult docs://WORKFLOW_CUSTOMIZATION for the decision framework.

Timed states (like working) automatically:

• Set owner when entering
• Track time_actual_ms
• Clear owner when leaving

Accounting rationale -- why you cannot skip timed states: The state machine requires tasks to pass through a timed state (e.g., working) before reaching completed. You cannot go directly from pending to completed. This exists because time_actual_ms is accumulated by measuring elapsed wall-clock time while a task sits in a timed state. Skipping the timed state would produce zero-duration records, breaking parent rollup totals, sprint velocity, and agent utilization metrics.

>

Pattern for coordinator/bookkeeping tasks: Parent rollup tasks, umbrella tasks, and other bookkeeping items where no real work happens still need to transit through working. The transition can be immediate: `` update(task=task_id, state="working", worker_id=worker_id) update(task=task_id, state="completed", worker_id=worker_id) `` This records a minimal (near-zero) duration while keeping the audit trail and accounting system consistent.

Unified Update Behavior

The update tool handles ownership based on state transitions:

Transition to TIMED state (e.g., working)
  CLAIMS task: validates tags, checks limit, sets owner

Transition to NON-TIMED state (e.g., pending)
  RELEASES task: clears owner

Transition to TERMINAL state (e.g., completed)
  COMPLETES task: checks children, releases file locks

Force parameter:

• update(force=true) takes ownership from another worker
• claim(force=true) same behavior (claim is shortcut for update)

Task Trees

Use create_tree for hierarchical task structures:

{
  "tree": {
    "title": "Feature X",
    "children": [
      {"title": "Design", "points": 3},
      {"title": "Implement", "points": 5},
      {"title": "Test", "points": 2}
    ]
  },
  "sibling_type": "follows"
}

Top-level params:

• child_type - Dependency from parent to children (default: "contains")
• sibling_type - Dependency between siblings ("follows" for sequential, null for parallel)

Tree node fields:

• title - Task title (required for new tasks)
• ref - Reference existing task by ID (other fields ignored)
• id - Custom task ID (UUID7 generated if omitted)
• description, priority, points, time_estimate_ms
• tags, needed_tags, wanted_tags
• children - Nested child nodes

Reference existing tasks:

{ "ref": "existing-task-id" }

Parallel Workstreams with Cross-Branch Dependencies

For complex patterns with parallel tracks, build the tree then add links:

{
  "tree": {
    "title": "Sprint 5",
    "children": [
      {
        "title": "Backend Track",
        "children": [
          {"title": "API endpoints", "id": "api", "needed_tags": ["backend"]},
          {"title": "Database migrations", "id": "db", "needed_tags": ["database"]}
        ]
      },
      {
        "title": "Frontend Track",
        "children": [
          {"title": "Component library", "id": "comp", "needed_tags": ["frontend"]},
          {"title": "Page integration", "id": "page", "needed_tags": ["frontend"]}
        ]
      }
    ]
  }
}

# Sequential deps within each track:
link(from="api", to="db", type="follows")
link(from="comp", to="page", type="follows")

# Cross-branch deps:
link(from="api", to="page", type="blocks")

Scope Expansion via Relink

When a task's scope grows, move children atomically with relink:

# Task "Backend" has children A, B, C, D
# Split: keep A, B in Backend; move C, D to new "Database" sibling

# 1. Create new sibling task
create(title="Database", parent=grandparent_id)
  new_task_id

# 2. Atomic move
relink(
  prev_from="backend-task-id",
  prev_to=["child-c", "child-d"],
  from=new_task_id,
  to=["child-c", "child-d"],
  type="contains"
)

Why relink vs unlink+link?

• Single transaction: all changes succeed or none do
• No intermediate state where children are orphaned
• Validates constraints (single parent, no cycles) before committing

Query Patterns

Find available work

list_tasks(ready=true, worker_id=worker_id)
# Returns: unclaimed tasks with satisfied deps matching worker's tags

Find blocked tasks

list_tasks(blocked=true)
# Returns: tasks waiting on dependencies

Find my tasks

list_tasks(owner=worker_id)
# Returns: tasks I've claimed

Get root tasks only

list_tasks(parent="null")
# Returns: top-level tasks

Get formatted output

list_tasks(format="markdown")
get(task=task_id, children=true, format="markdown")

Search tasks

search(query="authentication")
# Returns: ranked results with highlighted snippets

search(query="auth", include_attachments=true, status_filter="pending")
# Returns: pending tasks matching "auth" in title, description, or attachments

Search vs list_tasks

Best Practices

Always Do

• Save your worker_id after connecting
• Use thinking() frequently to show progress
• Mark files before editing (mark_file)
• Check mark_updates before editing shared files or when seeing edit conflicts
• Log costs with log_cost for tracking

Never Do

• Claim tasks without checking dependencies
• Edit files without advisory locks
• Leave tasks in limbo (always update state)
• Ignore tag requirements on tasks

Error Handling

Related Skills