Git Branch Management Skill
This skill guides AI agents and human contributors on how to create, name, structure, and navigate Git branches cleanly and safely across repositories.
1. Core Branching Principles
git switch -c <github-username>/<parent-branch>/<feature>). Never develop or commit directly on main or dev.main.git switch -c).<github-username>/<parent-branch>/<feature>.main is the sole production integration branch. Never open PRs against dev or temporary feature branches.- Agents may create or switch between local branches directly.
- STRICT RULE: Agents MUST NOT push branches to a remote repository automatically. Pushing and opening PRs is permitted ONLY upon explicit human request.
- STRICT RULE: Agents MUST NEVER force-push (git push --force) or delete remote branches.
2. Branch Naming Convention
All development branches MUST follow the standard structure:
<github-username>/<parent-branch>/<feature>Components Breakdown
<github-username>: GitHub username of the author.<parent-branch>: Target base branch name (typically main).<feature>: Concise, kebab-case description of the feature or fix (e.g. database-auto-sync, precommit-workflow, branch-first-migration).Rules
3. Canonical Branch Workflow Runbook
For Human Contributors
# 1. Update main branch
git checkout main
git pull origin main
# 2. Create and switch to new branch
git switch -c <github-username>/main/my-feature
# 3. Develop, validate, and commit
make pre-commit
git add .
git commit -s -S -m "feat(worker): add new capability"
# 4. Push and open PR
git push -u origin <github-username>/main/my-feature
gh pr create --base main --head <github-username>/main/my-feature --title "feat(worker): add new capability" --body "..."For AI Agents
```bash
git status
git branch -a
```
main and pull latest changes:```bash
git switch main
git pull origin main
```
```bash
git switch -c <github-username>/<parent-branch>/<feature>
```
-s and -S.main.4. Single Open PR Mandate & Preventing Merge Conflicts
To ensure continuous delivery without merge conflict deadlock:
gh pr list --state open before creating a new branch.main, DO NOT create a new branch or open a secondary PR. Check out the existing PR's branch (git checkout <open-branch>), implement all requested changes there, and push to that same branch.main is updated while a PR is open, rebase your branch on origin/main (git fetch origin && git rebase origin/main), re-verify with pre-commit gates, and push with --force-with-lease.5. Merging & Local Branch Cleanup
main on GitHub and upon explicit human user instruction, perform safe branch cleanup:```bash
git switch main
git pull origin main
git fetch --prune origin
git branch | grep -v "^\* main$" | grep -v "^ main$" | xargs -r git branch -D
git reflog expire --expire=now --all
git gc --prune=now --aggressive
```
.agents/skills/git-post-merge-cleanup/SKILL.md.