Conventional Branch

---
name: conventional-branch
description: 'Create Git branches following the Conventional Branch specification (feature/, bugfix/, hotfix/, release/, chore/). Use when creating a new branch, naming a branch, or checking whether a branch name complies with the spec.'
---

# Conventional Branch

Create Git branches that follow the [Conventional Branch](https://conventional-branch.github.io) specification — a simple, consistent convention for naming Git branches.

## Branch Name Format

```
<type>/<description>
```

### Branch Types

| 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) |

### 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 allowed only** in `release/` version descriptions (e.g., `release/v1.2.0`)
- **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
```

## 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:

```bash
# 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`):

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

**Step 4 — Create and Checkout**

```bash
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

## Relationship with Conventional Commits

Conventional Branch complements [Conventional Commits](https://www.conventionalcommits.org):

| 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).

The download contains SKILL.md. Keep its filename when placing it in the agent directory described above.

By GitHub community. Exact upstream source ↗ · Licence · Attribution

SHA-256 94b962ff93ac639c8b760a29465ca48f51d6af1ad1b4bdd242d52f1260959b07

MIT License

Copyright GitHub, Inc.

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.