# Branching Conventions

Agrarian uses a lightweight branch model until team size, release cadence, or
storefront channels require a heavier workflow.

## Current Model

- `main` is the only long-lived development branch.
- Do not create a long-lived `dev` branch yet.
- Use short-lived task branches for risky, multi-commit, or parallel work.
- Small Codex-only changes may land directly on `main` when the worktree is
  clean, the change is scoped, and validation is run.

## Branch Names

Use lowercase words separated by hyphens:

```text
type/short-description
```

Allowed `type` values:

- `feature/` for new gameplay, tools, systems, or content.
- `fix/` for bugs.
- `docs/` for documentation-only changes.
- `ops/` for infrastructure, build, server, repo, or deployment work.
- `test/` for test-only changes.
- `asset/` for art/content-only changes.
- `experiment/` for throwaway prototypes that are not expected to merge as-is.

Examples:

```text
feature/water-source-interaction
fix/inventory-replication
docs/storage-policy
ops/tile-serving-mvp
asset/ground-zero-foliage-pass
experiment/weather-provider-adapter
```

## Rules

- Keep branches focused on one roadmap item or tightly related slice.
- Prefer branches that can be merged within days, not weeks.
- Rebase or merge from `main` before final validation if the branch has drifted.
- Delete task branches after merge.
- Do not use personal-name branches for project work.
- Do not use vague names such as `updates`, `misc`, `stuff`, or `wip`.
- Do not commit raw terrain source datasets, generated builds, DerivedDataCache,
  or large archive/source-art drops on any branch.

## Future Triggers For A Long-Lived Dev Branch

Create a long-lived staging branch only when one of these becomes true:

- Multiple developers are merging daily.
- Storefront channels need separate internal, investor, alpha, and public build
  tracks.
- Release candidates need stabilization while feature work continues.
- Automated CI checks become strict enough that `main` should only receive
  reviewed, green changes.