feat: add work-queue skill for Marcus and Steve

skill/SKILL.md

@@ -0,0 +1,115 @@
+---
+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`.