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

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

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

Scope

Required. Must be one of the allowed scopes defined in conventional.config.cjs:

Scope	Description
`ic-suite`	In-house code measurement and validation toolchains (Callidescope, Codependix, Codometer, Conformetry) and their shared conventions
`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)
`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

Description

Required. The description must be:

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

Examples

✅ Good:

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:

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

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

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

# 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
validate-branch-name.config.cjs — Validation config
conventional.config.cjs — Types and scopes

checkout-branch