# AI Agent Workflow Reference

**PRIMARY REFERENCE FOR: Gemini-CLI, Claude, OpenCode, and all AI tools**

## 🚨 CRITICAL RULES

1. **NEVER work on `main` branch** - Always use feature branches
2. **NEVER auto-delete feature branches** - Preserve all branches permanently
3. **ALWAYS push before switching branches** - Never lose work
4. **Push every 10 commits max** - Keep work backed up
5. **Tag milestones** - Mark completed stages/milestones
6. **UPDATE WORKLOGS** - Maintain WORKLOG.md and CURRENTWORK.md

## 📋 Quick Commands

**Start new feature:**
```bash
git checkout main && git pull origin main
git checkout -b feature/your-feature-name
```

**Before switching branches:**
```bash
git add . && git commit -m "Your message"
git push origin current-branch-name
```

**Tag a milestone:**
```bash
git tag -a milestone-name -m "Description of what was completed"
git push origin milestone-name
```

## 🌳 Branch Structure

- **`main`** - Stable, protected, no direct work
- **`LLMBOOTSTRAP`** - Initial setup/bootstrap work
- **`INTEGRATION-WIP`** - Auto-merge target for testing
- **`RELEASE`** - Manual PR target for production
- **`feature/*`** - All development work happens here

## ⚡ Workflow Pattern

1. Create feature branch from `main`
2. Work with frequent commits (small, logical)
3. Push every ~10 commits or before branch switching
4. Feature auto-merges to `INTEGRATION-WIP` for testing
5. Manual PR to `RELEASE` when ready for production
6. **NEVER delete branches** - Keep for history

## 🏷️ Tagging Guidelines

**When to tag:**
- Milestone completed
- Stage finished
- Major feature done

**Tag formats:**
- `bootstrap-complete` (stage names)
- `milestone-2025-09-05` (date-based)
- `auth-module-done` (feature-based)

**Always use:** `git tag -a tagname -m "description"`

## 🛠️ Repository Context

- **Platform:** Gitea (not GitHub)
- **Workflow:** Feature branches → Integration → Release
- **Philosophy:** Preserve history, frequent commits, milestone tracking

## 📝 Work Tracking

**ALWAYS maintain work logs:**
- **[WORKLOG.md](./WORKLOG.md)** - Medium fidelity: status, progress, next actions
- **[CURRENTWORK.md](./CURRENTWORK.md)** - High fidelity: detailed notes, concerns, questions
- **LLM Versions:** [AGENT-LLM.MD](./AGENT-LLM.MD), [WORKLOG-LLM.md](./WORKLOG-LLM.md), [CURRENTWORK-LLM.md](./CURRENTWORK-LLM.md)

**Update pattern:**
1. Start session → Update current status in WORKLOG.md
2. During work → Add detailed notes to CURRENTWORK.md  
3. End session → Update completion status and next actions

## 📚 Detailed Reference

Full documentation: [GIT_WORKFLOW.MD](./GIT_WORKFLOW.MD)