---
name: work-queue
description: "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

```bash
# 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.
```bash
wq health
```

---

## Project Commands

### `wq project add`
Create a project.
```bash
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.
```bash
wq project list
```

### `wq project get`
Get a single project.
```bash
wq project get <project_id>
```

### `wq project update`
Update a project's name or external_ref.
```bash
wq project update <project_id> [--name <name>] [--external-ref <ref>]
```

---

## Work Item 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>] \
  [--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:
```bash
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.
```bash
wq dispatch <work_item_id> <agent>
```
Fails if agent already has an in_progress item.

### `wq update`
Update status, outcome, notes, or reassign agent.
```bash
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.
```bash
wq delete <work_item_id>
```

### `wq list`
List work items with optional filters.
```bash
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).
```bash
wq get <work_item_id>
```

### `wq my-queue`
Short-cut: dispatched items for a given agent — what Steve polls.
```bash
wq my-queue <agent>
```

### `wq stale-check`
Find in_progress items older than N minutes, mark them blocked. Run on heartbeat.
```bash
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`