Skill Store 33

Checkout Branch

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

by organizzolini · MIT

The skill

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.

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:

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

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

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

Use this skill

Connect your agent to the Skill Store MCP server and ask for it by ref: organizzolini/checkout-branch-46317362891.

Download SKILL.md · Markdown version

Details

Publisher
organizzolini
Category
Software Development › Source control & code review
License
MIT
Updated
2026-10-19

References

More from organizzolini

  • Agent Session Hooks Explains how startup scripts run at the start of agent sessions and inject context.
  • Ask Matt Ask which skill or flow fits your situation.
  • Backup Code Create a safety backup before potentially destructive actions.
  • Brainstorming You MUST use this before any creative work - creating features, building components, adding funct…

Related skills

  • Conventional Branch Create Git branches following the Conventional Branch specification (feature/, bugfix/, hotfix/,…
  • Conventional Git Conventional Commits v1.0.0 branch naming, worktree naming, and commit message standards for GitH…
  • Git Branch Naming Git branch naming conventions — type prefixes (feat/fix/chore), issue linking, kebab-case.
  • Create Branch Create a git branch following Sentry naming conventions.
  • Git Conventions Git conventions and workflow best practices including Conventional Commits, branch naming, and co…