work-queue-api/skill/SKILL.md

name, description

name	description
work-queue	Full Work Queue API skill for TheLab agents. Covers all project and work item operations: submit, dispatch, track, complete, cancel, and monitor work across agents. Embeds TheLab dispatch opinion.

Work Queue Skill

Wrapper around the Work Queue API at http://app-01:8080.

Setup

# Already configured:
echo "http://app-01:8080" > ~/.config/work_queue_api_url
export WORK_QUEUE_API_URL=http://app-01:8080

Commands

wq health

Check API is up.

wq health

---

Project Commands

wq project add

Create a project.

wq project add <name> [--external-ref <ref>]

external_ref can be a Todoist project ID, GitHub repo, or any external identifier.

wq project list

List all projects.

wq project list

wq project get

Get a single project.

wq project get <project_id>

wq project update

Update a project's name or external_ref.

wq project update <project_id> [--name <name>] [--external-ref <ref>]

---

Work Item Commands

wq add

Submit a new work item (status=queued).

wq add <type> <description> \
  [--agent <agent>] \
  [--project-id <id>] \
  [--priority 1-5>] \
  [--payload <json>] \
  [--created-by <name>]

• type — e.g. code_review, bug_fix, infra_setup, gitea_issue
• priority — 1 (highest) to 5 (lowest), default 3
• payload — arbitrary JSON object with type-specific fields
• created-by — defaults to marcus-a

Example:

wq add code_review "Review PR #3 in work-queue-api" \
  --agent steve-w \
  --project-id be358bbf-aff2-477d-8116-d4bf3d4d3540 \
  --priority 1 \
  --payload '{"pr":3,"repo":"work-queue-api"}'

wq dispatch

Dispatch a queued item to an agent. Atomically moves queued→dispatched→in_progress.

wq dispatch <work_item_id> <agent>

Fails if agent already has an in_progress item.

wq update

Update status, outcome, notes, or reassign agent.

wq update <work_item_id> \
  [--status <status>] \
  [--outcome <success|failed|cancelled>] \
  [--notes <text>] \
  [--agent <agent>]

wq delete

Cancel a work item (sets status=cancelled). Only works from queued or dispatched.

wq delete <work_item_id>

wq list

List work items with optional filters.

wq list \
  [--status <status>] \
  [--agent <agent>] \
  [--project-id <id>] \
  [--since <ISO8601>] \
  [--type <type>]

since filters to items created after the given timestamp (ISO8601).

wq get

Get a single work item (includes dispatch history).

wq get <work_item_id>

wq my-queue

Short-cut: dispatched items for a given agent — what Steve polls.

wq my-queue <agent>

wq stale-check

Find in_progress items older than N minutes, mark them blocked. Run on heartbeat.

wq stale-check [30]

Default timeout: 30 minutes.

---

Dispatch Opinion (enforced by the API)

Transition	From	To
submit	—	queued
dispatch	queued	dispatched
pick up	dispatched	in_progress
block	in_progress	blocked
complete	in_progress	completed
fail	in_progress	failed
cancel	queued/dispatched	cancelled

Rules:

1. One in_progress per agent — dispatch blocks if agent is already busy
2. Terminal states require outcome — completed/failed/cancelled require outcome field
3. Stale detection — wq stale-check auto-blocks stale in_progress items

---

Status Lifecycle

queued → dispatched → in_progress → completed
                              ↘ blocked
                              ↘ failed
           ↘ cancelled (from queued or dispatched only)

API Base

http://app-01:8080