Git Workflow

Git Workflow Standards

When to Use

• When creating commits
• When deciding whether to create a branch
• Before declaring work complete
• When preparing changes for pull requests

Branch Protection

1. Never commit directly to main - create a feature branch first
2. Always pull from main before branching - run git fetch origin && git rebase origin/main (or git pull origin main) before creating a feature branch or starting work. This prevents merge conflicts in the PR.
3. Branch naming: Use kebab-case that describes the change (e.g., add-user-authentication, fix-memory-leak)
4. Stay on feature branches - don't create feature branches off feature branches

Success Criteria

Changes are considered successful when ALL of the following are met:

1. Requirements satisfied - original task goals are achieved
2. Build passes - code compiles without errors
3. Tests pass - all existing and new tests succeed
4. No linting errors - code follows project style guidelines
5. Files formatted - code is properly formatted
6. Complete changes - no partial or incomplete modifications
7. Dependencies included - all necessary imports and packages added
8. Documentation updated - relevant docs reflect the changes

Language-Specific Checks

Commit Message Format

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

<detailed description>

Cursor-Task: <original task description>

Types

Guidelines

• Brief description: Max 72 characters, imperative mood ("add" not "added")
• Scope: Optional, indicates area affected (e.g., auth, api, ui)
• Detailed description: 1-2 sentences explaining the why
• Cursor-Task: Reference the original task that prompted the change

Examples

Good Commit

git commit -m "feat(auth): implement OAuth2 user authentication

Add Google OAuth2 authentication flow with JWT token handling.
Update user model to support OAuth providers.

Cursor-Task: Add OAuth2 authentication for user login"

Good Infrastructure Commit

git commit -m "infra(aws): update ECS task definitions

Increase memory allocation and add CloudWatch logging.

Cursor-Task: Optimize ECS resource allocation"

Bad Commits

• git commit -m "fixed stuff" - Missing type, not descriptive
• git commit -m "wip" - Never commit work-in-progress
• Committing with failing tests - Always verify success criteria first

Tools

• Prefer git command line for operations
• Use GitHub MCP for creating pull requests when available
• If MCP isn't working, prompt the user for next steps

Pre-Commit Checklist

Before every commit, verify:

• Pulled from main first — git fetch origin && git rebase origin/main before branching
• Build compiles successfully
• All tests pass
• No linting errors
• Changes match the original task
• No secrets or credentials in the commit
• Documentation updated if needed

Source: queen-of-code/AI-DLC — distributed by TomeVault.