Plan, dispatch, review. Repeat.

01 The data model.

Three nouns: projects, tasks, steps. One verb that matters: dispatch. Everything else — activity entries, dependencies, attachments, cron schedules — hangs off those.

Tasks carry a human-friendly shortId (e.g. TASK-216) for use in chat, plus a UUID for foreign-key joins. Steps are ordered by orderIndex and typed: PLAN, READ_FILE, EDIT_FILE, CREATE_FILE, DELETE_FILE, RUN_COMMAND, SEARCH, ASK_USER, REVIEW. The type is a hint — the agent picks the actual tool to use at execution time.

02 The status machine.

A task moves through a small set of statuses. Two transitions are gated — IN_PROGRESS → REVIEW is set by the executing agent when it claims work is done; REVIEW → COMPLETED is set by a human, never by a bot. That single rule is what keeps the system honest.

03 Dispatch: clean-context handoff.

When a human (or another bot) clicks Dispatch, the frontend hits POST /api/agents/tasks/[id]/dispatch. That route does four things, in this order:

1. Mark the task IN_PROGRESS in Postgres and pre-fill modelId from the assigned bot's default model — the human doesn't have to specify which model is doing the work.
2. Touch the parent project's updatedAt so it bubbles to the top of the sidebar.
3. Record an AgentActivity row of type task.dispatched with actorType = user or bot.
4. Return {ok: true, status: "dispatched"} immediately. The actual LLM call is deferred to Next's after() background hook so the HTTP response is never blocked on a 30-second agent turn.

Inside the after() callback, the route fetches the full task with its project and ordered steps, renders the agents.task_execution prompt template (pulled live from the llm-bawt prompt store, cached 5 minutes), and POSTs to /v1/chat/completions with extract_memory: false and augment_memory: false. Task work doesn't pollute the bot's conversational memory.

The execution prompt is the interesting part. It includes the task's markdown context (title, description, project context, ordered checklist of steps with their UUIDs), then injects:

The agent is told to update its own task via the same REST endpoints the UI uses — PATCH /api/agents/tasks/[id] and PATCH /api/agents/tasks/[id]/steps/[stepId]. From its perspective there's nothing magic about the dashboard; it just makes the same HTTP calls a human would.

04 What the human sees.

/agents — the dispatch surface. Left: tasks grouped by project, status pills colored by stage. Right: the bot roster, each agent showing its current load. Selecting a task opens a panel with BotDispatchPanel — pick a bot, hit Plan or Execute, the task flips to PLANNING or IN_PROGRESS in real time as the dispatched bot updates its own row.

The frontend pieces — SortableTaskList, TaskRow, BotDispatchPanel, PlanDispatchButton, DispatchNoteDialog — all live under src/app/(app)/(dashboard)/agents/_components/. The drag-to-reorder uses POST /api/agents/tasks/reorder. Promote-to-project is a one-click action that wraps a task as its own project when scope creeps.

05 The MCP surface.

Every operation the UI can perform on tasks is also exposed as an MCP tool, registered in mcp_server/task_tools.py. Agents call these directly. The tools are thin httpx wrappers over the same /api/agents/* REST endpoints — X-Agent-Bot-Id is passed for activity attribution, and errors are wrapped as {error: ..., status: ...} dicts instead of raised exceptions, because LLMs handle failure better as data.

06 Task context as a markdown briefing.

The tasks_get_context tool builds a single markdown document agents can paste into their reasoning at the top of a turn. It's deliberately not a JSON blob — the agent doesn't need to parse it. It looks like this:

# TASK-216 — Wire up Codex tool-result diffs

**Status:** IN_PROGRESS  **Priority:** HIGH
**Assigned to:** caid  **Model:** claude-sonnet-4-6

## Description
The Codex bridge currently sends fileChange items without diff content...

## Dependencies
- ✅ TASK-212 — Provider-aware tool rendering (COMPLETED)

## Steps
- [x] Inspect codex item shape (READ_FILE)
- [~] Map file_change → ClaudeToolCallCard (EDIT_FILE)
- [ ] Add provider gate to FileChangeBody (EDIT_FILE)

## Project: llm-bawt
### Project Context
This is the llm-bawt repo. Run `make restart` after Python changes...

The checkbox states [x], [~], [ ], [!], [-] map to COMPLETED, RUNNING, PENDING, FAILED, SKIPPED. The agent updates these via steps_update as it works; a parallel viewer in the human dashboard re-fetches the task and shows the same row state. Both sides are watching the same Postgres rows.

07 Two-phase dispatch: plan, then execute.

For larger tasks the UI offers two dispatch buttons. Plan sends the task to a bot with a different prompt template — agents.task_planning — that asks the bot to write the spec and seed an ordered step list, but not to do the work. Status moves QUEUED → PLANNING → REFINED. Execute dispatches the same or a different bot against the now-refined plan.

This split lets a fast-thinking bot (e.g. Snark or Loopy) plan, and a code-capable agent (Caid for code; Vex for security audits) execute. The planner doesn't have to be a coding agent, and the executor doesn't have to write the spec from a one-liner.

08 Cron and scheduled work.

The /api/agents/cron family — CronCreate, CronList, CronDelete — lets agents schedule recurring task creation. A common pattern is a daily 6am job: create a task titled "morning brief" assigned to snark with the description "summarize overnight Postgres logs". The cron row holds a crontab expression plus a task template; on each fire it materializes a fresh task in QUEUED and either auto-dispatches or waits for a human nudge depending on the row's autoDispatch flag.

09 Activity as the audit trail.

Every mutating operation — task.created, task.dispatched, task.status_changed, step.completed, project.updated — appends a row to AgentActivity. The row carries actorType (user or bot), actorId (user email or bot slug), and a free-form meta JSON for type-specific payload. The frontend's chat-side AgentActivityRow component renders these inline in the conversation when an agent touches a task while talking to you.

The activity_get MCP tool lets agents look up what they (or other agents) did recently — useful for follow-up tasks: List the last 10 things caid did on TASK-216 returns the actual mutation history, not a summary.

10 Key files.