docs(workflow): formalize gitflow process and templates

docs/workflow.md

@@ -0,0 +1,77 @@
+# GitFlow Workflow Notes
+
+This document is the operational reference for branch and release flow in HoopScout.
+
+## Branch Types
+
+- `main`: production
+- `develop`: integration
+- `feature/*`: new work from `develop`
+- `release/*`: release preparation from `develop`
+- `hotfix/*`: urgent production fixes from `main`
+
+## Branch Start Commands
+
+Create `develop` from current `main`:
+
+```bash
+git checkout main
+git pull origin main
+git checkout -b develop
+git push -u origin develop
+```
+
+Create `feature/*`:
+
+```bash
+git checkout develop
+git pull origin develop
+git checkout -b feature/<scope>-<short-description>
+```
+
+Create `release/*`:
+
+```bash
+git checkout develop
+git pull origin develop
+git checkout -b release/<major>.<minor>.<patch>
+```
+
+Create `hotfix/*`:
+
+```bash
+git checkout main
+git pull origin main
+git checkout -b hotfix/<scope>-<short-description>
+```
+
+## Release Flow
+
+1. Branch `release/x.y.z` from `develop`.
+2. Freeze feature work on release branch (only bugfix/docs/changelog).
+3. Validate in Docker and test suite.
+4. Merge release branch into `main`.
+5. Tag `vX.Y.Z` on `main`.
+6. Merge release branch back into `develop`.
+
+## Hotfix Flow
+
+1. Branch `hotfix/*` from `main`.
+2. Apply minimum safe fix and tests.
+3. Merge hotfix into `main`.
+4. Tag patch release (`vX.Y.Z`).
+5. Merge hotfix into `develop`.
+
+## Milestone-Oriented Branching Recommendation
+
+Recommended sequence for planning feature branches:
+
+1. Domain and indexing stability
+2. Search/filter performance
+3. Scouting UX workflows
+4. Provider adapter breadth
+5. Ingestion observability
+6. API hardening
+7. Security and rate-limit tuning
+
+Keep milestones in issues/boards; use branches only for implementation slices.