shelbi workflow

shelbi workflow <SUBCOMMAND> [OPTIONS]

shelbi workflow manages the YAML files that declare the statuses an issue moves through, who owns each one, and which git side-effects fire on each transition. shelbi init ships two workflows: task, the review-gated default track (Backlog → Todo → In Progress → Review → Done → Canceled), and subtask, a piece of a parent task that squash-merges into the parent's branch with no PR or review. The project's default_workflow: (set to task at init) picks the one new issues use. The legacy name default is an alias that resolves to task when the project has no default.yaml. These subcommands list and edit the shipped workflows alongside any custom ones you add.

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 blank marker in the first column means the workflow is a file on disk. A multi-line description prints verbatim over several lines.

  subtask              5 statuses     A piece of a parent task, squash-merged into the parent's branch with no PR or review.
  task                 6 statuses     Branch work with a review gate: the default track shipped with every project.

On a legacy project with no workflow files, list shows a single code-built default row marked ·. As soon as any workflow file exists, only on-disk files are listed.

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). Any missing name other than default errors with the resolved file path.

show default prints the legacy built-in from code whenever there's no default.yaml, even on a project where default resolves to task everywhere else, so it may not match the workflow in use (for example, its review agent is orchestrator rather than review). Run shelbi workflow show task to see the shipped default track.

new

shelbi workflow new [OPTIONS] <NAME>

Scaffold a new workflow YAML pre-populated with the canonical six-status default (the five historical lanes plus Canceled). 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 start with a lowercase letter or digit and may contain only a-z, 0-9, -, and _ (an invalid name is reported as an "invalid agent id"). The name doubles as a YAML identifier referenced from issue 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.

The materialize-default path is for legacy projects that predate task and subtask. On a current project, edit task instead: writing a default.yaml stops default from aliasing to task, so issues and settings that name default would switch to that legacy copy (which has no transitions or git actions).

Examples

See every workflow declared in the project:

shelbi workflow list

Inspect the shipped default track before customizing it:

shelbi workflow show task

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

shelbi workflow new docs --edit

Edit the shipped default track:

shelbi workflow edit task

See also

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