speckit-branch-convention-rename
Skill107 starsChanged 9 months agoMITView on GitHub
Rename non-compliant branches and spec folders to match the configured
- Commits and pushes
In this repository48 other files it gives its agents.
- AGENTS.mdAGENTS.md
- .github/copilot-instructions.mdCopilot instructions
- commitSkill
- create-pull-requestSkill
- create-release-branchSkill
- create-release-notesSkill
- handle-pr-reviewSkill
- qlty-checkSkill
- record-code-review-feedbackSkill
- record-spec-feedbackSkill
- recreate-test-dbSkill
- redmine-playwright-loginSkill
- regression-checkSkill
- rubocopSkill
- speckit-agent-context-updateSkill
- speckit-analyzeSkill
- speckit-branch-convention-configureSkill
- speckit-branch-convention-validateSkill
- speckit-checklistSkill
- speckit-clarifySkill
- speckit-constitutionSkill
- speckit-convergeSkill
- speckit-git-commitSkill
- speckit-git-featureSkill
- speckit-git-initializeSkill
- speckit-git-remoteSkill
- speckit-git-validateSkill
- speckit-implementSkill
- speckit-planSkill
- speckit-review-codeSkill
- speckit-review-commentsSkill
- speckit-review-errorsSkill
- speckit-review-runSkill
- speckit-review-simplifySkill
- speckit-review-testsSkill
- speckit-review-typesSkill
- speckit-specifySkill
- speckit-tasksSkill
- speckit-taskstoissuesSkill
- speckit-token-budget-compactSkill
- speckit-token-budget-conciseSkill
- speckit-token-budget-scopeSkill
- speckit-token-budget-usageSkill
- speckit-wiki-ingestSkill
- speckit-wiki-initSkill
- speckit-wiki-lintSkill
- speckit-wiki-querySkill
- speckit-wiki-statusSkill
The file
We split this skill into the rules it gives an agent
7 rules. About 0 are common, 5 are distinctive, and 2 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈5
Distinctive · estimate
This author's own choices. Worth a look.
2
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 29
Verify a spec-kit project exists by checking for .specify/ directory
- Very specific: line 31
If no convention is configured, inform the user and suggest running /speckit.branch-convention.configure first
- Distinctive: line 32
Verify the working tree is clean (no uncommitted changes) — renaming with dirty state risks data loss
- Distinctive: line 59
Confirm with user: Ask for explicit confirmation before proceeding.
- Distinctive: line 63
Update internal references: Search spec.md, plan.md, tasks.md for references to the old folder/branch name and update them
- Distinctive: line 65
Update tracking: If branch tracks a remote, inform user to update remote separately
- Distinctive: line 67
Update references in artifacts: After renaming, scan all spec artifacts for stale references:
≈ “Common” is an estimate: at least 1 in 5 of the 372,429 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Branch Convention Rename Skill
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
$ARGUMENTSYou 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
- Verify a spec-kit project exists by checking for
.specify/directory - Load convention config from
.specify/branch-convention.yml - If no convention is configured, inform the user and suggest running
/speckit.branch-convention.configurefirst - Verify the working tree is clean (no uncommitted changes) — renaming with dirty state risks data loss
Outline
- Run validation first: Execute the same checks as
/speckit.branch-convention.validateto identify all non-compliant branches and folders. 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-systemRename branch, keep folder 5-api{seq}-{kebab}(pad 3)005-apiRename branch + move folder PROJ142-auth{ticket}-{kebab}PROJ-142-authRename branch + move folder 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- Confirm with user: Ask for explicit confirmation before proceeding. This is a destructive operation.
- 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
- Rename spec folder:
- Update references in artifacts: After renaming, scan all spec artifacts for stale references:
spec.mdheader metadata (branch name field)plan.mdheader metadatatasks.mdheader metadata- Any cross-references between features
- 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.validateto 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
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

