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.
1---2name: rename-branch3description: Rename a git branch. Analyzes changes against the main branch, decides on a conventional name, and executes the rename.4---5
6# Rename Branch
7
8This skill provides a standardized workflow for renaming a Git branch to comply with the repository's Conventional Commits naming conventions (`<type>/<scope>-<description>`).
9
10## When to Use This Skill
11
12- When the user asks to "rename this branch" or "give this branch a better name".
13- When a branch name is rejected by a pre-push hook or CI validation and needs to be fixed.
14- When the user wants the agent to automatically deduce a conventional branch name based on the current local changes.
15
16## Workflow
17
18When invoked, perform the following steps sequentially:
19
20### 1. Analyze Changes
21
22Use the terminal to understand what the branch is doing:
23
24- Check the current branch: `git branch --show-current`
25- Compare with the default branch to see what changed: `git diff --name-status main...HEAD`
26- If there are uncommitted changes, check them too: `git status -s`
27
28### 2. Determine the Conventional Name
29
30Using the repository's naming convention (`<type>/<scope>-<description>`):
31
32**Type**: Choose the appropriate type based on the nature of the changes.
33<!-- types-start -->
34
35| Type | Description |
36| ---- | ----------- |
37| `feat` | A new feature or capability that adds value for users |
38| `fix` | A bug fix that addresses a specific issue or problem |
39| `docs` | Documentation, AGENTS.md, SKILL.md, README, and planning files |
40| `test` | Adding or correcting unit, integration, or end-to-end tests |
41| `refactor` | Code restructuring that neither fixes a bug nor adds a feature |
42| `style` | Formatting, whitespace, or code structure changes with no semantic effect |
43| `perf` | A code change that improves performance (caching, query optimization, etc.) |
44| `chore` | Housekeeping that doesn't modify src or test files (gitignore, editor config, etc.) |
45| `ci` | GitHub Actions workflows, composite actions, and CI/CD scripts |
46| `build` | Build system, Vite/Docker/Helm config, or external dependency integration |
47| `revert` | Reverts a previous commit |
48
49<!-- types-end -->
50
51**Scope**: Identify the scope based on the directory of the modified files.
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**: Formulate a concise, lowercase, kebab-case description (e.g., `add-user-auth`).
86
87_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._
88
89### 3. Create a Backup (Safety First)
90
91Be very cautious before taking any destructive actions (renaming or deleting remote branches). Always create a temporary backup branch to ensure no work is lost:
92
93Preferred approach: invoke [backup-code](../backup-code/SKILL.md) before renaming so backup creation and recovery commands are documented.
94
95```bash
96branch_name="$(git branch --show-current)"
97iso_timestamp="$(date -u +%Y-%m-%dT%H-%M-%SZ)"
98git branch "backup/${branch_name}/${iso_timestamp}"
99```
100
101### 4. Execute the Rename
102
103Proceed automatically with the best determined name without asking the user for permission. Run the appropriate Git commands to rename the branch.
104
105```bash
106git branch -m <type>/<scope>-<description>
107```
108
109### 5. Update Remote (If Applicable)
110
111If 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:
112
113```bash
114git push origin -u <new-branch-name>
115git push origin --delete <old-branch-name>
116```
117
118If remote cleanup or rename operations are incorrect, use [restore-code](../restore-code/SKILL.md) with the backup branch to recover safely.
119
120## Example Scenarios
121
122### Scenario 1: Uncommitted feature in lexico
123
124- _Changes_: Modified `applications/lexico/src/components/Button.tsx`
125- _Derived Name_: `feat/lexico-button-component`
126- _Action_: `git branch backup/old-name/2026-06-22T12-00-00Z`, then `git branch -m feat/lexico-button-component`
127
128### Scenario 2: Pushed bugfix in caelundas
129
130- _Changes_: Modified `applications/caelundas/src/utils/time.ts` (already pushed as `fix-time`)
131- _Derived Name_: `fix/caelundas-time-calculation`
132- _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.
jimmypaolini