Task Dispatch

Task scheduling and dispatching for task boards. Use when setting up periodic task dispatch, checking for dispatchable tasks, creating subagents to execute t...

Security Scan

The skill's declared metadata is mostly instruction-only and matches its stated purpose, but the runtime instructions ask you to clone and run a third‑party repo, create and write access tokens into agent workspace files, and reference env vars and filesystem paths that are not declared — these mismatches and the potential for long‑running continuous dispatch make the package suspicious and worth manual review before use.

Purpose & Capability

The skill's name and description (task scheduling/dispatch) align with the files and instructions. However, the package metadata declares no required environment variables or credentials while SKILL.md and README repeatedly require TASKBOARD_API_URL and TASKBOARD_ACCESS_TOKEN and tell the agent to write/read .env files. That mismatch (declared requirements = none vs instructions requiring tokens) is an incoherence a user should be aware of.

Instruction Scope

SKILL.md instructs running commands that clone and run a third‑party project (git clone https://github.com/CCCaptain0129/ClawBoard.git and ./clawboard install/start/token), reading ~/ClawBoard/.env, writing a .env into the agent workspace (~/.openclaw/workspace-<name>/.env), and spawning subagents in a continuous dispatch loop. These actions include filesystem reads/writes and execution of external code beyond simple API calls — broader scope than a purely declarative dispatcher and potentially dangerous if the cloned code is untrusted.

Install Mechanism

There is no formal install spec (instruction-only), which is low-risk by itself, but the instructions explicitly direct cloning and executing a third‑party GitHub repository. That is a moderate risk because it causes arbitrary remote code (the ClawBoard repo) to be installed/run on the host; the skill itself does not bundle that code but relies on it.

Credentials

The skill uses and instructs creation of TASKBOARD_API_URL and TASKBOARD_ACCESS_TOKEN and expects tokens to be stored in filesystem .env files. Yet the declared required env vars list is empty. The token handling (writing token into agent workspace .env, reading token from ~/ClawBoard/.env) involves sensitive credentials and file paths; requesting/storing these credentials without declaring them is disproportionate and inconsistent.

Persistence & Privilege

The skill does not set always:true and does not claim to modify other skills or system settings. However it encourages continuous dispatch loops and spawning subagents until no tasks remain — combined with autonomous invocation (platform default) this can create a long‑running process and many subagent executions. This is not automatically disallowed, but it increases blast radius if the deployed ClawBoard or subagents are untrusted.

What to consider before installing

Before installing or following these instructions: (1) review the ClawBoard GitHub repository being cloned — do not run unreviewed code as root; (2) confirm why TASKBOARD_API_URL and TASKBOARD_ACCESS_TOKEN are needed (they are required at runtime) and store tokens securely (avoid placing secrets in world‑readable files); (3) run the deployment in an isolated test environment (container/VM) first so any third‑party code cannot access sensitive host data; (4) limit subagent permissions and concurrency (maxConcurrentTasks=1) and set sensible timeouts to avoid runaway continuous dispatch; (5) if you expect the skill to declare required env vars, ask the author to update metadata so required credentials are explicit. If you cannot audit the cloned repo, do not run the install/start/token commands on a production machine.

Automated task scheduling and execution for task management systems.

Quick Start

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

Step 1: 检测环境

# 检查 Node.js
node --version  # 需要 >= 18

# 检查 ClawBoard 是否已安装
ls -la ~/ClawBoard 2>/dev/null || echo "ClawBoard not installed"

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

# 克隆仓库
git clone https://github.com/CCCaptain0129/ClawBoard.git ~/ClawBoard
cd ~/ClawBoard

# 安装依赖并初始化
./clawboard install

# 生成访问 token（自动保存到 .env）
./clawboard token --generate

Step 3: 启动服务

cd ~/ClawBoard
./clawboard start

# 检查状态
./clawboard status

Step 4: 配置 Agent 环境

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

# 获取 token
TOKEN=$(cat ~/ClawBoard/.env | grep BOARD_ACCESS_TOKEN | cut -d= -f2)

# 写入 Agent 工作目录
echo "TASKBOARD_API_URL=http://127.0.0.1:3000" >> ~/.openclaw/workspace-<name>/.env
echo "TASKBOARD_ACCESS_TOKEN=$TOKEN" >> ~/.openclaw/workspace-<name>/.env

Step 5: 打开看板

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

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

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

{
  "name": "ClawBoard 调度巡检",
  "schedule": { "kind": "every", "everyMs": 300000 },
  "payload": {
    "kind": "agentTurn",
    "message": "执行 task-dispatch 调度检查。无任务时返回 HEARTBEAT_OK。"
  },
  "sessionTarget": "isolated",
  "delivery": { "mode": "none" }
}

---

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

What	Source
Task data	API endpoint (e.g., http://127.0.0.1:3000/api/tasks/...)
Task files	tasks/*.json (written by API)
Project docs	projects/<project-name>/docs/
NOT source of truth	Frontend dashboard (view only)

ClawBoard Deployment Guide

Prerequisites

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

Installation Commands

Command	Description
./clawboard install	Install dependencies, create .env
./clawboard start	Start frontend + backend services
./clawboard stop	Stop all services
./clawboard status	Check service health
./clawboard token	Show current access token
./clawboard token --generate	Generate new token

Verification Checklist

After deployment, verify:

1. ✅ Backend API responds: curl http://127.0.0.1:3000/health
2. ✅ Frontend loads: open http://127.0.0.1:5173
3. ✅ Token works: curl -H "Authorization: Bearer $TOKEN" http://127.0.0.1:3000/api/tasks/projects
4. ✅ Agent .env configured with token

Common Issues

Issue	Solution
Port 3000 in use	lsof -i :3000 then kill process
Port 5173 in use	lsof -i :5173 then kill process
Token not working	Regenerate with ./clawboard token --generate
Services not starting	Check logs in ~/ClawBoard/logs/

---

Dispatch Operations

Overview

This skill enables agents to:

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

触发一次 → 循环执行直到无任务 → 结束

而不是：

触发一次 → 派发一个任务 → 等待下次触发

Dispatch Loop

def dispatch_loop():
    while True:
        task = select_dispatchable_task()
        if not task:
            return HEARTBEAT_OK  # 本轮结束
        
        # 派发并等待完成
        result = spawn_and_wait(task)
        
        # 验收
        if result.success:
            update_task(task.id, status="review")
        else:
            update_task(task.id, status="failed", blockingReason=result.error)
        
        # 【关键】立即继续下一轮，不返回
        # 循环会自动检查下一个任务

---

API Reference

Get Projects

GET {TASKBOARD_API_URL}/api/tasks/projects
Authorization: Bearer {TOKEN}

Get Tasks

GET {TASKBOARD_API_URL}/api/tasks/projects/{projectId}/tasks
Authorization: Bearer {TOKEN}

Create Project

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

{
  "id": "my-project",
  "name": "My Project",
  "description": "...",
  "taskPrefix": "MP",
  "color": "#3B82F6",
  "icon": "📁"
}

Create Task

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

{
  "title": "Task title",
  "description": "...",
  "status": "todo",
  "priority": "P1",
  "executionMode": "auto",
  "assignee": "agent-id"
}

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:

Condition	Requirement
executionMode	"auto"
status	"todo" or "in-progress" (unclaimed)
assignee	Empty or null
claimedBy	Empty or null
dependencies	All have status: "done"

Priority Order

1. P0 > P1 > P2 > P3
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:

{
  "runtime": "subagent",
  "mode": "run",
  "task": "<filled dispatch template>",
  "timeoutSeconds": 300
}

The main agent should:

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:

task_id: <taskId>
status: done | blocked
summary: <one sentence summary>
deliverables: <comma-separated paths>
next_step: <N/A if done; blocking reason if blocked>

Parse this block to determine task outcome:

• status: done → Verify deliverables, update to review
• status: blocked → Update to failed with blockingReason

---

Status Transitions

todo → in-progress → review → done
                ↓         ↓
              failed    failed

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. Deliverables exist

   • Check all paths in deliverables array
   • Files should be non-empty

2. Acceptance criteria met

   • Review each criterion
   • Mark pass/fail

3. Update status

   • All pass → review
   • Any fail → failed with blockingReason

---

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. 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

Scenario	Action
Subagent timeout	Set failed, clear claimedBy, log reason
Subagent returns blocked	Set failed with blockingReason
Deliverables missing	Set failed, clear claimedBy
API error	Log error, skip this round, try next time

---

Dispatch Principles

1. Only dispatch executionMode=auto tasks
2. Priority order: todo first, then unclaimed in-progress
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

"部署 ClawBoard 看板"

Setup with User Guidance

"帮我设置任务调度系统"

Manual Dispatch (runs until empty)

"检查任务看板，派发所有待执行任务"

Setup Periodic Check

"设置每10分钟自动检查任务"

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