169 lines
3.7 KiB
Markdown
169 lines
3.7 KiB
Markdown
---
|
|
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`
|