Feature-branch (GitHub-flow)
View as markdownFeature-branch (a.k.a. GitHub-flow) is the simplest durable model:
main is always deployable, every issue 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
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. 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:
# 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 shipped task workflow references them by id. No name: or
category: is repeated here (the loader rejects a workflow file that does):
# workflows/task.yaml
name: task
description: 'Branch work with a review gate: the default track shipped with every project.'
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: review, tags: [review] }
- { id: done, owner: user }
- { id: canceled, owner: user }
transitions:
- { from: in-progress, to: review, actions: [push_branch, open_pr] } # push the issue 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] }
git:
base_branch: main
branch: '{{github_user}}/{{id}}' # e.g. you/t-046
merge_strategy: squashgit.base_branch: main means branches are cut off main, and because no
transition declares a
target:,
open_pr opens the PR against main and merge lands it there. 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). The
review status names agent: review with tags: [review]: the hub
daemon's review auto-loader loads each card that reaches Review onto a free
review-tagged workspace, where the Review agent serves the branch for you
to try. See Review workspaces.
Orchestrator adjustments
None. This is the shape the shipped orchestrator prompt already assumes:
triage into Backlog and dispatch Todo. When the developer writes its
ready marker,
the hub moves the card to Review, pushes the branch, and opens the PR. The
Review → Done accept is yours: moving the card to Done runs the merge. If
you turn on Zen Mode, the merge on
Review → Done is what the confidence bar gates.
See also
- Workflows — the full schema and the lifecycle walkthrough this board follows.
- Trunk-based — the same model with the
Reviewgate collapsed and auto-merge turned on. - Customize the orchestrator prompt — start here when a routing or reporting tweak is worth encoding.