# Checkout Branch

> Create and validate Git branch names following this codebase's Conventional Commits naming convention. Use this skill when creating branches, renaming branches, or when asked about branch naming rules and validation.

- Skill: `jimmypaolini/checkout-branch` (Agent Skill)
- Install (CLI): `npx skillmds@latest add jimmypaolini/checkout-branch`
- Raw SKILL.md: https://api.skillmd.com/api/skills/jimmypaolini/checkout-branch/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- License: MIT
- Author: jimmypaolini (https://skillmd.com/u/jimmypaolini)
- Updated: 2026-09-09
- Page: https://skillmd.com/skills/jimmypaolini/checkout-branch

---


# Branch Naming Conventions

This skill teaches how to name Git branches for this codebase. All branch names **must** follow these rules to pass pre-push hooks and CI validation.

## When to Use This Skill

- Creating a new feature, fix, or other branch
- Renaming an existing branch to comply with conventions
- Understanding why a branch name was rejected
- Validating branch names before pushing

## Format

```text
<type>/<scope>-<description>
```

**All three parts are required.** The description must be kebab-case (lowercase with hyphens).

## Type

**Required.** Must be one of the allowed types defined in [conventional.config.cjs](../../../configuration/conventional.config.cjs):

<!-- types-start -->

| Type | Description |
| ---- | ----------- |
| `feat` | A new feature or capability that adds value for users |
| `fix` | A bug fix that addresses a specific issue or problem |
| `docs` | Documentation, AGENTS.md, SKILL.md, README, and planning files |
| `test` | Adding or correcting unit, integration, or end-to-end tests |
| `refactor` | Code restructuring that neither fixes a bug nor adds a feature |
| `style` | Formatting, whitespace, or code structure changes with no semantic effect |
| `perf` | A code change that improves performance (caching, query optimization, etc.) |
| `chore` | Housekeeping that doesn't modify src or test files (gitignore, editor config, etc.) |
| `ci` | GitHub Actions workflows, composite actions, and CI/CD scripts |
| `build` | Build system, Vite/Docker/Helm config, or external dependency integration |
| `revert` | Reverts a previous commit |

<!-- types-end -->

## Scope

**Required.** Must be one of the allowed scopes defined in [conventional.config.cjs](../../../configuration/conventional.config.cjs):

<!-- scopes-start -->

| Scope | Description |
| ----- | ----------- |
| `affirmations` | Python Jupyter notebook application for LangGraph affirmation generation |
| `caelundas` | Node.js CLI for astronomical calendar generation (NASA JPL ephemeris) |
| `configuration` | Workspace root config files (tsconfig, eslint, vitest, nx.json, etc.) |
| `conformetry` | Code generator templates and validation tests for generated instances |
| `dependencies` | Dependency version changes (upgrades, additions, removals via pnpm) |
| `deps` | Dependency version changes (upgrades, additions, removals via pnpm) |
| `deployments` | GitHub Actions workflows and CI/CD pipeline configuration |
| `documentation` | Markdown docs, skills, planning files, and AGENTS.md files |
| `infrastructure` | Helm charts, Terraform configs, and Kubernetes resources |
| `JimmyPaolini` | Static GitHub profile README project (markdown and assets) |
| `lexico` | TanStack Start SSR Latin dictionary web app with Supabase backend |
| `lexico-components` | Shared React/shadcn component library |
| `lexico-entities` | Shared TypeORM entities and GraphQL types |
| `lexico-ingestion` | Data ingestion scripts for Lexico |
| `meanderaw` | Greek meander (key/fret) SVG generator CLI and the composable motif/modifier library it reads |
| `sempientor` | Lexical gap discovery CLI that surveys English for morphological, phonotactic, and semantic gaps and coins words to fill them |
| `callidescope` | Call stack tracing and linting CLI, the configuration package it reads, and the packages that build and render its call graph |
| `codependix` | Dependency graph export CLI, the configuration package it reads, and the package that judges the graphs against declared rules |
| `codometer` | Code statistics measurement CLI, the configuration package it reads, and the packages that diff and render its pull request change report |
| `no-release` | Escape hatch: suppress semantic-release for any commit type |
| `release` | Version bumps and release commits generated by semantic-release |
| `reporting` | Pull request change report generation and the packages that diff and render it |
| `scripts` | Shell and TypeScript scripts in scripts/ (sync, setup, utilities) |
| `testing` | Vitest configuration, shared test utilities, and coverage setup |
| `synchronization` | Synchronization application and commands for automating workflows |
| `validation` | Validation CLI and the checks it runs, such as pull request metadata |

<!-- scopes-end -->

## Description

**Required.** The description must be:

- **Lowercase** — No capital letters
- **Kebab-case** — Words separated by hyphens
- **Descriptive** — Clearly indicate the purpose

### Examples

✅ **Good:**

```bash
git checkout -b feat/lexico-user-auth
git checkout -b fix/caelundas-timezone-bug
git checkout -b docs/codebase-architecture
git checkout -b chore/dependencies-update-nx
git checkout -b feat/infrastructure-devcontainer
```

❌ **Bad:**

```bash
git checkout -b feat/lexico                  # Missing description
git checkout -b fix/caelundas                # Missing description
git checkout -b feature/lexico-auth          # Invalid type (use 'feat')
git checkout -b feat/lexicoAuth              # Wrong case (use kebab-case)
git checkout -b feat/deps-update             # Invalid scope (use 'dependencies')
```

## Special Branches

These branches are exempt from the naming convention:

- `main` — Default branch
- `develop` — Development branch
- `renovate/*` — Automated dependency updates
- `dependabot/*` — Automated dependency updates

## Creating Branches

```bash
# Feature branch for lexico project
git checkout -b feat/lexico-dashboard

# Bug fix for caelundas project
git checkout -b fix/caelundas-timezone

# Documentation update for codebase
git checkout -b docs/codebase-architecture

# Infrastructure change
git checkout -b chore/infrastructure-helm-chart
```

## Renaming Branches

If a branch name is rejected, rename it:

```bash
# Rename local branch
git branch -m <type>/<scope>-<description>

# If already pushed, update remote
git push origin -u <new-branch-name>
git push origin --delete <old-branch-name>
```

## Validation

Branch names are validated at multiple stages:

| Stage | Mechanism                                 | Config File                       |
| ----- | ----------------------------------------- | --------------------------------- |
| Local | `configuration/.husky/pre-push` hook      | `validate-branch-name.config.cjs` |
| CI    | `.github/workflows/branch-validation.yml` | Same config                       |

The validation config imports types and scopes from [conventional.config.cjs](../../../configuration/conventional.config.cjs) to ensure consistency with commit message rules.

## Troubleshooting

| Issue                 | Cause                   | Solution                                              |
| --------------------- | ----------------------- | ----------------------------------------------------- |
| "Branch name invalid" | Missing description     | Add `-<description>` after scope                      |
| "Unknown scope"       | Typo or invalid scope   | Check allowed scopes list above                       |
| "Unknown type"        | Typo or invalid type    | Check allowed types list above                        |
| "Invalid format"      | Wrong separator or case | Use `/` after type, `-` in description, all lowercase |

## Quick Reference

```bash
# Format
<type>/<scope>-<description>

# Common patterns
feat/lexico-feature-name        # New feature in lexico
fix/caelundas-bug-name          # Bug fix in caelundas
docs/documentation-topic        # Documentation update
chore/dependencies-update       # Dependency update
refactor/codebase-cleanup       # Refactoring

# Rules
- Type: lowercase, from allowed list (feat, fix, docs, etc.)
- Scope: lowercase, from allowed list (project or category)
- Description: required, lowercase, kebab-case
- Separator: / between type and scope, - between scope and description
```

## Resources

- [Conventional Commits](https://www.conventionalcommits.org/)
- [validate-branch-name.config.cjs](../../../validate-branch-name.config.cjs) — Validation config
- [conventional.config.cjs](../../../configuration/conventional.config.cjs) — Types and scopes