git-branch-conventions

Scope: New work branches only — not permanent branches (main, master, develop), release branches, or sync branches. Repos may have their own branch policies that take precedence.

When to Use

• Running git checkout -b, git switch -c, git branch <name>, or git worktree add -b
• Choosing a name for a new work branch

Before Naming the Branch

Ask whether there's an associated issue in the project's tracker; if yes, get its identifier from the user.

Headless/unattended fallback: use an identifier already present in the current task/session context if one exists; if none exists, stop and report that no identifier is available rather than fabricating one or proceeding silently — unless this project's own policy doesn't require an identifier at all, in which case proceed without one and say so.

Verify the identifier resolves to a real, open issue via the issue-verify skill before using it in a branch name, commit, or PR — never construct an issue reference from memory.

Case consistency: the branch slug is lowercase per "Branch Name Format" below; the commit and PR title use the tracker's canonical case for the identifier, so all three point at the same issue.

Whether an identifier is mandatory at all is a policy call for the project this skill is installed into (set by that project's own contribution docs) — this skill does not mandate one itself.

Semantic Branch Prefixes (REQUIRED)

New work branches MUST start with one of these prefixes:

Decision Guide

Is it throwaway / exploratory?              → exp/
Is it a bug fix?                            → fix/
Is it only documentation?                   → doc/
Is it only performance / optimization?      → perf/
Is it a new feature or behavior change?     → feat/
Everything else (deps, CI, refactor, tests) → chore/

Mixed-purpose branches: Use the prefix that describes the primary intent.

Branch Name Format

{prefix}/{short-description}

Rules:

• Lowercase only
• Hyphens between words (not underscores)
• Descriptive but concise
• Include ticket ID when relevant: fix/proj-1189-null-config

# ✅ CORRECT
git checkout -b feat/outbound-calling
git checkout -b fix/proj-1189-null-config
git checkout -b exp/grpc-spike
git checkout -b chore/bump-node-22
git checkout -b chore/refactor-auth-module

# ❌ WRONG — missing prefix
git checkout -b outbound-calling

# ❌ WRONG — non-standard prefix
git checkout -b feature/outbound         # Use feat/
git checkout -b bugfix/null-check        # Use fix/
git checkout -b refactor/auth-module     # Use chore/
git checkout -b test/add-unit-tests      # Use chore/
git checkout -b hotfix/urgent-patch      # Use fix/

# ❌ WRONG — formatting
git checkout -b FEAT/OUTBOUND           # Uppercase
git checkout -b feat/outbound_calling   # Underscores

Verification

After creating a branch, confirm the name matches all format rules:

branch=$(git branch --show-current)
if echo "$branch" | grep -qE '^(feat|fix|exp|doc|perf|chore)/[a-z0-9]+(-[a-z0-9]+)*$'; then
  echo "✅ Valid: $branch"
else
  echo "❌ Invalid: $branch"
  echo "  Required: {prefix}/{lowercase-hyphenated-description}"
  echo "  Prefixes: feat/ fix/ exp/ doc/ perf/ chore/"
fi

Integration

Note: The obra/superpowers using-git-worktrees skill shows feature/auth in its example. That prefix is non-canonical per this convention — use feat/auth instead. This skill takes precedence for branch naming.

Failure Modes