---
name: git-branch-management
description: >-
  Rules and procedures for creating, naming, structuring, and navigating Git branches
  in the repository for both human contributors and AI agents.
---

# 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

1. **Mandatory Local Branch Creation**: Prior to modifying any code, configuration, or documentation files for ANY task, you MUST ALWAYS create and switch to a dedicated local branch (`git switch -c <github-username>/<parent-branch>/<feature>`). Never develop or commit directly on `main` or `dev`.
2. **Branch-First Development**: All changes (features, fixes, refactoring, tests, docs) are developed directly on Git branches created from `main`.
3. **Strict No-Worktree Rule**: AI agents and contributors must **NOT** create or use Git worktrees for standard development tasks. All work occurs in the primary repository clone via branch switching (`git switch -c`).
4. **Structured Hierarchical Naming**: Branch names follow the standard format `<github-username>/<parent-branch>/<feature>`.
5. **All Pull Requests Target `main`**: `main` is the sole production integration branch. Never open PRs against `dev` or temporary feature branches.
6. **Agent Safety Boundaries**:
   - 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:

```text
<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
- **Lowercase**: All characters lowercase.
- **Kebab-Case**: Hyphen-separated words for the feature portion.
- **Concise**: 2-4 descriptive words.
- **No Timestamps/Hashes**: Avoid timestamps or random suffixes unless required for uniqueness.

---

## 3. Canonical Branch Workflow Runbook

### For Human Contributors
```bash
# 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
1. Inspect repository and branch status (do NOT spawn worktrees):
   ```bash
   git status
   git branch -a
   ```
2. Switch to `main` and pull latest changes:
   ```bash
   git switch main
   git pull origin main
   ```
3. Create local branch:
   ```bash
   git switch -c <github-username>/<parent-branch>/<feature>
   ```
4. Develop directly on that branch, run pre-commit validations, and commit locally with `-s` and `-S`.
5. When explicitly requested by the user, push to remote and open a PR targeting `main`.

---

## 4. Single Open PR Mandate & Preventing Merge Conflicts

To ensure continuous delivery without merge conflict deadlock:
- **Mandatory Pre-Branch Check**: Always run `gh pr list --state open` before creating a new branch.
- **Consolidate into Existing Open PR**: If an open PR already exists targeting `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.
- **Open New PR Only on Clean State**: Create a new feature branch and open a new PR ONLY when zero open PRs exist.
- **Rebasing**: If `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

1. Once a Pull Request is merged into `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
   ```
2. **Explicit Instruction Only**: AI agents must only execute branch cleanup when explicitly asked by the user after PR merge.
3. See `.agents/skills/git-post-merge-cleanup/SKILL.md`.