Task Dispatch

Automated task scheduling and execution for task management systems.

Quick Start

用户说"设置任务调度"或"部署 ClawBoard"时，按以下流程引导：

Step 1: 检测环境

CODEBLOCK0

Step 2: 部署 ClawBoard（如未安装）

CODEBLOCK1

Step 3: 启动服务

CODEBLOCK2

Step 4: 配置 Agent 环境

在 Agent 工作目录创建 .env 文件：

CODEBLOCK3

Step 5: 打开看板

• - 前端看板: http://127.0.0.1:5173
• 后端 API: http://127.0.0.1:3000
• 输入 .env 中的 BOARD_ACCESS_TOKEN 登录

Step 6: 设置定时调度（可选）

用户说"设置定时调度"时：

CODEBLOCK4

Agent Role

You are a dispatcher, not an executor.

• - Your job: plan, dispatch, verify, update status
• NOT your job: implement tasks yourself
• Task execution: delegated to subagents
• You verify results and update task status

Data Source of Truth

ClawBoard Deployment Guide

Prerequisites

• - Node.js >= 18
• Git
• PM2 (auto-installed by ./clawboard install)

Installation Commands

Verification Checklist

After deployment, verify:

1. 1. ✅ Backend API responds: INLINECODE13
2. ✅ Frontend loads: open http://127.0.0.1:5173
3. ✅ Token works: INLINECODE14
4. ✅ Agent .env configured with token

Common Issues

Dispatch Operations

Overview

This skill enables agents to:

1. 1. Check task boards for dispatchable tasks
2. Spawn subagents to execute tasks
3. Verify completion and update task status
4. Continue dispatching until no tasks remain (no waiting for next cron)

Key Principle: Continuous Dispatch

CODEBLOCK5

Dispatch Loop

CODEBLOCK6

API Reference

Get Projects

Get Tasks

Create Project

Create Task

Update Task

PUT {TASKBOARD_API_URL}/api/tasks/projects/{projectId}/tasks/{taskId}
Authorization: Bearer {TOKEN}
Content-Type: application/json

{
  "status": "in-progress",
  "claimedBy": "agent-id"
}

Task Selection Rules

A task is dispatchable if ALL conditions are met:

Priority Order

1. 1. P0 > P1 > P2 > INLINECODE31
2. Same priority: earlier createdAt first

Subagent Execution

Prepare Dispatch Context

Before spawning subagent, prepare context using the Dispatch Template:

See references/dispatch-template.md for full template.

Required fields to fill:

• - Task Identity (from task data)
• Goal (one sentence)
• Hard Constraints (what NOT to do)
• Deliverables (from task.deliverables)
• Acceptance Criteria (from task.acceptanceCriteria)
• Output Format (completion_signal block)

Spawn with Wait

Use sessions_spawn with the dispatch context:

CODEBLOCK12

The main agent should:

1. 1. Fill dispatch template with task context
2. Spawn subagent with the template
3. Wait for completion (blocking or polling)
4. Parse completion_signal from response
5. Verify deliverables and update status
6. Immediately continue to next task

Completion Signal

Subagent must return a completion_signal block:

CODEBLOCK13

Parse this block to determine task outcome:

• - status: done → Verify deliverables, update to INLINECODE37
• INLINECODE38 → Update to failed with INLINECODE40

Status Transitions

CODEBLOCK14

Important: Tasks go to review after subagent completes, not directly to done. User or main agent verifies before done.

Verification Checklist

After subagent completes, verify:

1. 1. Deliverables exist

1. 2. Acceptance criteria met

1. 3. Update status

Heartbeat Response

When triggered by cron/heartbeat:

• - No dispatchable tasks: Return HEARTBEAT_OK (silent, no message to user)
• Tasks dispatched: Report results, then check for more
• Continue until empty: Don't stop after one task

Failure Handling

When a task fails or has no valid execution:

1. 1. Record the reason in blockingReason field
2. Clear invalid occupation (claimedBy)
3. Return task to actionable state (todo or in-progress)
4. Never fail silently - always log or report

Common Failure Scenarios

Dispatch Principles

1. 1. Only dispatch executionMode=auto tasks
2. Priority order: todo first, then unclaimed INLINECODE62
3. Respect assignee: Don't re-dispatch if assignee is set
4. Verify before done: Tasks go to review first, then done after verification

Configuration

See references/config.md for:

• - Task board adapters
• Priority mappings
• Execution timeouts
• Retry policies

Example Usage

Deploy ClawBoard

Setup with User Guidance

Manual Dispatch (runs until empty)

Setup Periodic Check

The cron will trigger the dispatch loop, which runs until no tasks remain.