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 |
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 |
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 branchdevelop — Development branchrenovate/* — Automated dependency updatesdependabot/* — 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
1---2name: checkout-branch3description: 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.4license: MIT5---6
7# Branch Naming Conventions
8
9This 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.
10
11## When to Use This Skill
12
13- Creating a new feature, fix, or other branch
14- Renaming an existing branch to comply with conventions
15- Understanding why a branch name was rejected
16- Validating branch names before pushing
17
18## Format
19
20```text
21<type>/<scope>-<description>
22```
23
24**All three parts are required.** The description must be kebab-case (lowercase with hyphens).
25
26## Type
27
28**Required.** Must be one of the allowed types defined in [conventional.config.cjs](../../../configuration/conventional.config.cjs):
29
30<!-- types-start -->
31
32| Type | Description |
33| ---- | ----------- |
34| `feat` | A new feature or capability that adds value for users |
35| `fix` | A bug fix that addresses a specific issue or problem |
36| `docs` | Documentation, AGENTS.md, SKILL.md, README, and planning files |
37| `test` | Adding or correcting unit, integration, or end-to-end tests |
38| `refactor` | Code restructuring that neither fixes a bug nor adds a feature |
39| `style` | Formatting, whitespace, or code structure changes with no semantic effect |
40| `perf` | A code change that improves performance (caching, query optimization, etc.) |
41| `chore` | Housekeeping that doesn't modify src or test files (gitignore, editor config, etc.) |
42| `ci` | GitHub Actions workflows, composite actions, and CI/CD scripts |
43| `build` | Build system, Vite/Docker/Helm config, or external dependency integration |
44| `revert` | Reverts a previous commit |
45
46<!-- types-end -->
47
48## Scope
49
50**Required.** Must be one of the allowed scopes defined in [conventional.config.cjs](../../../configuration/conventional.config.cjs):
51
52<!-- scopes-start -->
53
54| Scope | Description |
55| ----- | ----------- |
56| `affirmations` | Python Jupyter notebook application for LangGraph affirmation generation |
57| `caelundas` | Node.js CLI for astronomical calendar generation (NASA JPL ephemeris) |
58| `configuration` | Workspace root config files (tsconfig, eslint, vitest, nx.json, etc.) |
59| `conformetry` | Code generator templates and validation tests for generated instances |
60| `dependencies` | Dependency version changes (upgrades, additions, removals via pnpm) |
61| `deps` | Dependency version changes (upgrades, additions, removals via pnpm) |
62| `deployments` | GitHub Actions workflows and CI/CD pipeline configuration |
63| `documentation` | Markdown docs, skills, planning files, and AGENTS.md files |
64| `infrastructure` | Helm charts, Terraform configs, and Kubernetes resources |
65| `JimmyPaolini` | Static GitHub profile README project (markdown and assets) |
66| `lexico` | TanStack Start SSR Latin dictionary web app with Supabase backend |
67| `lexico-components` | Shared React/shadcn component library |
68| `lexico-entities` | Shared TypeORM entities and GraphQL types |
69| `lexico-ingestion` | Data ingestion scripts for Lexico |
70| `meanderaw` | Greek meander (key/fret) SVG generator CLI and the composable motif/modifier library it reads |
71| `sempientor` | Lexical gap discovery CLI that surveys English for morphological, phonotactic, and semantic gaps and coins words to fill them |
72| `callidescope` | Call stack tracing and linting CLI, the configuration package it reads, and the packages that build and render its call graph |
73| `codependix` | Dependency graph export CLI, the configuration package it reads, and the package that judges the graphs against declared rules |
74| `codometer` | Code statistics measurement CLI, the configuration package it reads, and the packages that diff and render its pull request change report |
75| `no-release` | Escape hatch: suppress semantic-release for any commit type |
76| `release` | Version bumps and release commits generated by semantic-release |
77| `reporting` | Pull request change report generation and the packages that diff and render it |
78| `scripts` | Shell and TypeScript scripts in scripts/ (sync, setup, utilities) |
79| `testing` | Vitest configuration, shared test utilities, and coverage setup |
80| `synchronization` | Synchronization application and commands for automating workflows |
81| `validation` | Validation CLI and the checks it runs, such as pull request metadata |
82
83<!-- scopes-end -->
84
85## Description
86
87**Required.** The description must be:
88
89- **Lowercase** — No capital letters
90- **Kebab-case** — Words separated by hyphens
91- **Descriptive** — Clearly indicate the purpose
92
93### Examples
94
95✅ **Good:**
96
97```bash
98git checkout -b feat/lexico-user-auth
99git checkout -b fix/caelundas-timezone-bug
100git checkout -b docs/codebase-architecture
101git checkout -b chore/dependencies-update-nx
102git checkout -b feat/infrastructure-devcontainer
103```
104
105❌ **Bad:**
106
107```bash
108git checkout -b feat/lexico # Missing description
109git checkout -b fix/caelundas # Missing description
110git checkout -b feature/lexico-auth # Invalid type (use 'feat')
111git checkout -b feat/lexicoAuth # Wrong case (use kebab-case)
112git checkout -b feat/deps-update # Invalid scope (use 'dependencies')
113```
114
115## Special Branches
116
117These branches are exempt from the naming convention:
118
119- `main` — Default branch
120- `develop` — Development branch
121- `renovate/*` — Automated dependency updates
122- `dependabot/*` — Automated dependency updates
123
124## Creating Branches
125
126```bash
127# Feature branch for lexico project
128git checkout -b feat/lexico-dashboard
129
130# Bug fix for caelundas project
131git checkout -b fix/caelundas-timezone
132
133# Documentation update for codebase
134git checkout -b docs/codebase-architecture
135
136# Infrastructure change
137git checkout -b chore/infrastructure-helm-chart
138```
139
140## Renaming Branches
141
142If a branch name is rejected, rename it:
143
144```bash
145# Rename local branch
146git branch -m <type>/<scope>-<description>
147
148# If already pushed, update remote
149git push origin -u <new-branch-name>
150git push origin --delete <old-branch-name>
151```
152
153## Validation
154
155Branch names are validated at multiple stages:
156
157| Stage | Mechanism | Config File |
158| ----- | ----------------------------------------- | --------------------------------- |
159| Local | `configuration/.husky/pre-push` hook | `validate-branch-name.config.cjs` |
160| CI | `.github/workflows/branch-validation.yml` | Same config |
161
162The validation config imports types and scopes from [conventional.config.cjs](../../../configuration/conventional.config.cjs) to ensure consistency with commit message rules.
163
164## Troubleshooting
165
166| Issue | Cause | Solution |
167| --------------------- | ----------------------- | ----------------------------------------------------- |
168| "Branch name invalid" | Missing description | Add `-<description>` after scope |
169| "Unknown scope" | Typo or invalid scope | Check allowed scopes list above |
170| "Unknown type" | Typo or invalid type | Check allowed types list above |
171| "Invalid format" | Wrong separator or case | Use `/` after type, `-` in description, all lowercase |
172
173## Quick Reference
174
175```bash
176# Format
177<type>/<scope>-<description>
178
179# Common patterns
180feat/lexico-feature-name # New feature in lexico
181fix/caelundas-bug-name # Bug fix in caelundas
182docs/documentation-topic # Documentation update
183chore/dependencies-update # Dependency update
184refactor/codebase-cleanup # Refactoring
185
186# Rules
187- Type: lowercase, from allowed list (feat, fix, docs, etc.)
188- Scope: lowercase, from allowed list (project or category)
189- Description: required, lowercase, kebab-case
190- Separator: / between type and scope, - between scope and description
191```
192
193## Resources
194
195- [Conventional Commits](https://www.conventionalcommits.org/)
196- [validate-branch-name.config.cjs](../../../validate-branch-name.config.cjs) — Validation config
197- [conventional.config.cjs](../../../configuration/conventional.config.cjs) — Types and scopes
jimmypaolini