Type	Alias	Purpose
`feature/`	`feat/`	New features or enhancements
`bugfix/`	`fix/`	Bug fixes
`hotfix/`	—	Urgent production fixes
`release/`	—	Release preparation (dots allowed in version: `release/v1.2.0`)
`chore/`	—	Non-code tasks (deps, docs, config)

AI agent source prefixes — identify branches generated by AI coding agents:

Type	Alias	Purpose
`ai/`	—	Generic prefix for any AI coding agent
`copilot/`	—	GitHub Copilot
`cursor/`	—	Cursor
`claude/`	—	Claude Code by Anthropic
`codex/`	—	OpenAI Codex

Use a vendor-specific prefix when you know which agent is producing the branch; use ai/ as a vendor-neutral fallback.

Trunk Branches

main, master, and develop are trunk branches — they do not use a prefix. Never create new branches with the same names as trunk branches; branch off them instead.

Naming Rules

Lowercase only — no uppercase letters anywhere
Alphanumerics, hyphens, and dots — a-z, 0-9, -, .
Dots are allowed in any description, typically for version numbers (e.g., release/v1.2.0, chore/upgrade-node-v20.11)
No underscores, spaces, or special characters
No consecutive hyphens (--), dots (..), or hyphen-dot adjacency (-. or .-)
No leading or trailing hyphens or dots in the description

Valid Examples

main
master
develop
feature/add-login-page
feat/add-login-page
bugfix/fix-header-bug
fix/header-bug
hotfix/security-patch
release/v1.2.0
chore/update-dependencies
feature/issue-123-new-login
ai/refactor-auth-flow
copilot/add-login-page
cursor/fix-header-bug
claude/security-patch
codex/optimize-query

Invalid Examples

Branch	Problem
`Feature/Add-Login`	Uppercase letters
`feature/new--login`	Consecutive hyphens
`feature/-new-login`	Leading hyphen
`feature/new-login-`	Trailing hyphen
`release/v1.-2.0`	Hyphen adjacent to dot
`fix/header bug`	Space
`fix/header_bug`	Underscore
`unknown/some-task`	Unknown prefix type

Description Guidelines

Use kebab-case with 2-5 words
Be descriptive but concise (~50 chars total)
Good: add-oauth-login, fix-header-overflow, update-ci-config
Bad: fix-bug, new-feature

Workflow

Follow these steps:

Step 1 — Determine Branch Type

Ask the user (if not already clear):

Branch type — default to feature when uncertain
Brief description — what the branch is for

If the user mentions a ticket or issue number, include it in the description (e.g., feature/issue-123-add-oauth).

Step 2 — Validate the Name

Check the assembled name against the Naming Rules above. If any rule fails, fix it:

Lowercase everything
Replace underscores and spaces with hyphens
Collapse consecutive hyphens
Strip leading/trailing hyphens

Step 3 — Detect the Base Branch

Different repos use different trunk branches. Detect which one this repo uses:

# Prefer the remote's default branch
git symbolic-ref --short refs/remotes/origin/HEAD 2>/dev/null | sed 's|^origin/||'

If that returns nothing, check which trunk branch exists locally (priority order: develop, main, master):

for b in develop main master; do
  git show-ref --verify --quiet "refs/heads/$b" && echo "$b" && break
done

Step 4 — Create and Checkout

git checkout <base>
git pull origin <base>
git checkout -b <type>/<description>

Step 5 — Confirm

Tell the user:

The branch name that was created
That they are now on the new branch
Remind them: git push -u origin <branch-name> when ready

Validation

commit-check validates branch names against the specification. Run commit-check --branch, use its check-branch pre-commit hook, or commit-check-action in GitHub Actions. Configuration for GitHub rulesets, GitLab, Bitbucket and Git hooks is at https://conventionalbranch.org/enforce/.

Relationship with Conventional Commits

Conventional Branch complements Conventional Commits:

Conventional Branch	Typical Conventional Commit
`feature/add-login`	`feat: add login page`
`bugfix/fix-header`	`fix: header overflow on mobile`
`chore/update-deps`	`chore: bump lodash to 5.0`
`release/v1.2.0`	`chore: release v1.2.0`

Align the branch type with commit types where possible (e.g., feature/* branches with feat: commits).

conventional-branch

Conventional Branch

Branch Name Format

Branch Types