Understanding Workflows
View as markdownThese are reference deep-dives for readers who already know the workflow basics. If a Shelbi Workflow (the per-project YAML that declares the statuses a task moves through and the git side-effects that fire on each transition) is new to you, start with Workflows for the fundamentals, then come back here.
Shelbi doesn't impose a branching model. Each guide below takes one well-known git branching model and shows the Shelbi Workflow that implements it: the statuses it references, the transitions that push, PR, and merge branches in the right place, and any adjustment the orchestrator prompt needs to route and merge the way that model expects.
The models
Read Feature-branch first. It's the model Shelbi ships by default, written out in full, and the other three guides are described as deltas from it.
| Model | Shape | Guide |
|---|---|---|
| Trunk-based | Short-lived branches, merge to main fast. Pairs naturally with Zen auto-merge. | Trunk-based → |
| Git-flow | Long-lived develop integration branch with feature/release/hotfix branches. | Git-flow → |
| Feature-branch (GitHub-flow) | Branch per task off main, PR, merge. The default Shelbi shape. | Feature-branch → |
| Forking | Contributions arrive from forks; a review gate stands between them and main. | Forking → |
Statuses are defined once, referenced by id
Every guide shows two YAML shapes. Status identity (id, name, and
category) is declared once in workflows/statuses.yaml, the
project-wide status catalog. Each workflow file references statuses by
id and adds only its owner and optional agent:; it never repeats
name: or category: (the loader rejects a workflow that does). See
Workflows → Schema for the full rule.
See also
- Workflows — the schema every guide is built
on: statuses, categories, transitions,
target:, parameterization. - Author a custom Shelbi workflow — how to edit the orchestrator prompt each model's routing note asks for.
- Zen Mode — the action-based confidence bar
that gates any transition whose actions include
merge.