Statuses

View as markdown

statuses.yaml is the single source of truth for status identity in a project. Every workflow references these entries by id and inherits their name and category; workflows may pick a subset but cannot reorder or rename them. Declaration order here is the canonical left-to-right column order on the board's all-workflows view.

Where it lives

<config-root>/workflows/statuses.yaml

<config-root> is ~/.shelbi/projects/<name>/ in the default global mode and <repo>/.shelbi/ in in-repo mode, the same directory as the workflow files.

Editing from Settings

You don't have to edit the file by hand. Settings ▸ Workflows, in the desktop app and in the TUI (press , in the sidebar, then 4), lists the catalog with the workflows that use each status. From there you can add a status, rename it (its id never changes, so workflows keep pointing at it), change its category, reorder it, and delete one no workflow uses. Each change is saved to this file as you make it, comments and unknown keys included, and Edit YAML opens the file itself. If the file changed on disk since the page read it, nothing is written: the page reloads and says so.

Example

# ~/.shelbi/projects/myapp/workflows/statuses.yaml
statuses:
  - { id: backlog,     name: Backlog,     category: backlog }
  - { id: todo,        name: Todo,        category: ready }
  - { id: in-progress, name: In Progress, category: active }
  - { id: review,      name: Review,      category: handoff }
  - { id: done,        name: Done,        category: done }
  - { id: canceled,    name: Canceled,    category: archived }

Top-level fields

Field	Type	Required	Default	Description
`statuses`	list of Status	yes	—	Ordered catalog of every status in the project. Order is significant: it's the column order on the board's all-workflows view.

status

Field	Type	Required	Default	Description
`id`	string	yes	—	Stable identifier referenced from every workflow's `statuses:` list. Must be unique and non-empty. Conventionally lowercase kebab-case.
`name`	string	yes	—	User-facing display label (e.g. `Backlog`, `In Progress`). Must be non-empty.
`category`	category	yes	—	Closed semantic category. Generic code keys off this, so a renamed status keeps its behavior.

categories

The category field is a closed vocabulary of exactly six values: generic code (the orchestrator, Zen Mode, event-log reactions) keys off the category, not the display name, so renaming a status leaves its semantics intact. See status categories.

Category	Meaning
`backlog`	Not yet ready for work — triage stage.
`ready`	Ready to be picked up by whoever owns it.
`active`	Owner is working on it now.
`handoff`	One owner finished their part; another's input is required next.
`done`	Terminal — accepted, shipped.
`archived`	Terminal — closed without shipping (cancelled, won't fix, duplicate).

At least one terminal category

Loading fails if no status has category done or archived. A board with no terminal state is degenerate, since a task could never leave it. Beyond that, the terminal categories done and archived may repeat cleanly (a pipeline can carry several done-like or archived-like lanes). The single-instance categories (backlog, ready, and handoff) raise a non-fatal warning if any of them appears more than once, as does a missing handoff. active may repeat freely: a second active status is how you add an agent gate (for example adversarial-review) before review, and it loads with no warning.