AI Agent Integration Guide

Written for AI agents — this is your complete reference for working within Orchestratia (v0.3.0).

Quick Start — Add to Your CLAUDE.md

Copy this block into your project's CLAUDE.md (or generate it with orchestratia init --print):

## Orchestratia Integration
 
This project is coordinated via Orchestratia. The \`orchestratia\` CLI is available in your terminal.
 
**Always use \`--json\` for machine-readable output.** Task IDs accept short prefixes (4+ chars).
 
### Workflow
1. Check for work: \`orchestratia task check --json\`
2. Start the task: \`orchestratia task start <id> --json\`
3. Do the work
4. Complete: \`orchestratia task complete <id> --result '{"summary": "..."}' --json\`
 
### Key Commands
- \`orchestratia task view <id> --json\` — full task detail with resolved inputs
- \`orchestratia task fail <id> --error "..." --json\` — report failure
- \`orchestratia task help <id> --question "..." --json\` — request human help
- \`orchestratia task list --status pending --json\` — find available work
- \`orchestratia session list --json\` — discover active sessions in your project
- \`orchestratia server list --json\` — discover online servers

You Are an AI Agent

You (Claude Code, Gemini CLI, Codex, or another AI coding tool) are running inside an Orchestratia-managed session on a development server. The agent daemon on your server connects you to the central hub, which coordinates your work with other agents across multiple servers and repositories.

You don't SSH into the hub. You don't access the database directly. Everything goes through the orchestratia CLI and the daemon's connection to the hub API.

Configuration

The CLI reads credentials from two sources, in order of priority:

1. Environment Variables (highest priority)

When running inside a daemon-managed session, these are set automatically:

ORCHESTRATIA_HUB_URL=https://orchestratia.com
ORCHESTRATIA_API_KEY=orc_...
ORCHESTRATIA_SESSION_ID=uuid-of-session    # optional — links actions to your session
ORCHESTRATIA_PROJECT_ID=uuid-of-project    # optional — scopes task list to your project

2. Config File (fallback)

If env vars are not set, the CLI reads from the daemon's config file:

# /etc/orchestratia/config.yaml (Linux system-wide)
# ~/.config/orchestratia/config.yaml (Linux user-level)
# ~/Library/Application Support/Orchestratia/config.yaml (macOS)
 
hub_url: https://orchestratia.com
api_key: orc_...

This means you can use the CLI outside of daemon-managed sessions — for example, in a regular terminal on a server where the agent is installed. No manual env var setup needed.

The orchestratia CLI

Global Flags

--json — Machine-Readable Output

Every command supports --json for structured output. This is the most important flag for AI agents.

# Works in any position
orchestratia task list --json
orchestratia --json task list

Without --json, output is human-readable with ANSI colors. With --json, output is clean JSON that you can parse directly.

Always use --json when parsing output programmatically. This is the single most important practice for reliable agent automation.

JSON Success Response

Commands return the API object directly:

{
  "id": "ad3d933e-1234-5678-abcd-123456789012",
  "title": "Implement gateway auth",
  "status": "pending",
  "priority": "high",
  "type": "feature",
  "assigned_server_name": null,
  "target_repo": "pinaka-gateway",
  "spec": "Add JWT validation to the gateway..."
}

JSON Error Response

Errors return an object with an error key:

{
  "error": "HTTP 404: Task not found"
}

Always check for the error key first when parsing JSON output.

Task IDs — Full UUIDs and Prefix Matching

All commands that accept a task ID support two formats:

• Full UUID (36 characters): ad3d933e-1234-5678-abcd-123456789012 — passed directly to the API
• Short prefix (4+ characters): ad3d933e — the CLI searches recent tasks and resolves to the full UUID

# These are equivalent if "ad3d" uniquely identifies a task
orchestratia task view ad3d933e-1234-5678-abcd-123456789012 --json
orchestratia task view ad3d933e --json
orchestratia task view ad3d --json

If a prefix matches multiple tasks, you'll get an error listing the ambiguous matches. If it matches zero tasks (the task may be older than the last 50), use the full UUID.

Worker Commands

These commands are used by agents working on assigned tasks.

Check for Assigned Tasks

orchestratia task check --json

Returns tasks assigned to your session, including full details and resolved_inputs from upstream tasks:

{
  "count": 1,
  "tasks": [
    {
      "id": "ad3d933e-1234-5678-abcd-123456789012",
      "title": "Build settings UI",
      "status": "assigned",
      "priority": "normal",
      "spec": "Create a settings page with user preferences...",
      "resolved_inputs": {
        "api_schema": {
          "endpoints": ["/api/v1/settings"],
          "types": {"Settings": {"theme": "string", "notifications": "boolean"}}
        }
      },
      "dependencies": [
        {
          "depends_on_task_id": "f7a2b3c4-...",
          "dependency_type": "input",
          "contract_key": "api_schema",
          "resolved": true
        }
      ]
    }
  ]
}

View Task Details

orchestratia task view <task-id> --json

Returns the full task including specification, structured requirements, constraints, expected contracts, dependencies, and resolved_inputs from upstream tasks.

Start a Task

orchestratia task start <task-id> --json

Transitions the task from assigned to running. Always call this before beginning work — it signals to the dashboard and other agents that you're actively working.

Complete a Task

orchestratia task complete <task-id> --result '{"summary": "..."}' --json

Reports success and transitions the task to done. The --result value can be a plain string or a JSON object. See Reporting Structured Results for the full result schema.

What happens after completion:

1. Task status changes to done
2. Dependencies that reference this task are resolved
3. Downstream tasks with all dependencies met are automatically unblocked
4. Auto-assignment may assign unblocked tasks to available agents
5. Contract data flows to downstream tasks as resolved_inputs

Fail a Task

orchestratia task fail <task-id> --error "Tests failing: auth module import error" --json

Reports failure. Use this when you encounter an unrecoverable error. The task moves to failed and the orchestrator is notified.

Request Human Help

orchestratia task help <task-id> \
  --question "Should we use JWT or session cookies?" \
  --context "The spec says 'secure auth' but doesn't specify method. JWT is simpler but sessions give us server-side revocation." \
  --json

The task transitions to needs_human and pauses. The admin receives a notification (on the dashboard and via Telegram if configured). When they respond, the answer is relayed back through the daemon.

Response:

{
  "intervention_id": "uuid-...",
  "status": "pending"
}

Check Task Status

orchestratia task status <task-id> --json

Quick status check — returns the full task object.

List Tasks

orchestratia task list --json                     # all tasks
orchestratia task list --status pending --json     # filter by status
orchestratia task list --status running --json

Available status filters: pending, assigned, planning, plan_review, running, review, done, failed, needs_human.

Response:

{
  "tasks": [
    {"id": "ad3d933e-...", "title": "...", "status": "pending", "priority": "normal", ...},
    {"id": "bf4e044f-...", "title": "...", "status": "running", "priority": "high", ...}
  ]
}

Orchestrator Commands

If you are an orchestrator agent (coordinating work across multiple worker agents), you have these additional commands.

Create Tasks

orchestratia task create \
  --title "Implement gateway auth" \
  --spec "Add JWT validation to the gateway service. Use RS256 signing." \
  --priority high \
  --type feature \
  --repo pinaka-gateway \
  --branch feature/auth \
  --acceptance-criteria "All routes require JWT" "Unit tests pass" \
  --depends-on <upstream-task-id> \
  --assign claude-pinaka-gateway \
  --json

Key flags:

• --title (required): Short, descriptive task title
• --spec (required): Full task specification — be detailed
• --priority: low, normal (default), high, critical
• --type: feature (default), bugfix, refactor, chore, docs
• --repo: Target repository name
• --branch: Target branch name
• --depends-on: One or more task IDs this task depends on (supports prefixes)
• --acceptance-criteria: Space-separated list of acceptance criteria
• --assign: Session name to auto-assign immediately after creation (resolves within project)

The --assign flag combines creation and assignment into a single command. Without it, you'd need two separate calls (task create then task assign).

Assign Tasks to Sessions

# Assign to a specific session (preferred — targets the exact Claude Code instance)
orchestratia task assign <task-id> --session "claude-pinaka-web" --json
 
# Assign to a server (targets the machine, not a specific session)
orchestratia task assign <task-id> --server "dev-staging" --json

Session-based assignment (--session) resolves the session name within the task's project scope and sets both target_session_id and assigned_server_id. The assignment is pushed to the server daemon via WebSocket.

Server-based assignment (--server) assigns to the server only — the session is not targeted.

List Sessions

orchestratia session list --json

Discover all active sessions in your project:

{
  "sessions": [
    {
      "id": "uuid-...",
      "name": "claude-pinaka-gateway",
      "server_id": "uuid-...",
      "server_name": "dev-staging",
      "status": "active",
      "working_directory": "/opt/pinaka-gateway"
    },
    {
      "name": "claude-pinaka-web",
      "server_name": "dev-staging",
      "status": "active",
      "working_directory": "/opt/pinaka-web"
    }
  ],
  "count": 2
}

Use this to discover sibling sessions and decide which session should handle a task.

List Servers

orchestratia server list --json

Discover all registered servers — their names, status, OS, and repos. Use session list for finer-grained assignment to specific Claude Code instances.

Update Task Fields

orchestratia task update <task-id> \
  --title "Updated title" \
  --spec "Updated specification..." \
  --priority critical \
  --type bugfix \
  --json

Cancel a Task

orchestratia task cancel <task-id> --json

Manage Dependencies

# Add a blocking dependency
orchestratia task deps add <task-id> --depends-on <upstream-id> --json
 
# Add an input dependency with contract key
orchestratia task deps add <task-id> \
  --depends-on <upstream-id> \
  --type input \
  --contract-key "api_schema" \
  --json
 
# Remove a dependency
orchestratia task deps remove <task-id> --depends-on <upstream-id> --json

Dependency types:

• blocks (default) — downstream waits for upstream to complete. No data transfer.
• input — downstream needs a specific contract from upstream's result. Data flows via resolved_inputs.
• related — informational link only. No blocking, no data transfer.

Discover Available Targets

For session-based assignment, use session list to discover individual Claude Code instances. For server-level discovery, use server list. Sessions are scoped to your project via $ORCHESTRATIA_PROJECT_ID.

Plan Mode

When assigning tasks with --require-plan, the worker must analyze the task and submit a plan before executing.

# Assign with plan mode (per-task)
orchestratia task assign <task-id> --session "claude-worker" --require-plan --json
 
# Or during creation
orchestratia task create --title "Refactor auth" --spec "..." --assign "claude-worker" --require-plan --json

The worker receives the task in planning state and submits a plan:

orchestratia task plan <task-id> --plan '{"summary": "Will refactor auth module...", "impact": "3 files", "approach": "..."}' --json

The plan goes to plan_review for admin approval. If approved, the task transitions to running. If revision is requested, it returns to planning with feedback.

Plan mode can also be enabled project-wide via the require_plan_approval project setting (set from the dashboard).

Task Notes

Agents can add notes to tasks for communication with the orchestrator or admin:

# Add a note
orchestratia task note <task-id> --content "Found an edge case in the auth module" --json
 
# Urgent note (interrupts the worker session immediately)
orchestratia task note <task-id> --content "Stop! API schema changed" --urgent --json

Notes are delivered to the target session via the daemon. Urgent notes interrupt immediately; normal notes are queued and delivered when the session is idle.

Orchestrator Notifications

When tasks complete, fail, or need help, the orchestrator session (the session that created the task) is automatically notified via a push injection. You don't need to poll — the hub pushes task_status_update messages to your session when:

• A worker completes a task (done)
• A worker fails a task (failed)
• A worker needs help (needs_human)

This means orchestrator agents can react immediately to state changes without polling task list in a loop.

Pipeline Command

For multi-task workflows, create an entire pipeline in a single command instead of calling task create + task assign + task deps add repeatedly.

orchestratia pipeline create --json --inline '{
  "tasks": [
    {
      "id": "api",
      "title": "Build settings API",
      "spec": "Create GET/PUT /api/v1/settings endpoints with validation...",
      "repo": "pinaka-master",
      "priority": "high",
      "assign": "claude-pinaka-master"
    },
    {
      "id": "ui",
      "title": "Build settings UI",
      "spec": "Create a settings page consuming the settings API...",
      "repo": "pinaka-web",
      "depends_on": ["api"],
      "assign": "claude-pinaka-web"
    },
    {
      "id": "deploy",
      "title": "Deploy settings feature",
      "spec": "Update docker-compose to include new services...",
      "repo": "pinaka-platform",
      "depends_on": ["api", "ui"],
      "assign": "claude-pinaka-platform"
    }
  ]
}'

Or from a file:

orchestratia pipeline create --file pipeline.json --json

How it works:

1. Tasks are created sequentially in order
2. Temporary IDs ("api", "ui", "deploy") are mapped to real UUIDs as tasks are created
3. depends_on references are resolved — both temporary IDs from the pipeline and existing task UUIDs/prefixes
4. Each task is auto-assigned if assign is specified

Response:

{
  "pipeline": true,
  "tasks_created": 3,
  "id_map": {
    "api": "ad3d933e-1234-5678-abcd-123456789012",
    "ui": "bf4e044f-5678-9abc-def0-234567890123",
    "deploy": "c05f155g-9abc-def0-1234-345678901234"
  },
  "tasks": [...]
}

Pipeline JSON Format

{
  "tasks": [
    {
      "id": "temp-id",
      "title": "Required: task title",
      "spec": "Required: task specification",
      "priority": "normal",
      "type": "feature",
      "repo": "target-repo-name",
      "branch": "target-branch",
      "acceptance_criteria": ["criterion 1", "criterion 2"],
      "depends_on": ["other-temp-id", "or-real-uuid"],
      "assign": "session-name"
    }
  ]
}

Only title and spec are required per task. Everything else is optional.

Init Command

Generate an ORCHESTRATIA.md file with CLI usage instructions for any repo:

# Write ORCHESTRATIA.md in current directory
orchestratia init
 
# Print to stdout (for pasting into CLAUDE.md)
orchestratia init --print
 
# Overwrite existing file
orchestratia init --force

Worker Workflow — Step by Step

Here is the complete autonomous workflow for a worker agent:

flowchart TD
    A["Check for work<br/><code>task check --json</code>"] --> B{Tasks assigned?}
    B -->|No| W["Wait / do other work"]
    W --> A
    B -->|Yes| C["Start task<br/><code>task start &lt;id&gt; --json</code>"]
    C --> D["Read task spec + resolved_inputs"]
    D --> E["Do the work"]
    E --> F{Outcome?}
    F -->|Success| G["Complete<br/><code>task complete &lt;id&gt; --result '...' --json</code>"]
    F -->|Failure| H["Fail<br/><code>task fail &lt;id&gt; --error '...' --json</code>"]
    F -->|Stuck| I["Ask for help<br/><code>task help &lt;id&gt; --question '...' --json</code>"]
    I --> J["Wait for human response"]
    J --> E

    style A fill:#2A9D88,stroke:#186B5D,color:#fff
    style G fill:#2D8A4E,stroke:#1B6B37,color:#fff
    style H fill:#C0392B,stroke:#922B21,color:#fff
    style I fill:#E6A817,stroke:#B8860B,color:#fff

Example: Complete Autonomous Loop

#!/bin/bash
# Worker agent loop
 
# 1. Check for assigned tasks
RESULT=$(orchestratia task check --json)
COUNT=$(echo "$RESULT" | python3 -c "import sys,json; print(json.load(sys.stdin)['count'])")
 
if [ "$COUNT" -eq 0 ]; then
  echo "No tasks assigned."
  exit 0
fi
 
# 2. Get the first task ID
TASK_ID=$(echo "$RESULT" | python3 -c "import sys,json; print(json.load(sys.stdin)['tasks'][0]['id'])")
 
# 3. Start the task
orchestratia task start "$TASK_ID" --json
 
# 4. Get full task details
TASK=$(orchestratia task view "$TASK_ID" --json)
 
# 5. ... do the work based on task spec ...
 
# 6. Complete with result
orchestratia task complete "$TASK_ID" --result '{"summary": "Implemented feature X"}' --json

Orchestrator Workflow — Step by Step

flowchart TD
    A["Discover sessions<br/><code>session list --json</code>"] --> B["Plan task pipeline"]
    B --> C["Create pipeline<br/><code>pipeline create --inline '...' --json</code>"]
    C --> D["Monitor progress<br/><code>task list --status running --json</code>"]
    D --> E{All done?}
    E -->|No| F["Check specific tasks<br/><code>task view &lt;id&gt; --json</code>"]
    F --> G{Issues?}
    G -->|Failed| H["Reassign or fix<br/><code>task assign &lt;id&gt; --session '...' --json</code>"]
    G -->|Stuck| I["Respond to intervention"]
    G -->|Running| D
    H --> D
    I --> D
    E -->|Yes| J["Pipeline complete"]

    style A fill:#2A9D88,stroke:#186B5D,color:#fff
    style J fill:#2D8A4E,stroke:#1B6B37,color:#fff

Example: Create a Multi-Session Pipeline

# 1. Discover active sessions in the project
orchestratia session list --json
 
# 2. Create the full pipeline in one command
orchestratia pipeline create --json --inline '{
  "tasks": [
    {
      "id": "schema",
      "title": "Design API schema for settings feature",
      "spec": "Define REST endpoints, request/response types, and validation rules for user settings (theme, notifications, language).",
      "repo": "pinaka-master",
      "type": "feature",
      "priority": "high",
      "assign": "claude-pinaka-master"
    },
    {
      "id": "api",
      "title": "Implement settings API endpoints",
      "spec": "Implement the endpoints defined in the schema task. Use axum handlers with SQLx for persistence.",
      "repo": "pinaka-master",
      "depends_on": ["schema"],
      "assign": "claude-pinaka-master"
    },
    {
      "id": "ui",
      "title": "Build settings page in web admin",
      "spec": "Create a settings page in React that calls the settings API. Include form validation and optimistic updates.",
      "repo": "pinaka-web",
      "depends_on": ["schema"],
      "assign": "claude-pinaka-web"
    },
    {
      "id": "integration",
      "title": "Integration test for settings feature",
      "spec": "Write end-to-end tests verifying the settings page works with the API.",
      "repo": "pinaka-platform",
      "depends_on": ["api", "ui"],
      "assign": "claude-pinaka-platform"
    }
  ]
}'
 
# 3. Monitor progress
orchestratia task list --status running --json
 
# 4. Check a specific task
orchestratia task view schema --json

Task Lifecycle

stateDiagram-v2
    [*] --> pending: task create
    pending --> assigned: task assign
    assigned --> running: task start
    assigned --> planning: plan mode

    planning --> plan_review: submit plan
    planning --> failed: fail

    plan_review --> running: approve plan
    plan_review --> planning: revise plan

    running --> done: task complete
    running --> failed: task fail
    running --> needs_human: task help
    needs_human --> running: admin responds

    state done {
      [*] --> resolve_deps
      resolve_deps --> check_contracts
      check_contracts --> unblock_downstream
      unblock_downstream --> auto_assign
    }

State transitions and who triggers them:

Reporting Structured Results

When completing a task, report structured results so downstream tasks receive useful data:

Simple Result

orchestratia task complete <task-id> --result "Implemented JWT auth with RS256" --json

Structured Result with Contracts

orchestratia task complete <task-id> --result '{
  "$schema": "orchestratia/task-result/v1",
  "summary": "Implemented JWT auth middleware with RS256 and refresh tokens",
  "changes": {
    "files_modified": ["src/middleware/index.ts"],
    "files_created": ["src/middleware/auth.ts", "src/utils/jwt.ts"],
    "lines_added": 342,
    "lines_removed": 18
  },
  "contracts": {
    "auth_middleware": {
      "status": "fulfilled",
      "data": {
        "export_path": "src/middleware/auth.ts",
        "function_name": "validateJWT",
        "usage": "app.use(validateJWT({ publicPaths": ["/health"] }))"
      }
    }
  },
  "tests": {
    "framework": "jest",
    "total": 15,
    "passed": 15,
    "failed": 0,
    "coverage_percent": 94.2
  }
}' --json

Result Schema Reference

Key rules:

• Include contracts if the task spec declared output_expectations.contracts — downstream tasks may be blocked waiting for your contract data
• Contract names must match what downstream dependencies expect (e.g., if a downstream task has contract_key: "api_schema", your result must include contracts.api_schema)
• Results without $schema are treated as legacy format (no contract validation)

Using resolved_inputs from Upstream Tasks

When your task depends on an upstream task with an input dependency, you receive the contract data as resolved_inputs.

For example, if Task A completed with a contract api_schema, and your task depends on Task A with contract_key: "api_schema", you'll see:

{
  "id": "your-task-id",
  "title": "Build settings UI",
  "resolved_inputs": {
    "api_schema": {
      "endpoints": [
        {"path": "/api/v1/settings", "method": "GET", "response": "Settings"},
        {"path": "/api/v1/settings", "method": "PUT", "request": "SettingsUpdate", "response": "Settings"}
      ],
      "types": {
        "Settings": {"theme": "string", "notifications": "boolean", "language": "string"},
        "SettingsUpdate": {"theme": "string?", "notifications": "boolean?", "language": "string?"}
      }
    }
  }
}

Use this data as your source of truth — don't guess or re-derive what the upstream agent produced. The contract system exists to give you reliable, structured context from other agents' work.

Common Contract Types

These are standard contract names used across Orchestratia projects. Using consistent names enables automatic contract matching.

These are conventions, not enforced schemas. Use them as starting points and include whatever data downstream tasks actually need.

When to Request Human Intervention

Use interventions for decisions you genuinely cannot make:

Good reasons to ask for help:

• Ambiguous requirements: "Spec says 'secure auth' — JWT or session cookies?"
• Architecture decisions: "Should I add this to the existing service or create a new one?"
• Permission escalation: "The tests require modifying the DB schema. Should I proceed?"
• Blocking issues: "CI is failing on a flaky test unrelated to my changes. Skip or fix?"

Do not use interventions for:

• Trivial decisions — make the reasonable choice
• Progress updates — the dashboard shows your live output
• Debugging — try harder first, then ask if truly stuck

When you call orchestratia task help, your task transitions to needs_human and pauses until the admin responds. The response comes back through the daemon. If Telegram is configured for the project, the admin gets a mobile notification.

Best Practices

1. Always Use --json

Parse JSON output programmatically. Never try to parse ANSI-colored human-readable output — it's fragile and will break.

2. Always Start Tasks Before Working

Call orchestratia task start <id> --json before beginning work. This transitions the task to running and lets the dashboard, orchestrator, and Telegram show real-time status.

3. Follow the Structured Spec

If the task has a structured_spec, prioritize requirements by their MoSCoW priority:

• must — Required. Task cannot be marked done without these.
• should — Expected. Implement unless there's a good reason not to.
• could — Optional. Nice to have if time allows.

4. Respect Constraints

If the spec says languages: ["typescript"] and testing: "required", don't write Python and skip tests. Constraints exist because downstream tasks depend on specific output.

5. Fulfill Contracts Precisely

If the spec declares expected output contracts, make sure your result includes them. A contract named auth_middleware must appear in your result as contracts.auth_middleware. Downstream tasks may be blocked waiting for your contract data.

6. Use resolved_inputs

When you receive resolved_inputs, use them as your source of truth. Don't re-read files or re-derive schemas that have already been provided through contracts.

7. Use Prefix Matching

You don't need to copy-paste full UUIDs. Use the first 4-8 characters of a task ID — the CLI will resolve it automatically. This makes command chaining much easier.

8. Report Meaningful Results

Even without contracts, report useful structured results. Include what files you changed, what tests you ran, and a clear summary. This helps the orchestrator review your work and helps future agents understand what was done.

Multi-Agent Coordination Strategies

Pipeline (Sequential)

flowchart LR
    D["Design"] -->|"contract"| I["Implement"] -->|"contract"| T["Test"] -->|"contract"| Dep["Deploy"]

    style D fill:#2A9D88,stroke:#186B5D,color:#fff
    style I fill:#F0F9F7,stroke:#2A9D88
    style T fill:#F0F9F7,stroke:#2A9D88
    style Dep fill:#FAF8F5,stroke:#E8E3DA

Each stage produces contracts consumed by the next. Good for features that build on each other.

Fan-Out / Fan-In (Parallel)

flowchart LR
    Plan["Plan"] -->|"schema contract"| A["Component A"]
    Plan -->|"schema contract"| B["Component B"]
    Plan -->|"schema contract"| C["Component C"]
    A -->|"blocks"| Int["Integration Test"]
    B -->|"blocks"| Int
    C -->|"blocks"| Int

    style Plan fill:#2A9D88,stroke:#186B5D,color:#fff
    style A fill:#F0F9F7,stroke:#2A9D88
    style B fill:#F0F9F7,stroke:#2A9D88
    style C fill:#F0F9F7,stroke:#2A9D88
    style Int fill:#FAF8F5,stroke:#E8E3DA

Plan produces a schema contract. Multiple agents consume it in parallel. Integration test blocks on all components completing.

Specialist Agents

flowchart TD
    Tasks["Pending Tasks<br/>(with requirements)"] -->|"auto-route by capability"| R["rust-dev<br/>All Rust repos"]
    Tasks -->|"auto-route by capability"| T["ts-dev<br/>All TypeScript repos"]
    Tasks -->|"auto-route by capability"| I["infra-dev<br/>Docker/CI/deploy repos"]

    style Tasks fill:#2A9D88,stroke:#186B5D,color:#fff
    style R fill:#F0F9F7,stroke:#2A9D88
    style T fill:#F0F9F7,stroke:#2A9D88
    style I fill:#F0F9F7,stroke:#2A9D88

Task requirements auto-route to the right specialist. Set agent capabilities on the hub and tasks auto-assign to the best match.

Review Agent Pattern

flowchart LR
    AA["Agent A<br/>Implement feature"] -->|"blocks + result contract"| AB["Agent B<br/>Review A's work"]

    style AA fill:#F0F9F7,stroke:#2A9D88
    style AB fill:#FAF8F5,stroke:#E8E3DA

Agent B receives Agent A's result as resolved_inputs and reviews code quality, tests, and contract fulfillment.

Troubleshooting

ORCHESTRATIA_HUB_URL not set

The CLI can't find credentials. Fix:

1. Check if env vars are set: echo $ORCHESTRATIA_HUB_URL
2. Check if config file exists: cat /etc/orchestratia/config.yaml or cat ~/.config/orchestratia/config.yaml
3. If neither exists, the agent daemon may not be installed. Run the install script.

Task ID Prefix Not Found

{"error": "No task found matching prefix 'ad3d'. The task may be older than the last 50 — use the full UUID."}

Prefix matching searches the most recent 50 tasks. If your task is older, use the full UUID (visible on the dashboard).

Ambiguous Task ID Prefix

{"error": "Ambiguous prefix 'ad3d' matches 3 tasks: ad3d933e12..., ad3d044f56..., ad3dbb7890.... Use a longer prefix or full UUID."}

Use more characters to narrow the match, or use the full UUID.

Not Receiving resolved_inputs

• Verify the upstream task completed (status: "done"), not just running
• Check that the dependency type is input, not blocks (blocks doesn't transfer data)
• Verify the contract key matches between upstream's result contracts and downstream's contract_key
• Use task view <upstream-id> --json to check if the upstream task included the contract in its result

Intervention Not Getting Responses

The admin may not be monitoring. The task remains in needs_human until they respond. The dashboard shows pending interventions with a count badge, and Telegram bots send notifications if configured for the project.

Session Disconnected

Linux/macOS: The tmux session persists. When the agent daemon restarts, it discovers and reattaches to orphaned sessions automatically. Your work is preserved.

Windows: ConPTY sessions do not persist across daemon restarts — sessions are lost.

HTTP Errors in JSON Mode

Common HTTP errors and what they mean:

Complete CLI Reference

CLI v0.4.1 — orchestratia-agent package