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:

# 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

# 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

# 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

# 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

# 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)

# 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

# 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

# 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

## 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:

# 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

# 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

# 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

# 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

# Always review what you're committing
git diff
git status
git add -p  # Interactive staging

5. Keep History Clean

# 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

# 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

# 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

# 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

# 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:

# .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