Git Branch Naming

Branch Types

When in doubt between feat and refactor: if the user will notice the change, use feat. If only the code changes, use refactor.

Short Description Rules

• kebab-case only — all lowercase, words separated by hyphens
• No underscores, no spaces, no special characters except hyphens
• 2–5 words — concise but descriptive enough to understand without looking at the issue
• Use the imperative mood — add-login, fix-crash, not adding-login, fixed-crash
• Max 50 characters for the full branch name (type + optional issue + description)

Good vs Bad

Issue Numbers

• Issue numbers reference GitHub Issues in the repository
• Use the numeric ID as it appears in GitHub (e.g. #42 → use 42)
• When to include: if the user mentions an issue number, or if the work is clearly tracked in GitHub, always include it
• When to omit: exploratory spikes, quick experiments, local-only work, or when the user explicitly has no issue
• Never invent an issue number — if unsure whether one exists, ask the user once

Protected Branches

Never create branches directly named:

• main
• develop
• release/*
• staging

These are managed through PRs only.

Workflow

When asked to start work on a task or create a branch:

1. Identify the type — ask if ambiguous
2. Check for an issue number — if the user mentions one, use it; if not, ask once: "Is there a GitHub Issue for this? If so, what's the number?"; if they say no or don't know, proceed without one
3. Derive a short description from the task or issue title (apply the rules above)
4. Propose the branch name to the user before creating it
5. Create and switch to the branch:

   # With issue
   git switch -c feat/42-add-oauth-login
   
   # Without issue
   git switch -c feat/add-oauth-login
   

If the user provides a branch name that violates these rules, point out the violation and suggest a corrected name before proceeding.