Imported from jimmypaolini/codebase (.agents/skills/rename-branch/SKILL.md). Install upstream with npx skills add jimmypaolini/codebase --skill rename-branch. Copyright stays with the author.

Rename Branch

This skill provides a standardized workflow for renaming a Git branch to comply with the repository's Conventional Commits naming conventions (<type>/<scope>-<description>).

When to Use This Skill

When the user asks to "rename this branch" or "give this branch a better name".
When a branch name is rejected by a pre-push hook or CI validation and needs to be fixed.
When the user wants the agent to automatically deduce a conventional branch name based on the current local changes.

Workflow

When invoked, perform the following steps sequentially:

1. Analyze Changes

Use the terminal to understand what the branch is doing:

Check the current branch: git branch --show-current
Compare with the default branch to see what changed: git diff --name-status main...HEAD
If there are uncommitted changes, check them too: git status -s

2. Determine the Conventional Name

Using the repository's naming convention (<type>/<scope>-<description>):

Type: Choose the appropriate type based on the nature of the changes.

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: Identify the scope based on the directory of the modified files.

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: Formulate a concise, lowercase, kebab-case description (e.g., add-user-auth).

Note: If multiple scopes are touched, list them comma-separated in the title (e.g., feat(lexico,logger): ...) rather than reaching for a single umbrella scope.

3. Create a Backup (Safety First)

Be very cautious before taking any destructive actions (renaming or deleting remote branches). Always create a temporary backup branch to ensure no work is lost:

Preferred approach: invoke backup-code before renaming so backup creation and recovery commands are documented.

branch_name="$(git branch --show-current)"
iso_timestamp="$(date -u +%Y-%m-%dT%H-%M-%SZ)"
git branch "backup/${branch_name}/${iso_timestamp}"

4. Execute the Rename

Proceed automatically with the best determined name without asking the user for permission. Run the appropriate Git commands to rename the branch.

git branch -m <type>/<scope>-<description>

5. Update Remote (If Applicable)

If the old branch was already pushed to the remote (git status shows it tracking an origin branch), you must push the new branch and delete the old one:

git push origin -u <new-branch-name>
git push origin --delete <old-branch-name>

If remote cleanup or rename operations are incorrect, use restore-code with the backup branch to recover safely.

Example Scenarios

Scenario 1: Uncommitted feature in lexico

Changes: Modified applications/lexico/src/components/Button.tsx
Derived Name: feat/lexico-button-component
Action: git branch backup/old-name/2026-06-22T12-00-00Z, then git branch -m feat/lexico-button-component

Scenario 2: Pushed bugfix in caelundas

Changes: Modified applications/caelundas/src/utils/time.ts (already pushed as fix-time)
Derived Name: fix/caelundas-time-calculation
Action: git branch backup/fix-time/2026-06-22T12-00-00Z, then git branch -m fix/caelundas-time-calculation, push new, and delete old remote.

rename-branch

About