Add comprehensive git workflow with tagging guidelines and DO/DON'T examples

AGENT.MD

@@ -0,0 +1,28 @@
+# Agent Guidelines
+
+This document provides guidelines for AI agents working on this repository.
+
+## Git Workflow
+
+All agents must follow the established git workflow documented in [GIT_WORKFLOW.MD](./GIT_WORKFLOW.MD).
+
+## Key Principles
+
+1. **Never work on the main branch** - All development must occur on feature branches
+2. **Follow the branch structure** as defined in the workflow documentation
+3. **Respect the integration and release processes** outlined in the workflow
+
+## Required Reading
+
+Before making any commits or branches, agents must review:
+- [Git Workflow Documentation](./GIT_WORKFLOW.MD)
+
+## Branch Usage
+
+- Use `LLMBOOTSTRAP` for initial setup and bootstrap tasks
+- Create new feature branches for specific development tasks
+- Ensure all work follows the integration and release pipeline
+
+## Repository Context
+
+This repository uses Gitea (not GitHub) for version control and collaboration.

GIT_WORKFLOW.MD

@@ -0,0 +1,174 @@
+# Git Workflow
+
+This document outlines the git workflow for this repository, designed for use with Gitea.
+
+## Branch Structure
+
+### Main Branches
+
+- **`main`** - The primary stable branch. Direct work should NOT be done on this branch.
+- **`RELEASE`** - Production-ready code. Only accepts pull requests that have been manually reviewed and approved.
+- **`INTEGRATION-WIP`** - Integration branch where all feature branches are automatically merged for testing and integration.
+
+### Feature Branches
+
+- **`LLMBOOTSTRAP`** - Initial bootstrap feature branch for LLM-assisted development setup.
+- Additional feature branches should follow naming conventions like `feature/description` or `task/description`.
+
+## Workflow Rules
+
+1. **Never work directly on `main`** - All work must be done on feature branches.
+
+2. **Feature Development Flow:**
+   - Create feature branches from `main`
+   - Develop features in isolation on these branches
+   - Feature branches automatically merge to `INTEGRATION-WIP` for continuous integration testing
+
+3. **Integration Testing:**
+   - `INTEGRATION-WIP` branch serves as the integration environment
+   - All feature branches are automatically merged here
+   - Used for testing compatibility between different features
+
+4. **Release Process:**
+   - Only manually reviewed pull requests are merged to `RELEASE`
+   - `RELEASE` branch represents production-ready code
+   - Requires explicit approval before merging
+
+## Branch Protection
+
+- `main` - Protected, no direct commits allowed
+- `RELEASE` - Protected, only manual PR merges allowed
+- `INTEGRATION-WIP` - Accepts automatic merges from feature branches
+
+## Feature Branch Management
+
+### **CRITICAL: Branch Preservation**
+- **NEVER automatically delete feature branches** under any circumstances
+- Feature branches must be preserved for historical reference and potential future work
+- Branch deletion should only occur through explicit manual action after careful consideration
+
+### **Commit and Push Frequency**
+- **Commit frequently** - Make small, logical commits as you work
+- **Push every 10 commits maximum** - Don't let local commits accumulate
+- **ALWAYS push before switching branches** - Ensure work is backed up remotely
+- **Push immediately before any branch operations** (merge, rebase, etc.)
+
+### **Tagging for Milestones**
+- **Create tags when interim stages or milestones are completed**
+- **Push tags immediately after creation** to preserve milestone markers
+- **Tag naming conventions:**
+  - Date-based: `milestone-YYYY-MM-DD` or `stage-YYYY-MM-DD-HHMM`
+  - Stage-based: `bootstrap-complete`, `auth-module-done`, `integration-ready`
+  - Plan-based: Use milestone names from planning documents
+- **Always annotate tags** with meaningful descriptions of what was accomplished
+
+## Best Practices
+
+- Keep feature branches focused and small
+- Use descriptive branch names
+- Regularly sync feature branches with `main`
+- Test thoroughly in `INTEGRATION-WIP` before requesting merge to `RELEASE`
+- Write clear commit messages and PR descriptions
+- Follow the commit/push frequency rules above
+
+## Examples: DO and DON'T
+
+### ✅ **DO Examples**
+
+```bash
+# DO: Create feature branch from main
+git checkout main
+git pull origin main
+git checkout -b feature/user-authentication
+
+# DO: Commit frequently with descriptive messages
+git add .
+git commit -m "Add user login form validation"
+git commit -m "Implement password hashing utility"
+git commit -m "Add user session management"
+
+# DO: Push after every 10 commits or before switching branches
+git push origin feature/user-authentication
+
+# DO: Push before switching to another branch
+git push origin feature/user-authentication
+git checkout feature/payment-system
+
+# DO: Sync feature branch with main regularly
+git checkout main
+git pull origin main
+git checkout feature/user-authentication
+git merge main
+
+# DO: Tag milestones with descriptive annotations
+git tag -a bootstrap-complete -m "Initial project structure and workflow setup completed"
+git push origin bootstrap-complete
+
+# DO: Use date-based tags for interim stages
+git tag -a stage-2025-09-05-1430 -m "Authentication module implementation complete"
+git push origin stage-2025-09-05-1430
+```
+
+### ❌ **DON'T Examples**
+
+```bash
+# DON'T: Work directly on main
+git checkout main
+git add .
+git commit -m "Fix user auth bug"  # ❌ NEVER DO THIS
+
+# DON'T: Delete feature branches automatically
+git branch -d feature/user-authentication  # ❌ NEVER DO THIS
+git push origin --delete feature/user-authentication  # ❌ NEVER DO THIS
+
+# DON'T: Let commits accumulate without pushing
+git log --oneline  # Shows 15+ unpushed commits  # ❌ Should have pushed earlier
+
+# DON'T: Switch branches without pushing current work
+git checkout feature/payment-system  # ❌ Without pushing current branch first
+
+# DON'T: Make massive commits
+git add .
+git commit -m "Complete entire user system"  # ❌ Too broad, break it down
+
+# DON'T: Create tags without annotations
+git tag milestone-1  # ❌ No description of what was accomplished
+git push origin milestone-1
+
+# DON'T: Forget to push tags
+git tag -a bootstrap-complete -m "Setup complete"
+# ❌ Missing: git push origin bootstrap-complete
+```
+
+### 🔧 **Workflow Examples**
+
+**Starting new feature:**
+```bash
+git checkout main
+git pull origin main
+git checkout -b feature/shopping-cart
+# Work, commit frequently, push every ~10 commits
+```
+
+**Switching between features:**
+```bash
+# Currently on feature/shopping-cart
+git add .
+git commit -m "Add item quantity validation"
+git push origin feature/shopping-cart  # ✅ Push before switching
+git checkout feature/user-profile
+```
+
+**Preparing for integration:**
+```bash
+git checkout feature/shopping-cart
+git push origin feature/shopping-cart
+# Feature automatically merges to INTEGRATION-WIP
+```
+
+## Gitea Integration
+
+This workflow is optimized for Gitea and utilizes:
+- Branch protection rules
+- Automatic merge capabilities for integration testing
+- Manual review processes for production releases