shelbi workflow

shelbi workflow <SUBCOMMAND> [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 <config-root>/workflows/<name>.yaml. <config-root> is ~/.shelbi/projects/<project>/ in the default global mode, <repo>/.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 <PROJECT> flag, omitted from the per-subcommand tables below.

list

shelbi workflow list

Print every workflow under the project's workflows/ directory (~/.shelbi/projects/<project>/workflows/ in global mode, <repo>/.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

shelbi workflow show <NAME>

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

shelbi workflow new [OPTIONS] <NAME>

Scaffold a new workflow YAML pre-populated with the canonical five-status default. The file's name: field is set to <NAME> 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.

edit

shelbi workflow edit <NAME>

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 <NAME> first.

Examples

See every declared workflow plus the built-in default fallback:

shelbi workflow list

Inspect the canonical default before customizing it:

shelbi workflow show default

Scaffold a docs-only workflow and open it in $EDITOR:

shelbi workflow new docs --edit

Materialize the built-in default to disk and edit it:

shelbi workflow edit default

See also

• Workflows — the schema, the category model, and how transitions wire into the orchestrator.
• shelbi task — the --workflow flag on task add and the workflow-aware --to validation on task move.