# shelbi workflow Manage the per-project workflow YAML files — list, show, scaffold, and edit the status schemas tasks run under. ```text shelbi workflow [OPTIONS] ``` `shelbi workflow` manages the YAML files that declare the statuses a task moves through, who owns each one, and which git side-effects fire on each transition. Every project has a built-in `default` workflow: the canonical five-status flow (`Backlog → Todo → InProgress → Review → Done`). These subcommands surface it alongside any custom workflows the project authors. The default is virtual: it lives in code, not on disk, until `workflow new` or `workflow edit` writes a file. Workflow files live at `/workflows/.yaml`. `` is `~/.shelbi/projects//` in the default [global mode](/docs/concepts/config-modes), `/.shelbi/` in in-repo mode. A file's basename is its name; the in-file `name:` field must match. Most projects never touch this command. Reach for it when you want a second pipeline: a docs-only flow, a research track that never opens PRs, a feature-stacking flow off a long-lived branch. Every subcommand accepts the global `-p / --project ` flag, omitted from the per-subcommand tables below. ## list ```text shelbi workflow list ``` Print every workflow under the project's `workflows/` directory (`~/.shelbi/projects//workflows/` in global mode, `/.shelbi/workflows/` in in-repo mode), one per line, with a count of statuses and the YAML description. A `·` marker in the first column means the workflow is the built-in fallback. No file has been written yet. A blank marker means a file exists on disk. When the workflows directory is empty, the only entry is the built-in `default` workflow. ## show ```text shelbi workflow show ``` Print the workflow's per-status table: `STATUS`, `OWNER`, and `AGENT` for each status, in the canonical `statuses.yaml` order (statuses the workflow doesn't declare are dropped). `show default` works even before any file is written, rendering the built-in default from code; any other missing name errors with the resolved file path. ## new ```text shelbi workflow new [OPTIONS] ``` Scaffold a new workflow YAML pre-populated with the canonical five-status default. The file's `name:` field is set to `` so it matches the basename. For non-`default` names the placeholder description is dropped. The default's "standard one-track flow…" copy would misrepresent a freshly scaffolded workflow whose author hasn't written a real description yet. Errors if a workflow with that name already exists. Names must be non-empty, must not start with `.`, and may only contain `a-z`, `0-9`, `-`, `_`. The name doubles as a YAML identifier referenced from task frontmatter, so the validator is stricter than POSIX. | Flag | Type | Default | Description | | --- | --- | --- | --- | | `` | string | — | Workflow name (positional, required). | | `--edit` | flag | off | Open the new file in `$EDITOR` after creating it. | ## edit ```text shelbi workflow edit ``` Open a workflow YAML in `$EDITOR` (defaults to `vi`). If the file doesn't exist and the name is `default`, the built-in default is materialized to disk first so you have something concrete to tweak. Any other missing name errors with a hint to run `shelbi workflow new ` first. ## Examples See every declared workflow plus the built-in default fallback: ```bash shelbi workflow list ``` Inspect the canonical default before customizing it: ```bash shelbi workflow show default ``` Scaffold a docs-only workflow and open it in `$EDITOR`: ```bash shelbi workflow new docs --edit ``` Materialize the built-in default to disk and edit it: ```bash shelbi workflow edit default ``` ## See also - [Workflows](/docs/guides/getting-started/workflows) — the schema, the category model, and how transitions wire into the orchestrator. - [`shelbi task`](/docs/cli/task) — the `--workflow` flag on `task add` and the workflow-aware `--to` validation on `task move`.