Git branch conventions

Skill bordenet/superpowers-plus/skills/engineering/git-branch-conventions

Use when running git checkout -b, git switch -c, git worktree add -b, or any command that creates a new work branch — enforces semantic prefix naming.From its SKILL.md

Install

npx -y skills add bordenet/superpowers-plus --skill git-branch-conventions

Assembled from the repository path, not quoted from the project. Check it against their README if it does not work.

One thing to look at

8 stars8 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.

SKILL.md

5.7 KB, as published. Nobody here has run it

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:

Prefix	Use For	Examples
`feat/`	New features, user-facing functionality	`feat/scheduler-v3`, `feat/outbound-calling`
`fix/`	Bug fixes, defect corrections	`fix/memory-leak-tts`, `fix/null-check-handler`
`exp/`	Experimental, spike, or throwaway work	`exp/grpc-prototype`, `exp/redis-caching-spike`
`doc/`	Documentation updates only	`doc/api-reference-update`, `doc/onboarding-guide`
`perf/`	Performance and optimization work	`perf/query-optimization`, `perf/reduce-cold-start`
`chore/`	Non-feature maintenance — deps, CI, config, refactors, test harness, repo housekeeping	`chore/bump-deps-march`, `chore/ci-pipeline-fix`

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

Mode	Symptom	Recovery
Non-compliant branch name	PR rejected by CI	Follow type/description pattern
Non-standard prefix used	Confusion in branch listing	Use the six canonical prefixes
Skipping prefix on quick branches	Inconsistent repo	Every work branch gets a prefix
No issue identifier given, or identifier doesn't resolve via `issue-verify`	Branch/commit/PR carries a wrong, fabricated, or missing issue reference	Ask the user for a real identifier; headless with one already in context, verify and use it; headless with neither, stop and report rather than fabricate — unless this project's own policy doesn't require one, in which case proceed and say so