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. Verify the working tree is clean (no uncommitted changes) — renaming with dirty state risks data loss

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. Report: Output a summary:

   • How many branches were renamed
   • How many folders were moved
   • How many artifact references were updated
   • 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
• Clean working tree required — refuse to rename if there are 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