CODEX_ADK/GIT-WORKFLOW.md

# CODEX_ADK Git Workflow

## Monorepo Structure

This is a **monorepo** containing two independent components:

```
CODEX_ADK/                  (Root - Combined Project)
├── BACKEND/                (ASP.NET Core 8.0 CQRS API)
├── FRONTEND/               (Flutter 3.x Console App)
├── .gitignore              (Root-level exclusions)
└── GIT-WORKFLOW.md         (This file)
```

## Repository Strategy

**Single Git Repository** at the root level that:
- Tracks both BACKEND and FRONTEND in one repo
- Allows independent commits for each component
- Maintains clear separation via commit prefixes
- Enables coordinated releases when needed

## Commit Conventions

### Component-Specific Commits

Use **scope prefixes** to indicate which component changed:

```bash
# Backend-only changes
git commit -m "backend: feat: Add user authentication endpoint"
git commit -m "backend: fix: Resolve null reference in AgentService"
git commit -m "backend: refactor: Optimize database queries"

# Frontend-only changes
git commit -m "frontend: feat: Add Agents list UI"
git commit -m "frontend: fix: API client timeout handling"
git commit -m "frontend: style: Update theme colors"

# Root/Infrastructure changes
git commit -m "chore: Update Docker Compose configuration"
git commit -m "docs: Add API integration guide"
git commit -m "ci: Add GitHub Actions workflow"

# Changes affecting both (rare)
git commit -m "feat: Add conversation feature (backend + frontend)"
```

### Commit Message Format

```
<scope>: <type>: <subject>

<optional body>

<optional footer>
```

**Scopes:**
- `backend` - ASP.NET Core API changes
- `frontend` - Flutter app changes
- `chore` - Build, config, dependencies
- `docs` - Documentation updates
- `ci` - CI/CD pipelines
- `test` - Test suite changes

**Types:**
- `feat` - New feature
- `fix` - Bug fix
- `refactor` - Code restructuring
- `perf` - Performance improvement
- `style` - Code style/formatting
- `test` - Add/update tests
- `docs` - Documentation only

### Examples

```bash
# Good - Clear component and intent
git commit -m "backend: feat: Implement agent execution tracking"
git commit -m "frontend: fix: Resolve dialog validation issues"
git commit -m "docs: Add OpenAPI integration workflow"

# Bad - Unclear what changed
git commit -m "update code"
git commit -m "fixes"
git commit -m "WIP"
```

## Workflow Examples

### 1. Backend-Only Changes

```bash
# Make changes to BACKEND files
cd BACKEND
# ... edit files ...

# Stage and commit (from root)
cd ..
git add BACKEND/
git commit -m "backend: feat: Add rate limiting middleware"
git push
```

### 2. Frontend-Only Changes

```bash
# Make changes to FRONTEND files
cd FRONTEND
# ... edit files ...

# Stage and commit (from root)
cd ..
git add FRONTEND/
git commit -m "frontend: feat: Add dark mode toggle"
git push
```

### 3. Independent Changes in Same Session

```bash
# Work on both components separately
git add BACKEND/Codex.Api/Controllers/AgentsController.cs
git commit -m "backend: fix: Validate agent name length"

git add FRONTEND/lib/screens/agents_screen.dart
git commit -m "frontend: feat: Add agent search filter"

git push
```

### 4. Coordinated Feature (Both Components)

```bash
# When a feature spans both backend and frontend
git add BACKEND/ FRONTEND/
git commit -m "feat: Add real-time conversation streaming

BACKEND: Added SignalR hub and streaming endpoints
FRONTEND: Added WebSocket client and message UI

Closes #123"

git push
```

### 5. Infrastructure Changes

```bash
# Docker, CI/CD, root config
git add docker-compose.yml .github/
git commit -m "chore: Add PostgreSQL health checks to Docker"
git push
```

## Branch Strategy

### Main Branch
- `master` - Production-ready code
- Always deployable
- Protected (requires PR for merges)

### Feature Branches

```bash
# Backend feature
git checkout -b backend/user-authentication
# ... work ...
git commit -m "backend: feat: Add JWT authentication"
git push origin backend/user-authentication

# Frontend feature
git checkout -b frontend/agents-ui
# ... work ...
git commit -m "frontend: feat: Add agents management screen"
git push origin frontend/agents-ui

# Cross-cutting feature
git checkout -b feature/real-time-chat
# ... work on both ...
git commit -m "feat: Add real-time chat (backend + frontend)"
git push origin feature/real-time-chat
```

### Branch Naming
- `backend/*` - Backend features/fixes
- `frontend/*` - Frontend features/fixes
- `feature/*` - Cross-cutting features
- `fix/*` - Bug fixes
- `hotfix/*` - Urgent production fixes

## Pull Request Guidelines

### PR Titles
Use same convention as commits:

```
backend: feat: Add user authentication
frontend: fix: Resolve dialog validation
feat: Add conversation streaming (backend + frontend)
```

### PR Description Template

```markdown
## Component
- [ ] Backend
- [ ] Frontend
- [ ] Both
- [ ] Infrastructure

## Type
- [ ] Feature
- [ ] Bug Fix
- [ ] Refactor
- [ ] Documentation

## Summary
Brief description of changes

## Changes
- Change 1
- Change 2
- Change 3

## Testing
- [ ] Unit tests pass
- [ ] Integration tests pass
- [ ] Manual testing completed

## Related Issues
Closes #123
```

## Release Strategy

### Versioning
Each component can have independent versions:

```bash
# Tag backend release
git tag backend/v1.2.0
git push origin backend/v1.2.0

# Tag frontend release
git tag frontend/v1.3.0
git push origin frontend/v1.3.0

# Tag coordinated release
git tag v1.0.0
git push origin v1.0.0
```

### Changelog
Maintain separate changelogs:
- `BACKEND/CHANGELOG.md` - Backend changes
- `FRONTEND/CHANGELOG.md` - Frontend changes
- `CHANGELOG.md` - Coordinated releases

## Best Practices

### 1. Keep Commits Focused
```bash
# Good - Single concern
git commit -m "backend: fix: Resolve null reference in AgentService"

# Bad - Multiple concerns
git commit -m "backend: fix bugs and add features and update docs"
```

### 2. Commit Frequently
```bash
# Commit logical units of work
git commit -m "backend: feat: Add Agent entity"
git commit -m "backend: feat: Add CreateAgentCommand"
git commit -m "backend: feat: Add AgentController endpoint"
```

### 3. Write Meaningful Messages
```bash
# Good
git commit -m "frontend: fix: Prevent double-submit on agent creation

Added disabled state to submit button while request is in flight.
This prevents users from accidentally creating duplicate agents.

Fixes #234"

# Bad
git commit -m "fix stuff"
```

### 4. Review Before Committing
```bash
# Always review what you're committing
git diff
git status
git add -p  # Interactive staging
```

### 5. Keep History Clean
```bash
# Amend last commit if you forgot something (ONLY if not pushed)
git add forgot-this-file.cs
git commit --amend --no-edit

# Squash work-in-progress commits before merging
git rebase -i HEAD~3
```

## Troubleshooting

### Accidentally Committed to Wrong Scope

```bash
# If not pushed yet
git reset --soft HEAD~1  # Undo commit, keep changes
git add BACKEND/        # Stage correct files
git commit -m "backend: fix: Correct scope"

# If already pushed
# Create new commit with correct scope, reference old one in message
```

### Mixed Changes in Working Directory

```bash
# Stage backend changes separately
git add BACKEND/
git commit -m "backend: feat: Add authentication"

# Then stage frontend changes
git add FRONTEND/
git commit -m "frontend: feat: Add login screen"
```

### Checking Component History

```bash
# See all backend commits
git log --oneline --grep="^backend:"

# See all frontend commits
git log --oneline --grep="^frontend:"

# See changes to specific component
git log --oneline -- BACKEND/
git log --oneline -- FRONTEND/
```

## Quick Reference

```bash
# Check status
git status

# Stage component changes
git add BACKEND/
git add FRONTEND/

# Commit with scope
git commit -m "backend: feat: description"
git commit -m "frontend: fix: description"

# View component history
git log --oneline -- BACKEND/
git log --oneline -- FRONTEND/

# Create feature branch
git checkout -b backend/feature-name
git checkout -b frontend/feature-name

# Push changes
git push origin branch-name

# Tag release
git tag backend/v1.0.0
git tag frontend/v1.0.0
git push --tags
```

## CI/CD Integration

When setting up CI/CD, use path filters:

```yaml
# .github/workflows/backend.yml
on:
  push:
    paths:
      - 'BACKEND/**'

# .github/workflows/frontend.yml
on:
  push:
    paths:
      - 'FRONTEND/**'
```

This ensures backend changes only trigger backend builds, and vice versa.

---

**Remember:** This monorepo structure allows you to:
- Commit backend and frontend changes independently
- Maintain clear separation via commit scopes
- Track related changes together
- Coordinate releases when needed
- Keep a unified project history