# Checkout Branch

> Create and validate Git branch names following this codebase's Conventional Commits naming conven…

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.

- Page: https://ss33.ai/skills/organizzolini/checkout-branch-46317362891
- Publisher: organizzolini
- Category: [Software Development](https://ss33.ai/skills/category/software-development-t44z8z) › [Source control & code review](https://ss33.ai/skills/category/software-development-t44z8z/source-control-and-code-review-jebezw)
- License: MIT
- Source: https://github.com/organizzolini/codebase/blob/dfcbcaf78074c8a6e2b449048e15cf63cd8c49ce/.agents/skills/checkout-branch/SKILL.md

## Skill

SKILL.md: https://ss33.ai/api/v1/ss33/download/organizzolini/checkout-branch-46317362891

# 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](../../../projects/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](../../../projects/configuration/conventional.config.cjs):

<!-- scopes-start -->

| Scope | Description |
| ----- | ----------- |
| `ic-suite` | In-house code measurement and validation toolchains (Callidescope, Codependix, Codometer, Conformetry) and their shared conventions |
| `affirmancy` | 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 |
| `database` | Shared Postgres package: environment, TypeORM module, base entities, test harness, and migrations |
| `dependencies` | 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 |
| `installation` | Developer-machine setup commands that run once Node is installed (environment files, dependencies, shell configuration, software) |
| `integration` | Continuous Integration plumbing: the steps that run around a CI job, such as the affected run and the Nx task-cache database |
| `JimmyPaolini` | Static GitHub profile README project (markdown and assets) |
| `lexico` | TanStack Start SSR Latin dictionary web app with Supabase backend |
| `components` | Shared React/shadcn component library |
| `lexico-entities` | Shared TypeORM entities and GraphQL types |
| `lexico-cli` | 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 |
| `publication` | Publication CLI: the CI release steps and the publishable-packages gate |
| `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 | `projects/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](../../../projects/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](../../../projects/configuration/conventional.config.cjs) — Types and scopes