feat(skill): cover full API — projects, delete, health, all WorkCreate fields

skill/SKILL.md

@@ -1,115 +1,168 @@
 ---
 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."
+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
 
- Thin wrapper around the Work Queue API with embedded dispatch opinion.
+Wrapper around the Work Queue API at `http://app-01:8080`.
 
 ## Setup
 
-Set the base URL:
 ```bash
-export WORK_QUEUE_API_URL=https://api.example.com  # replace with actual API URL
+# Already configured:
+echo "http://app-01:8080" > ~/.config/work_queue_api_url
+export WORK_QUEUE_API_URL=http://app-01:8080
 ```
 
-The skill reads `WORK_QUEUE_API_URL` from env.
+## Commands
 
-## Core 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>]
+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 shopping-list-api" --agent steve-w --priority 2 --payload '{"pr":3,"repo":"shopping-list-api"}'
+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 (moves queued→dispatched→in_progress atomically).
-
+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, or notes on a work item.
-
+Update status, outcome, notes, or reassign agent.
 ```bash
-wq update <work_item_id> [--status <status>] [--outcome <success|failed|cancelled>] [--notes <text>]
+wq update <work_item_id> \
+  [--status <status>] \
+  [--outcome <success|failed|cancelled>] \
+  [--notes <text>] \
+  [--agent <agent>]
 ```
 
-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 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, optionally filtered.
-
+List work items with optional filters.
 ```bash
-wq list [--status <status>] [--agent <agent>] [--project-id <id>]
+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 by ID.
-
+Get a single work item (includes dispatch history).
 ```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).
-
+Short-cut: dispatched items for a given agent — what Steve polls.
 ```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)
-
+### `wq stale-check`
+Find in_progress items older than N minutes, mark them blocked. Run on heartbeat.
 ```bash
-wq stale-check [--timeout-minutes 30]
+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)
 ```
 
-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`.
+## API Base
+`http://app-01:8080`