branch

Disciplined Git Flow

Use this workflow whenever managing branches. Treat branch history as a shared coordination system. Optimize for safety, explicit intent, and repository hygiene over speed or convenience.

Branch model

• main represents production-ready code only.
• develop is the primary development and integration branch.
• feature/*, fix/*, chore/*, refactor/*, test/*, and docs/* branches start from develop.
• release/* branches start from develop.
• hotfix/* branches start from main.
• Completed work normally merges back into develop.
• release/* and hotfix/* branches merge into main and then back into develop.

Allowed branch types

• feature/* for new functionality.
• fix/* for non-urgent bug fixes targeting development.
• hotfix/* for urgent production fixes from main.
• release/* for release preparation.
• chore/* for maintenance work.
• refactor/* for internal restructuring.
• test/* for test-only work.
• docs/* for documentation-only work.

Available helpers

• scripts/validate.py validates branch names, expected bases, and allowed merge source/target combinations.
• references/checklist.md contains the required safety gates for creation, switching, merging, release, and hotfix operations. Read it before the first branch operation in a session and whenever a branch operation is ambiguous.

Non-negotiable safety rules

• Before any branch operation, run git status --short.
• Never create, delete, rename, reset, rebase, merge, or switch branches before inspecting current Git state.
• Never discard, overwrite, or hide user changes.
• If uncommitted changes exist, leave them untouched unless they were created by the agent in the current run.
• Do not use destructive commands such as git reset --hard, git clean, git checkout --, git restore, forced branch deletion, or force push.
• Do not use broad or ambiguous commands when a narrower command is available.
• Use explicit branch names in commands.
• Do not assume the current branch is correct. Verify it first.
• If validation fails, stop and report the exact failed gate.

Required preflight

Before creating, switching, or merging:

1. Run:

   git status --short
   git branch --show-current
   

2. Use gh for repository coordination context when helpful:

   gh auth status
   gh pr view <number> --json headRefName,baseRefName,state,title
   gh issue view <number>
   

   Do not mutate GitHub state unless the user explicitly asked for that action.

3. Verify all of the following:

   • current branch
   • working tree status
   • intended base branch
   • intended target branch
   • branch naming compliance
   • whether uncommitted changes exist

4. If uncommitted changes exist, do not proceed with branch operations unless the user explicitly approves a precise plan that preserves those changes.

Branch naming

Branch names must use:

<type>/<short-description>

Rules:

• lowercase kebab-case only
• exactly one /
• no spaces
• no uppercase letters
• no special characters except / and -
• clear, intent-based description
• no vague names such as updates, changes, work, misc, or stuff

Examples:

feature/add-user-session-timeout
fix/handle-empty-api-response
hotfix/patch-login-token-expiry
release/1.4.0
docs/update-api-auth-guide

Validate names before using them:

python3 scripts/validate.py name feature/add-user-session-timeout
python3 scripts/validate.py name release/1.4.0

Creating branches

Create branches only from the correct base:

• feature/*, fix/*, chore/*, refactor/*, test/*, and docs/* from develop
• release/* from develop
• hotfix/* from main

Required sequence:

1. Run the required preflight.

2. Validate the requested branch name:

   python3 scripts/validate.py name <branch>
   

3. Validate the required base:

   python3 scripts/validate.py base <branch> <base>
   

4. Verify the base branch exists locally or remotely with explicit names:

   git rev-parse --verify develop
   git rev-parse --verify main
   

5. If the correct base does not exist, stop and report the issue.

6. If the working tree is dirty, stop unless the user approved a precise preservation plan.

7. Create the branch from the verified base with explicit branch names. Prefer the safest command available in the active environment.

Merging branches

Never merge without verifying source and target branches.

Allowed merge targets:

• Into main: only from release/* or hotfix/*.
• Into develop: from completed work branches, release/*, or hotfix/*.

Required sequence:

1. Run the required preflight.

2. Ensure the working tree is clean.

3. Verify source and target branches by exact name.

4. Validate the merge:

   python3 scripts/validate.py merge <source> <target>
   

5. Confirm the source branch contains completed, coherent, reviewed, and validated work.

6. Merge one branch at a time.

7. If conflicts occur, stop. Report the conflicted files and the decision needed. Do not guess conflict resolutions.

Release branches

• Use release/<version>, for example release/1.4.0.
• Start from develop.
• Use release branches for stabilization only.
• Allow only bug fixes, documentation updates, version bumps, changelog updates, and release metadata.
• Do not add unrelated features.
• On completion, merge into main.
• Then merge the same release branch back into develop.

Hotfix branches

• Use hotfix/<short-description>.
• Start from main.
• Keep hotfixes minimal and production-focused.
• Do not include unrelated cleanup, refactors, or non-critical changes.
• On completion, merge into main.
• Then merge the same hotfix branch back into develop.

Integration discipline

• Protect develop from incomplete or unrelated work.
• Integrate only completed, reviewed, and validated branches.
• If multiple branches need integration, merge them one at a time.
• Preserve clear branch history over convenience.
• Stop whenever the branch state, target, or ownership is ambiguous.