Skip to content

GIT_WORKFLOW.md

Latest commit

 

History

History
425 lines (298 loc) · 11.1 KB

GIT_WORKFLOW.md

File metadata and controls

425 lines (298 loc) · 11.1 KB

Git Workflow Guide

📋 Document Summary

What This Document Covers:

  • Mandatory /commit command usage via commit-manager agent
  • Prohibited git operations (direct git commit via Bash/Task tools)
  • Conventional commit format with logical grouping
  • Three commit modes: session changes, all pending, scoped commits
  • Branch strategy and collaboration workflow
  • Common git operations and troubleshooting

Sections in This Document:

Related Documentation:

Context Tags: #git #workflow #commits #version-control #commit-manager

Critical Requirements

⚠️ MANDATORY: Use /commit Command Only

ALL git commits in this project MUST use the /commit command (commit-manager agent).

Zero exceptions. Zero tolerance. No excuses.

❌ FORBIDDEN Operations

The following operations are ABSOLUTELY PROHIBITED:

Forbidden: All direct git commit commands (including -m, --amend, -a, etc.), Task tool with generic agent for git operations, manual git add + git commit workflows.

✅ REQUIRED Operations

Command Use Case
/commit Session changes (default)
/commit --all All pending changes
/commit <scope> Scoped commits (e.g., web ui, database, documentation)

Commit Manager Agent

What is the Commit Manager Agent?

The commit-manager is a specialized agent that:

  • Analyzes git status to understand changes
  • Groups related changes into logical commits
  • Follows conventional commit standards
  • Filters scopes intelligently
  • Provides session-aware commit creation
  • Uses ZERO Opus tokens (100% token savings)

Why Use the Commit Manager?

Benefits:

  1. Logical Grouping - Related changes automatically grouped
  2. Conventional Format - Consistent commit message style
  3. Token Efficiency - No Opus tokens consumed
  4. Quality Control - Validates changes before committing
  5. Session Awareness - Tracks what changed in current session

Commit Modes

1. /commit (Session Changes - Default)

Use Case: Commit changes made in current session

# Commit all changes from current working session
/commit

What It Does:

  • Analyzes changes made during current session
  • Groups related changes logically
  • Creates one or more commits based on logical boundaries
  • Recommended for most use cases

2. /commit --all (All Pending Changes)

Use Case: Commit all pending changes, including untracked files

# Commit everything that's modified or new
/commit --all

What It Does:

  • Includes all modified files
  • Includes all untracked files
  • Groups into logical commits
  • Use sparingly (prefer session-based commits)

When to Use:

  • After major refactoring across multiple components
  • When catching up after extended offline work
  • When multiple unrelated changes accumulated

3. /commit <scope> (Scoped Commits)

Use Case: Commit only changes related to specific scope

# Commit only web UI changes
/commit web ui

# Commit only database changes
/commit database

# Commit only documentation changes
/commit documentation

# Commit only workflow changes
/commit workflows

What It Does:

  • Filters files by scope keyword
  • Commits only matching files
  • Useful for focused, incremental commits

Common Scopes:

  • web ui - Web UI and API changes
  • database - Vector DB, Firebase changes
  • workflows - Workflow documentation/implementation
  • documentation - Docs-only changes
  • tests - Test files only
  • orchestrators - Orchestrator changes

Conventional Commit Format

Commit Message Structure

The commit-manager agent automatically formats commits using the Conventional Commits standard:

<type>(<scope>): <description>

[optional body]

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

Commit Types

Type Use Case Example
feat New feature feat(web-ui): add memecoin edit proposal endpoint
fix Bug fix fix(firebase): resolve wallet status update race condition
docs Documentation only docs(workflows): add Document Summary to 8 READMEs
refactor Code refactoring refactor(processor): simplify stage execution logic
test Adding/updating tests test(firebase): add integration tests for trend storage
chore Maintenance tasks chore(deps): update pydantic to v2.5
perf Performance improvement perf(rag): optimize vector search query
style Code style changes style(all): run PyCharm reformat on codebase

Scope Examples

Scope Files Affected
web-ui src/web_ui/**/*
workflows src/workflows/**/*
database src/services/*firebase*, src/ai_generation/rag_memecoin/vector_store.py
orchestrators src/orchestrators/**/*
domain src/domain/**/*
tests tests/**/*
docs docs/**/*, *.md

Branch Strategy

Main Branch

  • Branch: main
  • Protection: Direct commits allowed (small team)
  • Quality: All commits must pass pre-commit hooks

Feature and Hotfix Branches

Feature branches: For larger features, create with git checkout -b feature/<name>, commit with /commit, then merge with git merge feature/<name>.

Hotfix branches: For urgent fixes, create with git checkout -b hotfix/<name>, commit with /commit, then merge to main.

Common Operations

Before Committing

ALWAYS run PyCharm formatting before committing:

1. Code → Reformat Code (Ctrl+Alt+L / Cmd+Option+L)
2. Code → Optimize Imports (Ctrl+Alt+O / Cmd+Option+O)

Undo Changes: Use git reset --soft HEAD~1 to undo your last commit while keeping changes (then use /commit again). Use git reset --hard HEAD only if you need to discard all local changes.

Push: After committing with /commit, push with git push origin main. Avoid git push --force unless absolutely necessary.

Troubleshooting

"I accidentally used git commit"

Solution:

# Undo the commit (keep changes)
git reset --soft HEAD~1

# Now use /commit instead
/commit

"Pre-commit hook failed"

Common Causes:

  1. Formatting issues - Run PyCharm "Reformat Code"
  2. Import issues - Run PyCharm "Optimize Imports"
  3. Linting errors - Fix errors shown in hook output

Solution:

# Fix the issues
# Re-run /commit (commit-manager will amend if safe)
/commit

"Merge conflict"

Solution:

# 1. Pull latest changes
git pull origin main

# 2. Resolve conflicts in files
# (Edit files, remove conflict markers)

# 3. Stage resolved files
git add <resolved-files>

# 4. Complete merge
git commit  # Auto-generated merge commit message

# 5. Push
git push origin main

"I need to amend my last commit"

⚠️ WARNING: Only amend commits that haven't been pushed!

# Make additional changes
# ... edit files ...

# Stage changes
git add <files>

# Amend last commit
git commit --amend --no-edit

# Or update commit message
git commit --amend

NOTE: The commit-manager agent handles amendments automatically when pre-commit hooks modify files.

Examples

Example 1: Simple Feature Addition

# 1. Make changes to web UI
# ... edit src/web_ui/api/memecoin_routes.py ...

# 2. Format code
# Code → Reformat Code
# Code → Optimize Imports

# 3. Check status
git status
# Modified: src/web_ui/api/memecoin_routes.py

# 4. Commit using commit-manager
/commit

# Output:
# ✓ Created commit: feat(web-ui): add batch approve endpoint for memecoins
#   🤖 Generated with Claude Code
#   Co-Authored-By: Claude <noreply@anthropic.com>

# 5. Push
git push origin main

Example 2: Documentation Update

# 1. Update multiple README files
# ... edit docs/workflows/*.md ...

# 2. Commit documentation changes
/commit documentation

# Output:
# ✓ Created commit: docs(workflows): add Document Summary sections to 8 workflow READMEs
#   Updated:
#     - src/workflows/WORKFLOWS.md
#     - src/workflows/live_launch_detection_workflow/README.md
#     - src/workflows/csv_launch_detection_workflow/README.md
#     ... (5 more files)

# 3. Push
git push origin main

Example 3: Multi-Component Feature

# 1. Make changes across multiple components
# ... edit src/workflows/trend_detection_workflow.py ...
# ... edit src/domain/processor/stages/trend_classification_stage.py ...
# ... edit tests/unit/domain/processor/stages/test_trend_classification_stage.py ...

# 2. Format all changed files
# Code → Reformat Code (select all)

# 3. Commit all session changes
/commit

# Output:
# ✓ Created 3 commits:
#   1. feat(workflows): enhance trend classification with multimodal analysis
#   2. feat(domain): add entity-to-image mapping in trend classification stage
#   3. test(domain): add tests for multimodal trend classification

# 4. Push
git push origin main

Example 4: Scoped Commit for Tests Only

# 1. Add tests for new feature
# ... create tests/unit/services/test_wallet_validation.py ...

# 2. Commit only test files
/commit tests

# Output:
# ✓ Created commit: test(services): add comprehensive wallet validation tests
#   Added: tests/unit/services/test_wallet_validation.py

# 3. Push
git push origin main

Best Practices

✅ DO

  1. Use /commit for all commits - No exceptions
  2. Format code before committing - PyCharm "Reformat Code"
  3. Commit frequently - Small, logical commits
  4. Write descriptive commit messages - Let commit-manager handle it
  5. Review git status before committing - Know what you're committing
  6. Pull before push - Stay in sync with remote

❌ DON'T

  1. Don't use git commit directly - Use /commit instead
  2. Don't commit without formatting - Always format first
  3. Don't commit commented-out code - Delete it
  4. Don't commit secrets - Use .env files
  5. Don't force push to main - Unless absolutely necessary
  6. Don't commit large binary files - Use Git LFS if needed

Pre-Commit Hooks

What Happens on Commit

When using /commit, the commit-manager agent:

  1. Checks authorship - Ensures you own the commit
  2. Validates not pushed - Prevents amending pushed commits
  3. Runs pre-commit hooks - Formatting, linting, tests
  4. Handles hook changes - Amends if hooks modify files
  5. Creates commits - With conventional format

If pre-commit hooks modify files (e.g., formatting), the commit-manager automatically amends. If hooks fail with errors, fix them and re-run /commit.

Last Updated: January 2025 - LaunchAgencyBot v2.0