work-queue-api/skill/SKILL.md

name, description

name	description
work-queue	Work queue skill for TheLab agents. Submit, dispatch, track, and complete work items via the Work Queue API. Embeds TheLab dispatch opinion: one in_progress per agent, stale detection, automatic blocking of timed-out items.

Work Queue Skill

Thin wrapper around the Work Queue API with embedded dispatch opinion.

Setup

Set the base URL:

export WORK_QUEUE_API_URL=https://api.example.com  # replace with actual API URL

The skill reads WORK_QUEUE_API_URL from env.

Core Commands

wq add

Submit a new work item (status=queued).

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

Example:

wq add code_review "Review PR #3 in shopping-list-api" --agent steve-w --priority 2 --payload '{"pr":3,"repo":"shopping-list-api"}'

wq dispatch

Dispatch a queued item to an agent (moves queued→dispatched→in_progress atomically).

wq dispatch <work_item_id> <agent>

Fails if agent already has an in_progress item.

wq update

Update status, outcome, or notes on a work item.

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

Valid status transitions:

• dispatched → in_progress (agent picked it up)
• in_progress → blocked (waiting on something)
• in_progress → completed (done)
• in_progress → failed (unrecoverable error)
• queued → cancelled
• dispatched → cancelled

wq list

List work items, optionally filtered.

wq list [--status <status>] [--agent <agent>] [--project-id <id>]

wq get

Get a single work item by ID.

wq get <work_item_id>

wq my-queue

Short-cut: list items assigned to a given agent with status=dispatched (what Steve should poll).

wq my-queue <agent>

---

Dispatch Opinion

These rules are enforced automatically by the skill:

1. One in_progress per agent — dispatch fails if target agent is already in_progress
2. Stale detection — on every heartbeat, wq stale-check is called; items in_progress >30min are automatically marked blocked
3. Terminal states require outcome — moving to completed/failed/cancelled requires outcome field
4. Cancelled only from queued/dispatched — cannot cancel something already in_progress

---

Stale Check (for heartbeat)

wq stale-check [--timeout-minutes 30]

Finds all in_progress items older than timeout, marks them blocked, prints a summary line per item.

---

Integration with Gitea Watcher

The Gitea watcher (gitea_cron/check.sh) outputs dispatch: lines. On heartbeat, parse those lines and for each:

wq add <type> <description> --agent steve-w --payload '<json>'

The watcher itself does NOT call the API — it just emits dispatch lines. Marcus's heartbeat parses them, creates real work items via wq add, then dispatches via wq dispatch.