From 0ca351a39be73656ba14e3152acbe7c0de495dc2 Mon Sep 17 00:00:00 2001
From: Aster Seker <git.electroyar@gmail.com>
Date: Fri, 22 May 2026 11:08:46 +0300
Subject: [PATCH] docs(git): add branch policy and workflow rules

- Require feature branches for all changes; prohibit direct main commits.
- Mandate fetching and pulling latest main before creating a branch.
- Document branch naming prefixes (feat/, fix/, refactor/, etc.).
- Add agent rule: verify main is current, create branch, push for PR.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
---
 guides/README.md       |  1 +
 guides/git-workflow.md | 63 ++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 64 insertions(+)
 create mode 100644 guides/git-workflow.md

diff --git a/guides/README.md b/guides/README.md
index 86c30a4..65ce81a 100644
--- a/guides/README.md
+++ b/guides/README.md
@@ -22,6 +22,7 @@ These files are shared AI-agent instruction files for `log-it-cpp`.
 | `logging-macros.md` | Macro-first logging guidance for agents and maintainers. |
 | `build.md` | Build, test, example, and benchmark flows. |
 | `commits.md` | Commit message conventions and grouping rules. |
+| `git-workflow.md` | Branch policy, naming conventions, and required steps before starting work. |
 
 ## Maintenance
 
diff --git a/guides/git-workflow.md b/guides/git-workflow.md
new file mode 100644
index 0000000..3387dba
--- /dev/null
+++ b/guides/git-workflow.md
@@ -0,0 +1,63 @@
+# Git Workflow
+
+## Branch Policy
+
+All code changes must go through a feature branch and a pull request.
+Never commit directly to `main`.
+
+## Required Steps Before Creating a Branch
+
+1. Check the current state:
+   ```bash
+   git status
+   git branch -vv
+   ```
+2. Update `main` to the latest remote state:
+   ```bash
+   git fetch origin
+   git checkout main
+   git pull origin main
+   ```
+3. Only after `main` is up-to-date, create the feature branch:
+   ```bash
+   git checkout -b <prefix>/<short-description>
+   ```
+
+## Branch Naming
+
+| Prefix | Use for |
+| --- | --- |
+| `feat/` | New functionality |
+| `fix/` | Bug fixes |
+| `refactor/` | Code restructuring without behavior changes |
+| `test/` | Adding or modifying tests only |
+| `docs/` | Documentation changes |
+| `chore/` | Build, CI, dependency, or maintenance tasks |
+| `perf/` | Performance improvements |
+
+Examples:
+- `feat/otlp-gzip-compression`
+- `fix/payload-splitter-overflow`
+- `test/backpressure-race`
+
+## Workflow
+
+1. Create a focused branch from up-to-date `main`.
+2. Make atomic commits with conventional messages (see `commits.md`).
+3. Push the branch to origin:
+   ```bash
+   git push -u origin <branch-name>
+   ```
+4. Open a pull request on GitHub.
+5. Merge only after review and passing CI.
+
+## Agent Rule
+
+When starting any non-trivial task (feature, bug fix, improvement), an AI agent must:
+
+1. Verify `main` is current with `origin/main`.
+2. Create a feature branch with an appropriate prefix.
+3. Do all work on that branch.
+4. Push the branch and instruct the user to open a PR instead of merging directly.
+
+Trivial one-line fixes or documentation typos may be committed to `main` only when explicitly requested by the user.