# Feature-branch (GitHub-flow)

Branch per task off main, open a PR, merge back. This is the default Shelbi shape — the workflow every project ships with, written out in full.

**Feature-branch** (a.k.a. GitHub-flow) is the simplest durable model:
`main` is always deployable, every task cuts a short branch off it, opens
a pull request, and merges back. There are no long-lived integration
branches. The PR *is* the integration point.

This is the model Shelbi's [shipped `task` workflow](/docs/guides/getting-started/workflows#shipped-workflows-task-and-subtask)
already implements, so this guide doubles as a full annotation of the
shipped default. Read it first; the other guides are described as deltas
from this one.

## The board

Each card's branch is cut off `main` when it enters **In Progress**, is
pushed and PR'd on the way to **Review**, and squash-merged back into
`main` on the way to **Done**.

## The workflow

Status identity (the stable `id`, the display `name`, and the
`category`) lives once in `workflows/statuses.yaml`, the project-wide
[status catalog](/docs/guides/getting-started/workflows#schema). Every workflow file
then references those statuses by `id` and adds only what's
workflow-specific (`owner`, and an optional `agent:`). The shipped
catalog is the canonical six:

```yaml
# workflows/statuses.yaml — the status catalog, shared by every workflow.
statuses:
  - { id: backlog,     name: Backlog,     category: backlog }
  - { id: todo,        name: Todo,        category: ready }
  - { id: in-progress, name: In Progress, category: active }
  - { id: review,      name: Review,      category: handoff }
  - { id: done,        name: Done,        category: done }
  - { id: canceled,    name: Canceled,    category: archived }
```

The default workflow references them by `id`. No `name:` or `category:`
is repeated here (the loader rejects a workflow file that does):

```yaml
# workflows/default.yaml
name: default
description: Feature-branch flow — branch per task off main, PR, merge.

# Inherits the project's base_branch: main and merge_strategy from
# project.yaml. A git: block here would only be needed to override them.

statuses:
  - { id: backlog,     owner: user,  agent: orchestrator }
  - { id: todo,        owner: agent, agent: orchestrator }
  - { id: in-progress, owner: agent, agent: developer }
  - { id: review,      owner: user,  agent: orchestrator }
  - { id: done,        owner: user }
  - { id: canceled,    owner: user }

# The shipped default.yaml ships with no active transitions block
# (transitions: None). Unlisted edges are pure status moves, and Shelbi
# treats a transitions-less workflow as the legacy flow that still gates
# the merge on Review -> Done. The scaffolded file offers these as a
# commented, optional block you can uncomment to spell the side effects
# out. Note the accept edge pushes first and does not eagerly delete
# the branch (the merged branch is swept separately, so a bad merge
# stays recoverable):
#
# initial_status: backlog
#
# transitions:
#   - { from: in-progress, to: review,   actions: [push_branch, open_pr] }   # push the task branch, open a PR into main
#   - { from: review,      to: done,     actions: [push_branch, merge] }     # push, then squash-merge the PR
#   - { from: in-progress, to: canceled, actions: [close_pr, delete_branch] }
#   - { from: review,      to: canceled, actions: [close_pr, delete_branch] }
```

Nothing here overrides the project git defaults, so branches cut off
`main` and merges land back on `main`. When you spell out the
transitions, the `open_pr` action opens the PR with `main` as its base
because no transition declares a
[`target:`](/docs/guides/getting-started/workflows#per-transition-target). The
`user`-owned `review` status still names `agent: orchestrator`. That's
what lets [Zen Mode](/docs/concepts/zen-mode) land the merge without you.

## Orchestrator adjustments

None. This is the shape the shipped orchestrator prompt already assumes:
triage into `Backlog`, dispatch `Todo`, hand off to `Review` on the
[review marker](/docs/guides/getting-started/workflows#review-marker-promotion), and
leave the `Review → Done` accept to you. If you turn on
[Zen Mode](/docs/concepts/zen-mode), the merge on `Review → Done` is what
the confidence bar gates.

## See also

- [Workflows](/docs/guides/getting-started/workflows) — the full schema and the
  lifecycle walkthrough this board follows.
- [Trunk-based](/docs/guides/understanding-workflows/trunk-based) — the same model with the
  `Review` gate collapsed and auto-merge turned on.
- [Author a custom Shelbi workflow](/docs/guides/getting-started/custom-workflow)
  — start here when a routing or reporting tweak is worth encoding.