Board model
This is the data model behind every Metriq board, the analytics, and the MCP API. It is deliberately small: a fixed set of columns, one work-item shape, and labels (some of which are epics).
The four columns
A Metriq board always has exactly four columns, in this order:
| Column | State value | Meaning |
|---|---|---|
| Backlog | backlog | Captured but not yet committed to. The intake queue. |
| Ready | ready | Committed and refined — pullable into work. |
| In Progress | in_progress | Actively being worked. This is where WIP limits bite. |
| Done | done | Finished. The point at which cycle time stops counting. |
The four columns are fixed by design — they are not a setting, and the absence of custom columns is not a missing feature. Metriq targets teams practising XP-style continuous flow, where the value is in a stable, comparable pipeline rather than a bespoke workflow per team. A fixed pipeline is what makes cycle time, throughput, and forecasts mean the same thing across every team and over time; the moment columns become configurable, those measurements stop being comparable. If your process has an extra stage (e.g. "in review"), model it with a blocked flag, a label, or the agent blessing flow rather than a new column.
The transition that matters most for analytics is in_progress →
done: that is when a work item's clock stops and it becomes a data
point for cycle time and the Monte Carlo forecast. Metriq is
estimate-free by design — it never
asks you to size or point work, because measured cycle time over a stable
four-column flow forecasts more honestly than guesses do.
Work item
A work item (a "ticket" / "card") is the unit that moves across the board. The user-facing fields:
| Field | Type / values | Notes |
|---|---|---|
title | text | Required. |
description | text (markdown) | Optional long-form detail. |
type | story | bug | support | spike | Defaults to story. |
currentState | backlog | ready | in_progress | done | Which column the card is in. |
order | manual, within a column | Cards are prioritized by their position in the column (top = most important), drag-to-reorder, the same order for every viewer. There is no priority tier. |
isBlocked | boolean | A blocked card is flagged on the board; blocked time is tracked separately. |
labels | set of label ids | Tags; some labels are epics (below). |
checklist | list of { text, checked } | In-card decomposition. Max 25 items. Not subtasks — they don't move. |
assignees | set of member ids | Who's on it (humans or agents). |
Two timestamps drive the analytics: startedAt (set when the card first
enters in_progress) and finishedAt (set when it reaches done).
Cycle time is simply the span between them (finishedAt − startedAt).
Blocked time is tracked separately and feeds the distinct flow-efficiency
metric — it is not deducted from cycle time.
Ticket types
Every work item has one type. The type is descriptive, not a
workflow — it never changes how a card moves or what it is worth. It
drives the by-type analytics (cycle time and throughput broken down by
type) and the at-a-glance type dot: every card carries a small colored
header dot keyed to its type — story blue, bug red, support teal,
spike violet — each with a Type: <type> tooltip and aria-label so the
color is always decodable. bug stays red because defects interrupt
planned work and benefit from instant recognition. In keeping with Metriq
being estimate-free, a type is never
a size — it says what kind of work this is, not how big.
| Type | What it's for |
|---|---|
story | A unit of user-facing functionality or value. The default type. |
bug | A defect — something broken or regressed that interrupts planned work. |
support | Maintenance, hardening, or upkeep: keeping the system healthy rather than adding new behaviour. |
spike | A timeboxed investigation to reduce uncertainty. Produces knowledge to unblock work, not a shippable feature. |
Decomposition is in-card, not a tree
Metriq deliberately stops the hierarchy at epic → work item. There are no subtasks. To break a ticket down, use its checklist — a flat, in-card list of up to 25 items. Checklist items are not work items: they have no state and never move across the board, so they never pollute flow analytics with phantom cards.
Labels and epics
A label is a team-scoped tag with a name and a color. Apply any number to a work item.
An epic is simply a label with its isEpic flag set. Promoting a
label to an epic (and demoting it back) is a one-flag change — there is
no separate epic entity and no nesting. Work items carrying an epic
label roll up under it in the epic view; a card can carry more than one
epic label, and an epic is structurally incapable of containing another
epic. Demoting an epic leaves cards still tagged with that (now ordinary)
label; they just lose the rollup.
| Concept | Shape |
|---|---|
| Label | { name, color }, team-scoped, unique name per team. |
| Epic | A label with isEpic: true. Same row, one flag flipped. |
Operating on the model
Everything above is what the MCP tool catalog reads and
writes: get_board returns the four columns and their items;
create_item / update_item / move_item operate on a work item;
list_labels, create_label, set_item_labels, promote_label_to_epic,
and demote_epic operate on labels and epics. The same model backs the
web UI and the flow analytics, so a change made over MCP shows up live in
every open board.