speckit-branch-convention-rename

name	speckit-branch-convention-rename
description	Rename non-compliant branches and spec folders to match the configured convention
compatibility	Requires spec-kit project structure with .specify/ directory
metadata	{"author":"github-spec-kit","source":"branch-convention:commands/speckit.branch-convention.rename.md"}

Rename to Convention

Rename non-compliant Git branches and spec folders to match the configured naming convention. Handles both branch renaming and folder moving with full safety checks.

User Input

$ARGUMENTS

You MUST consider the user input before proceeding (if not empty). The user may specify a specific branch to rename (e.g., "004-chat-system") or "all" to rename everything non-compliant.

Prerequisites

1. Verify a spec-kit project exists by checking for .specify/ directory
2. Load convention config from .specify/branch-convention.yml
3. If no convention is configured, inform the user and suggest running /speckit.branch-convention.configure first
4. Check for uncommitted changes (git status --porcelain):
   • If there are uncommitted changes, run git stash push -u -m "speckit-branch-rename-autoStash" to save them
   • Record that a stash was created so it can be restored after renaming
   • If stash fails, abort and inform the user

Outline

1. Run validation first: Execute the same checks as /speckit.branch-convention.validate to identify all non-compliant branches and folders.

2. Build rename plan: For each non-compliant item, compute the correct name:

   Current Name	Convention	New Name	Action
   004-chat-system	{type}/{seq}-{kebab}	feat/004-chat-system	Rename branch, keep folder
   5-api	{seq}-{kebab} (pad 3)	005-api	Rename branch + move folder
   PROJ142-auth	{ticket}-{kebab}	PROJ-142-auth	Rename branch + move folder

3. Present the rename plan: Show a preview table before making any changes:

   # Rename Plan
   
   | # | Current Branch | New Branch | Current Folder | New Folder |
   |---|---------------|------------|----------------|------------|
   | 1 | 004-chat-system | feat/004-chat-system | 004-chat-system | 004-chat-system (unchanged) |
   | 2 | 5-api | feat/005-api | 5-api | 005-api |
   
   **Actions**: {N} branches to rename, {M} folders to move
   

4. Confirm with user: Ask for explicit confirmation before proceeding. This is a destructive operation.

5. Execute renames (after confirmation): For each item in the plan:

   • Rename spec folder: git mv specs/{old} specs/{new} (preserves git history)
   • Update internal references: Search spec.md, plan.md, tasks.md for references to the old folder/branch name and update them
   • Rename git branch: git branch -m {old} {new}
   • Update tracking: If branch tracks a remote, inform user to update remote separately

6. Update references in artifacts: After renaming, scan all spec artifacts for stale references:

   • spec.md header metadata (branch name field)
   • plan.md header metadata
   • tasks.md header metadata
   • Any cross-references between features

7. Restore stash (if one was created in Prerequisites step 4):

   • Run git stash pop to restore the uncommitted changes
   • If git stash pop fails due to conflicts, inform the user and leave stash intact with instructions to resolve manually (git stash pop or git stash show -p)

8. Report: Output a summary:

   • How many branches were renamed
   • How many folders were moved
   • How many artifact references were updated
   • Whether uncommitted changes were stashed and restored
   • Any items that could not be renamed (e.g., currently checked-out branch conflicts)
   • Suggest next step: /speckit.branch-convention.validate to confirm all items are now compliant

Rules

• Never rename without confirmation — always show the plan first and wait for explicit approval
• Auto-stash uncommitted changes — if the working tree is dirty, stash changes automatically before renaming and restore them after; never refuse solely due to uncommitted changes
• Use git mv for folders — preserves git history and tracking
• Update all references — scan artifacts for old names and update to new names
• Never rename main/master/develop — only rename spec-kit feature branches
• Handle checked-out branch — if the current branch needs renaming, rename it last using git branch -m
• Remote branches are informational only — report that remote branches need manual update (git push origin :{old} {new}) but do not push automatically