---
name: work-queue
description: "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:
```bash
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).

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

Example:
```bash
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).

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

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

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

### `wq get`

Get a single work item by ID.

```bash
wq get <work_item_id>
```

### `wq my-queue`

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

```bash
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)

```bash
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:

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