branch-orchestration_skill

Overview

This skill provides intelligent Git branch management with automated naming, issue linking, and lifecycle operations. It enforces the convention {issueNum}-{workType}/{kebab-name}, detects work types from context or labels, and automates creation, renaming, remote sync, and cleanup. Use it to keep branches consistent and traceable to issues.

How this skill works

The skill generates branch names using generateBranchName(issueNumber, workType, title) and converts titles to kebab-case with length limits. It can detect workType from issue labels or text via detectWorkType, validate names with validateBranchName, and extract issue IDs with extractIssueNumber. It also links branches to GitHub issues by updating issue bodies and a local state file (.claude/logs/branch-issues.json), and handles remote renames and deletions to keep refs in sync.

When to use it

• Create a branch from an issue with a consistent, traceable name
• Rename an existing branch to follow project conventions and sync remote
• Automatically link a branch to its GitHub issue for easy tracking
• Run CI validations to enforce branch naming rules
• Bulk-clean merged or stale branches while respecting linked issues

Best practices

• Always use the {issueNum}-{workType}/{kebab-name} pattern for new branches
• Generate branch names from issue metadata when possible (title + labels)
• Validate branch names in CI using validateBranchName before allowing merges
• Keep .claude/logs/branch-issues.json updated when linking branches to issues
• Push new branches with git push -u origin <branch> and remove old remotes when renaming
• Regularly prune merged and stale branches, preferring to check issue state first

Example use cases

• Create branch 42-feature/add-dark-mode from issue #42, push and add a comment linking it to the issue
• Rename a local branch to 123-fix/safari-auth-bug, push the new branch and delete the old remote ref
• Run validateBranchName in CI to block branches that don't match the convention
• Bulk-delete merged branches and only remove those with closed linked issues
• Switch to the branch that corresponds to a given issue number using a simple lookup