# User Guide

## How the Queue System Works

TheLab's work queue system dispatches tasks to autonomous agents. Each work item has a lifecycle:

```
queued → dispatched → in_progress → completed
                              ↘ blocked
                              ↘ failed
           ↘ cancelled (from queued or dispatched only)
```

1. **Marcus** (or another human) creates a work item via the Work Queue API
2. Work items wait in `queued` until an agent is available
3. The item is `dispatched` to an agent — the agent picks it up and it becomes `in_progress`
4. On completion, the item reaches `completed` (or `failed` if something went wrong)
5. Agents can only have one `in_progress` item at a time

## Viewing the Queue

On the main dashboard you can see:
- **Queued** — work items waiting for an agent
- **In Progress** — items currently being worked on
- **Completed** — finished items with outcomes

## Work Item Fields

| Field | Description |
|---|---|
| `id` | Unique identifier (UUID) |
| `type` | Category: `code_review`, `bug_fix`, `infra_setup`, etc. |
| `description` | Human-readable task description |
| `priority` | 1 (highest) to 5 (lowest) |
| `status` | Current lifecycle state |
| `assigned_agent` | Agent currently handling the item |
| `outcome` | `success`, `failed`, or `cancelled` |
| `created_at` | ISO8601 timestamp |
| `notes` | Optional human notes |

## Agents

Agents are autonomous workers assigned to the queue. Each agent picks up dispatched items and works through them one at a time.

Current known agents:
- **lennie-s** — infrastructure and tooling tasks
- **steve-w** — general development tasks

## Projects

Work items can be grouped under projects. Projects have a name and an optional external reference (e.g., a Git repo URL or Todoist project ID).

## Priorities

Work items have priorities from 1 (highest) to 5 (lowest). Higher priority items are picked up first by agents.