# Understanding Workflows

Deep-dives that map a well-known git branching model — trunk-based, git-flow, feature-branch, or forking — onto a Shelbi Workflow. Assumes you already know what a workflow is; each guide gives the statuses, transitions, and orchestrator tweaks for one model.

These 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](/docs/guides/getting-started/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](/docs/guides/getting-started/custom-workflow) needs to
route and merge the way that model expects.

## The models

Read **[Feature-branch](/docs/guides/understanding-workflows/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 →](/docs/guides/understanding-workflows/trunk-based) |
| **Git-flow** | Long-lived `develop` integration branch with `feature`/`release`/`hotfix` branches. | [Git-flow →](/docs/guides/understanding-workflows/git-flow) |
| **Feature-branch** (GitHub-flow) | Branch per task off `main`, PR, merge. The default Shelbi shape. | [Feature-branch →](/docs/guides/understanding-workflows/feature-branch) |
| **Forking** | Contributions arrive from forks; a review gate stands between them and `main`. | [Forking →](/docs/guides/understanding-workflows/forking) |

<Callout type="note" title="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](/docs/guides/getting-started/workflows#schema) for the full rule.

</Callout>

## See also

- [Workflows](/docs/guides/getting-started/workflows) — the schema every guide is built
  on: statuses, categories, transitions, `target:`, parameterization.
- [Author a custom Shelbi workflow](/docs/guides/getting-started/custom-workflow)
  — how to edit the orchestrator prompt each model's routing note asks for.
- [Zen Mode](/docs/concepts/zen-mode) — the action-based confidence bar
  that gates any transition whose actions include `merge`.