Epics and Tasks
Applies to: Dispatch v1.0.0, last verified 2026-04-05
TL;DR: The center column shows epics (from .tasks/) and tasks (all phases, flattened). Click a card to open the detail drawer. Use the sidebar or project tabs to filter.
The center column shows the work your agents are doing. Toggle between the three views using the buttons above the list: Missions (epic cards, default), Orders (flat phase list), and Sessions (active sessions from all four providers).
Missions view
Section titled “Missions view”Each epic in your .tasks/ directories appears as a card.
What a card shows
Section titled “What a card shows”| Element | Description |
|---|---|
| Status badge | TODO, IN PROGRESS, DONE, BLOCKED, ON HOLD, or CANCELLED |
| Phase railroad | A row of dots, one per phase. Green = done, blue pulse = in progress, red = blocked, grey = todo/cancelled/on-hold |
| Active phase | The title of the phase currently being worked, and the persona assigned to it |
| Epic title | Human-readable display title, resolved from the title: frontmatter field, the first sentence of request:, or the prettified epic: slug as a fallback |
Epics are sorted by status priority: BLOCKED first, then IN PROGRESS, ON HOLD, TODO, CANCELLED, DONE last.
Opening the detail drawer
Section titled “Opening the detail drawer”Click any epic card to open the Epic Drawer, a panel that slides in from the right. The drawer shows:
- The full plan prose (the body of
plan.md, rendered as Markdown) - The full execution log (
execution-log.md), parsed into individual phase entries - Both panes side by side
Press Escape or click the backdrop to close the drawer.
Status derivation
Section titled “Status derivation”The status: field at the epic level in plan.md is ignored by the server. It is not read, not written, and not required. Epic status was previously maintained by agents, but stale values after crashes made it unreliable. The server now derives epic status entirely from phase states, which agents do maintain.
The derivation uses this priority order:
BLOCKED > IN_PROGRESS > ON_HOLD > CANCELLED > DONE > TODOIf any phase is blocked, the epic is blocked. If no phase is in progress or blocked, and all phases are done, the epic is done. An epic with zero phases shows TODO.
Note: The dashboard derives a display status for each phase by combining the YAML status with live agent liveness data. If a phase says IN_PROGRESS but the assigned agent’s heartbeat has gone stale or is absent, the dashboard shows that phase as BLOCKED. The plan.md file is not modified. Agents still read and write status as normal. The adjusted value is a read-only server overlay called effectiveStatus and exists only for display purposes.
Status aliases
Section titled “Status aliases”Agents can write common aliases in plan.md. The parser normalizes them before display:
| Alias | Normalized to |
|---|---|
WIP, STARTED, ACTIVE | IN_PROGRESS |
COMPLETE, COMPLETED, FINISHED | DONE |
HOLD, PAUSED, WAITING, SUSPENDED | ON_HOLD |
CANCEL, CANCELED, DROPPED, SKIPPED | CANCELLED |
Anything unrecognized falls back to TODO.
Orders view
Section titled “Orders view”Switch to Orders view to see a flat list of every phase across all visible epics. Each row shows the phase title, the epic it belongs to, the assigned persona, and the phase status badge. Phases are sorted so claimable ones (those with TODO status whose prior phases are all DONE) appear at the top.
This view is the primary tool for detecting abandoned work. When an agent runs out of context mid-epic, or gets interrupted before completing a phase, the phase stays IN_PROGRESS or TODO indefinitely. Neither the Missions card view nor the activity feed will surface it clearly. The epic just looks stalled. The Orders view shows it immediately.
Example scenario: You ran a three-agent crew on a large refactoring epic. The @staff-engineer agent claimed Phase 3 (Implement API layer) and got partway through before running out of context. The terminal closed. Phase 3 is now permanently IN_PROGRESS with no agent alive to finish it, and Phase 4 (Write integration tests) is stuck in TODO because it depends on Phase 3. In the Missions view you see the epic is IN PROGRESS, but you don’t know what’s actually unfinished. In the Orders view you see Phase 3 as IN_PROGRESS with no live heartbeat for @staff-engineer, and Phase 4 as blocked. You can then reset Phase 3 to TODO in the plan.md frontmatter and hand it to a fresh agent to continue from the execution log.
To recover abandoned work: click the epic card for the stalled epic, read the execution log to understand what the previous agent completed, then start a new agent and point it at the phase that needs to be re-claimed.
Filtering by project
Section titled “Filtering by project”If you have multiple projects registered, a project tab bar appears above the epic list. Click a project tab to filter to that project’s epics only. Click All to return to the combined view.
Filtering by agent
Section titled “Filtering by agent”Click any live agent in the sidebar to apply an agent filter. The center column then shows only epics and sessions for that agent’s persona. Click the filter chip or click the agent again to clear the filter.
The .tasks/ directory
Section titled “The .tasks/ directory”Dispatch does not create epics. Your agents do. An epic appears in the dashboard when a directory exists at <project-root>/.tasks/<epic-name>/ and contains a plan.md with valid YAML frontmatter.
Epics in .tasks/.archive/ are not shown. Planners move completed epics there to keep the dashboard clean.
See How It Works for the full plan.md format reference and phase lifecycle.