docs: move git workflow to best practice locations

- Move .woodpecker/GIT_BRANCHING_STRATEGY.md → docs/GIT_WORKFLOW.md
- Add concise Git Workflow section to CONTRIBUTING.md
- Include daily workflow, branch protection, and GitLab Flow reference
- Update Getting Help section with proper doc links
- Update Release Process section to reference new location

Follows best practices:
- Detailed workflow docs in docs/ directory
- Quick reference in CONTRIBUTING.md for daily use
- CONTRIBUTING.md is now the entry point for all contributors

This makes git workflow more discoverable and follows standard
conventions used by major projects (Laravel, React, Django).

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

CONTRIBUTING.md

@@ -68,6 +68,61 @@ Our workflow provides audit trails regulators love:
 
 ---
 
+## Git Workflow & Branching Strategy
+
+**We follow GitLab Flow with environment branches** - an industry-standard workflow for teams with multiple deployment environments.
+
+### Quick Overview
+
+```
+feature/* → develop → master → v2024.MM.X tags
+            (dev)     (staging)  (production)
+```
+
+**Daily Workflow:**
+
+1. **Create feature branch** from `develop`:
+   ```bash
+   git checkout develop
+   git pull origin develop
+   git checkout -b feature/my-feature
+   ```
+
+2. **Make changes** using [conventional commits](#commit-message-format):
+   ```bash
+   git add .
+   git commit -m "feat(scope): description"
+   git push origin feature/my-feature
+   ```
+
+3. **Create Pull Request** to `develop`:
+   - Requires 1 approval
+   - CI must pass (Woodpecker)
+   - Auto-deploys to dev.cannabrands.app on merge
+
+4. **Promote to staging** (when ready):
+   - PR from `develop` → `master`
+   - Requires 2 approvals
+   - Auto-deploys to staging.cannabrands.app
+
+5. **Release to production** (after QA):
+   - Tag from `master` using CalVer: `v2024.11.0`
+   - Auto-deploys to app.cannabrands.com
+
+### Branch Protection
+
+Both `develop` and `master` branches are protected:
+- ✅ All changes require Pull Requests
+- ✅ Direct pushes blocked
+- ✅ CI checks must pass
+- ✅ Code review required
+
+**📖 Full Documentation:** [docs/GIT_WORKFLOW.md](docs/GIT_WORKFLOW.md)
+
+**Official GitLab Flow Guide:** https://docs.gitlab.com/ee/topics/gitlab_flow.html
+
+---
+
 ## Real-World Team Scenarios
 
 ### Scenario 1: Normal Feature Development
@@ -376,7 +431,7 @@ If you're responsible for creating releases, see:
 - **[Quick Reference](.woodpecker/QUICK_REFERENCE.md)** - One-page cheat sheet (print this!)
 - **[Release Workflow](.woodpecker/RELEASE_WORKFLOW_GUIDE.md)** - Complete walkthrough
 - **[Versioning Strategy](.woodpecker/VERSIONING_STRATEGY.md)** - CalVer explained
-- **[Git Branching](.woodpecker/GIT_BRANCHING_STRATEGY.md)** - Branching evolution
+- **[Git Workflow](docs/GIT_WORKFLOW.md)** - GitLab Flow branching strategy
 
 **TL;DR for releases:**
 ```bash
@@ -403,15 +458,17 @@ git push origin master
 ### Documentation
 
 **For daily development:**
-- `CONTRIBUTING.md` - This file (daily workflow)
-- `.githooks/README.md` - Git hooks details
-- `docs/URL_STRUCTURE.md` - Routing architecture
-- `docs/` - API and architecture docs
+- `CONTRIBUTING.md` - This file (daily workflow, git hooks, testing)
+- `docs/GIT_WORKFLOW.md` - Detailed branching strategy (GitLab Flow)
+- `docs/DEVELOPMENT.md` - Local environment setup (Sail, K8s)
+- `docs/URL_STRUCTURE.md` - Routing architecture & conventions
+- `docs/DATABASE.md` - Database schema & migrations
+- `.githooks/README.md` - Git hooks implementation details
 
 **For releases and operations:**
 - `.woodpecker/QUICK_REFERENCE.md` - Release cheat sheet
 - `.woodpecker/RELEASE_WORKFLOW_GUIDE.md` - Full release guide
-- `.woodpecker/VERSIONING_STRATEGY.md` - Versioning & rollback
+- `.woodpecker/VERSIONING_STRATEGY.md` - CalVer versioning & rollback
 
 ### Team
 - Ask in #engineering Slack channel

docs/GIT_WORKFLOW.md

@@ -6,7 +6,143 @@ Your branching strategy should evolve with your team size and customer base. Thi
 
 ---
 
-## Phase 0: Pre-Release (Current)
+## CannaBrands Current Workflow
+
+**We follow GitLab Flow with environment branches.**
+
+GitLab Flow is an industry-standard branching strategy designed for teams with multiple deployment environments. It provides a clear path from development through staging to production, with upstream-first merging.
+
+**Official Documentation:** https://docs.gitlab.com/ee/topics/gitlab_flow.html
+
+### Our Implementation (Three-Tier Model)
+
+```
+feature/* → develop → master → v2024.MM.MICRO
+            (dev)     (staging)  (production)
+```
+
+**Branch Naming Comparison:**
+
+| CannaBrands | GitLab Flow Standard | Purpose |
+|-------------|---------------------|---------|
+| `develop` | `main` | Integration branch |
+| `master` | `staging` | Pre-production environment |
+| `v2024.MM.X` tags | `production` (or tags) | Production releases |
+
+We use `develop`/`master` naming for historical reasons, but the workflow matches GitLab Flow's environment branches pattern exactly.
+
+### Branch Purposes
+
+**feature/*** - Active development, one branch per developer/feature
+- Individual developer work
+- Tested locally or in isolated k8s namespace
+- Merged to `develop` via Pull Request
+
+**develop** - Integration branch (auto-deploys to dev.cannabrands.app)
+- Fast-moving, frequent merges
+- Where features come together for integration testing
+- Can have minor bugs, but should be generally functional
+- **Protected**: Requires PR + 1 approval + CI passing
+
+**master** - Staging environment (auto-deploys to staging.cannabrands.app)
+- Stable, ready for QA and stakeholder testing
+- Only promoted from `develop` when features are complete and tested
+- Must pass all tests and code review
+- **Protected**: Requires PR + 2 approvals + CI passing
+
+**Tags (v2024.11.0)** - Production releases
+- Immutable releases, tagged from `master` after staging validation
+- Uses CalVer versioning (YYYY.MM.MICRO)
+- Deployed to production servers (app.cannabrands.com)
+- Only created after successful QA/stakeholder validation on staging
+
+### Workflow Summary
+
+| Branch | Environment | Purpose | Merge Process | Deploy |
+|--------|-------------|---------|---------------|--------|
+| `feature/*` | Local/K8s namespace | Active development | PR → `develop` (1 approval) | Manual |
+| `develop` | dev.cannabrands.app | Integration testing | PR → `master` (2 approvals) | Auto |
+| `master` | staging.cannabrands.app | QA/stakeholder validation | N/A (promotes to prod via tag) | Auto |
+| `v2024.MM.X` | app.cannabrands.com | Production | N/A (tagged from `master`) | Auto |
+
+### Daily Development Workflow
+
+```bash
+# 1. Create feature branch
+git checkout develop
+git pull origin develop
+git checkout -b feature/my-feature
+
+# 2. Work and commit using conventional commits
+git add .
+git commit -m "feat(scope): description"
+git push origin feature/my-feature
+
+# 3. Create Pull Request: feature/* → develop
+# - Requires 1 approval
+# - CI must pass (Woodpecker)
+# - Auto-deploys to dev.cannabrands.app on merge
+
+# 4. After testing on dev, promote to staging
+# Create Pull Request: develop → master
+# - Requires 2 approvals
+# - CI must pass
+# - Auto-deploys to staging.cannabrands.app on merge
+
+# 5. After QA validation on staging, create production release
+git checkout master
+git pull origin master
+git tag -a v2024.11.0 -m "Release v2024.11.0
+
+Features:
+- Feature 1
+- Feature 2
+
+Fixes:
+- Fix 1"
+
+git push origin v2024.11.0
+# Tag triggers production deployment
+```
+
+### Branch Protection Rules
+
+Both `develop` and `master` branches MUST be protected in Gitea:
+
+**Settings → Repository → Branches → Protected branches**
+
+**For `develop` branch:**
+- ✅ Enable push protection
+- ✅ Allowed to push: Nobody (all changes via PR)
+- ✅ Require pull request reviews: 1 approval minimum
+- ✅ Require status checks to pass: Yes (Woodpecker CI)
+- ✅ Block force push: Yes
+- ✅ Dismiss stale approvals when new commits pushed: Yes
+
+**For `master` branch:**
+- ✅ Enable push protection
+- ✅ Allowed to push: Nobody (all changes via PR)
+- ✅ Require pull request reviews: 2 approvals minimum
+- ✅ Require status checks to pass: Yes (Woodpecker CI)
+- ✅ Block force push: Yes
+- ✅ Dismiss stale approvals when new commits pushed: Yes
+- ✅ Allowed to merge: Team Lead/Admin only
+
+**Why branch protection is critical:**
+- Prevents accidental direct pushes that bypass code review
+- Ensures CI/CD checks run before code reaches environments
+- Maintains git history clarity
+- Forces proper workflow discipline
+
+---
+
+## Evolution Path: How We Got Here
+
+The sections below document the evolution path for git workflows. CannaBrands has already evolved beyond Phase 0 and Phase 1, and is currently operating at Phase 2 with a three-tier model.
+
+---
+
+## Phase 0: Pre-Release (Completed)
 
 **Team Size:** 1-2 developers
 **Customers:** None yet
@@ -539,40 +675,58 @@ git branch --merged master | grep -v "master" | xargs git branch -d
 
 ---
 
-## Summary: Your Transition Path
+## Summary: CannaBrands Current State
 
-### Today (Pre-Release)
-✅ **Direct to master** - current setup
-- Fast iteration
-- No PR overhead
-- Good for solo/pair development
+### ✅ Current Setup (GitLab Flow - Environment Branches)
+**Following GitLab Flow with three-tier deployment** - Operational
+- ✅ Feature branches with code review
+- ✅ Integration branch (`develop`) for dev testing
+- ✅ Staging branch (`master`) for QA validation
+- ✅ Production releases via CalVer tags
+- ✅ CI/CD pipeline (Woodpecker)
+- ⚠️ **ACTION REQUIRED**: Enable branch protection on `develop` and `master`
 
-### First Customer (In 1-3 Months)
-🔜 **Feature branches + PRs**
-- Add code review
-- Protect master branch
-- Enable CI on PRs
+### 🔜 Next Steps (Immediate)
+1. **Enable branch protection in Gitea** (see configuration above)
+   - Prevent direct pushes to `develop` and `master`
+   - Require PR reviews and CI passing
+2. **Document promotion schedule**
+   - When to promote `develop` → `master` (weekly? sprint-based?)
+   - Who approves staging → production releases
+3. **Create release checklist template**
+   - Tag message format
+   - Changelog generation process
+   - Rollback procedures
 
-### Growing Team (In 6-12 Months)
-🔜 **Develop + Master branches**
-- Add staging environment
-- Staged rollouts
-- Better stability
+### 🎯 Future Considerations (6-12+ Months)
+- Release branches for supporting multiple production versions
+- Automated changelog generation from conventional commits
+- Hotfix branch workflow for production emergencies
 
 ---
 
 ## Quick Reference
 
-| Phase | Team Size | Branches | Deploy To | When |
-|-------|-----------|----------|-----------|------|
-| 0: Pre-release | 1-2 | master | dev | Now |
-| 1: Feature branches | 2-5 | master + feature/* | dev | First customer |
-| 2: Environment branches | 5-10 | master + develop + feature/* | staging + prod | Growing team |
-| 3: Release branches | 10+ | master + develop + release/* + feature/* | Multiple envs | Enterprise |
+### CannaBrands Workflow (Current)
 
-**Recommended for Cannabrands:**
-- **Now:** Phase 0 (direct to master)
-- **Next:** Phase 1 (feature branches) - within 2 weeks of first customer
-- **Future:** Phase 2 (develop branch) - when team grows to 5+
+| Branch | Environment | Auto-Deploy | Merge Via | Approvals | Purpose |
+|--------|-------------|-------------|-----------|-----------|---------|
+| `feature/*` | Local/K8s | No | PR to `develop` | 1 | Active development |
+| `develop` | dev.cannabrands.app | Yes | PR to `master` | 2 | Integration testing |
+| `master` | staging.cannabrands.app | Yes | Tag for prod | Admin | QA validation |
+| `v2024.MM.X` | app.cannabrands.com | Yes | N/A | N/A | Production release |
+
+### Evolution Phases (Reference)
+
+| Phase | Team Size | Branches | Deploy To | Status |
+|-------|-----------|----------|-----------|--------|
+| 0: Pre-release | 1-2 | master | dev | ✅ Completed |
+| 1: Feature branches | 2-5 | master + feature/* | dev | ✅ Completed |
+| 2: Environment branches | 5-10 | master + develop + feature/* | staging + prod | ✅ **Current** |
+| 3: Release branches | 10+ | master + develop + release/* + feature/* | Multiple envs | Future |
+
+**CannaBrands follows GitLab Flow (Environment Branches)** with a three-tier model (dev → staging → production).
+
+**Official GitLab Flow Documentation:** https://docs.gitlab.com/ee/topics/gitlab_flow.html
 
 **Key principle:** *"Choose the simplest workflow that meets your current needs. You can always add complexity later."*