ATS Backend Skill

Connect to and interact with the Agent Task Service (ATS) backend for task orchestration between AI agents and humans.

Overview

The Agent Task Service is a PostgreSQL-backed task orchestration platform that enables intelligent handoffs between agents and humans. Use this skill when you need to:

• Create, list, claim, or complete tasks
• Subscribe to real-time task events
• Send messages on task threads
• Coordinate work between agents and humans

Prerequisites

FIRST: Verify ATS CLI Installation

ats --version  # Requires v1.x+

If not installed:

npm install -g @difflabai/ats-cli

Default Server: https://ats.difflab.ai

Environment Variables:

• ATS_URL - Override server URL
• ATS_ORG - Default organization
• ATS_PROJECT - Default project
• ATS_ACTOR_TYPE - Default actor type (human, agent, system)
• ATS_ACTOR_ID - Default actor ID
• ATS_ACTOR_NAME - Default actor display name

Configuration

ATS CLI stores defaults in ~/.ats/config:

{
  "organization": "default",
  "project": "main",
  "url": "https://ats.difflab.ai",
  "actor": {
    "type": "agent",
    "id": "claude-code",
    "name": "Claude Code"
  }
}

Priority: CLI flags > environment variables > config file > defaults

Statistics

# Aggregate task statistics (totals, by status, by channel)
ats stats

# JSON output
ats stats -f json

Project Commands

Initialize a Project in Current Directory

Bind the current directory to an org/project so all ats commands automatically scope to it:

# Bind to existing project
ats project init myorg/myproject

# With explicit flags
ats project init --org myorg --project myproject

# Overwrite existing config
ats project init myorg/myproject --force

# Skip server existence check (for projects that will be created later, or offline use)
ats project init myorg/myproject --skip-existence-check

Creates a .ats/project.json file in the current directory. By default, project init verifies that the org/project exists on the server before creating the local binding. Use --skip-existence-check when initializing a binding for a project that hasn't been created yet or when working offline.

List Projects

# List all projects across all organizations (with task counts)
ats project list

# JSON output
ats project list -f json

Shows project path (org/project), display name, pending/active/total task counts. Current project is marked with *.

Create a Project

# Create project (auto-creates org if it doesn't exist)
ats project create myorg/myproject

# With display name and description
ats project create myorg/myproject --name "My Project" --description "Project description"

Switch Default Project

Set the global default project (used when no local .ats/project.json exists):

ats project switch myorg/myproject

Show Current Project

# Show which project is active and where the config comes from
ats project current

Show Full Project Configuration

Displays global config, local config, and effective settings:

ats project show

# JSON output
ats project show -f json

Rename a Project or Organization

# Rename project slug
ats project rename myorg/oldslug myorg/newslug

# Rename just the project slug
ats project rename myorg/myproject --slug new-slug

# Rename display name
ats project rename myorg/myproject --name "New Display Name"

# Rename org and project together
ats project rename oldorg/oldproject neworg/newproject

Automatically updates local and global configs if the renamed project was the current project.

Task Operations

List Tasks

# List pending tasks (default - what needs attention)
ats list

# List all tasks
ats list --all

# Filter by status, channel, type
ats list --status in_progress
ats list --channel reviews
ats list --type approval

# Combine filters
ats list --status pending --channel support --limit 10

# JSON output for scripting
ats list -f json | jq '.[] | .title'

Create a Task

# Simple task
ats create "Review the pull request"

# With options
ats create "Deploy to production" \
  --type deployment \
  --channel ops \
  --priority 8 \
  --description "Deploy v2.1.0 to production cluster"

# With JSON payload
ats create "Process data import" \
  --payload '{"source": "s3://bucket/data.csv", "rows": 50000}'

Priority levels: 1-10, higher is more urgent (default: 5)

Get Task Details

# Human-readable output
ats get 123

# JSON for scripting
ats get 123 -f json | jq '.status'

Update a Task

ats update 123 --priority 9
ats update 123 --title "Updated title" --description "New description"

Claim a Task (Start Working)

Claiming moves the task to in_progress and starts a lease timer:

ats claim 123

# Custom lease duration (ms)
ats claim 123 --lease 120000

Important: The lease expires after 60 seconds by default. If the worker crashes, the task returns to pending automatically.

Complete a Task

# Simple completion
ats complete 123

# With output data
ats complete 123 --outputs '{"result": "Approved", "notes": "LGTM"}'

Cancel a Task

ats cancel 123

Fail a Task

ats fail 123 --reason "Unable to connect to external service"

Reject a Task

ats reject 123 --reason "This task is outside my capabilities"

Reopen a Task

Reopen a task from a terminal state (completed, cancelled, failed, rejected) back to pending:

ats reopen 123

# With reason
ats reopen 123 --reason "Need to revisit this task"

Delete a Task

ats delete 123

Message Operations

Add a Message to a Task

# Simple text message
ats message add 123 "I've started working on this"

# With content type
ats message add 123 '{"status": "analyzing", "progress": 50}' --type data

List Messages for a Task

ats message list 123

# JSON output
ats message list 123 -f json

Real-Time Events

Watch for Events

# Watch all events
ats watch

# Filter by channel
ats watch --channel support

# Filter by task type
ats watch --type approval

# Filter by specific events
ats watch --events task.created,task.completed

Event Types:

• task.created - New task created
• task.claimed - Task claimed by worker
• task.updated - Task fields modified
• task.completed - Task finished successfully
• task.cancelled - Task cancelled
• task.failed - Task failed with error
• task.rejected - Task rejected by worker
• task.reopened - Task reopened from terminal state
• task.message - New message added
• task.lease_expired - Worker lease expired, task returned to pending

Task Status Flow

pending ──claim──→ in_progress ──complete──→ completed ──┐
   ↑                    │                                │
   │                    ├──cancel───→ cancelled ─────────┤
   │                    │                                │
   │                    ├──fail─────→ failed ────────────┼──reopen──→ pending
   │                    │                                │
   │                    └─(lease expires)─→ pending      │
   │                                                     │
   └──reject──→ rejected ────────────────────────────────┘

Terminal states: completed, cancelled, failed, rejected (all can be reopened)

Common Patterns

Pattern 1: Create Task and Wait for Human Response

# Create task for human review
TASK_ID=$(ats create "Approve deployment" --type approval --channel ops -f json | jq -r '.id')
echo "Created task: $TASK_ID"

# Poll for completion
while true; do
  STATUS=$(ats get $TASK_ID -f json | jq -r '.status')
  if [ "$STATUS" = "completed" ] || [ "$STATUS" = "rejected" ]; then
    echo "Task finished with status: $STATUS"
    break
  fi
  sleep 5
done

Pattern 2: Claim and Process Tasks

# Get first pending task of a specific type
TASK_ID=$(ats list --type code-review -f json | jq -r '.[0].id')

# Claim it
ats claim $TASK_ID

# Do the work...

# Complete with results
ats complete $TASK_ID --outputs '{"review": "LGTM, approved"}'

Pattern 3: Escalate to Human

When Claude Code encounters something requiring human decision:

ats create "Human decision required: Delete production database?" \
  --type escalation \
  --channel urgent \
  --priority 10 \
  --description "The user requested to delete the production database. This requires human approval." \
  --payload '{
    "context": "User command: DROP DATABASE production",
    "risk_level": "critical",
    "suggested_action": "confirm_with_user"
  }'

Pattern 4: Pipeline with jq

# Get high-priority pending tasks
ats list -f json | jq '.[] | select(.priority >= 8)'

# Count tasks by status
ats list --all -f json | jq 'group_by(.status) | map({status: .[0].status, count: length})'

# Get task IDs for a channel
ats list --channel support -f json | jq -r '.[].id'

Actor Identity

Configure how you appear in ATS:

# As an agent (default for Claude Code)
ats list --actor-type agent --actor-id claude-code --actor-name "Claude Code Agent"

# As a human
ats list --actor-type human --actor-id user-123 --actor-name "John Doe"

# Or set via environment
export ATS_ACTOR_TYPE=agent
export ATS_ACTOR_ID=claude-code
export ATS_ACTOR_NAME="Claude Code Agent"

Health Check

ats health

Global Options

Quick Reference

Server API Endpoints Not Covered by CLI

The ATS server exposes 61 endpoints across 14 resource groups. The CLI covers tasks, messages, projects, basic org operations, stats, health, and WebSocket events. The following server endpoints have no CLI equivalent and must be accessed via direct HTTP calls or the WebSocket API.

Authentication & Identity (4 endpoints)

API Key Management (3 endpoints)

Guardian System (5 endpoints)

Organization Members (4 endpoints)

Invitations (5 endpoints)

Namespace Permissions (3 endpoints)

Other Missing Operations (3 endpoints)

Total: 27 server endpoints with no CLI command (out of 61 total).