Repository Guidelines

This provides essential guidance for AI coding agents working on this repository.

🚨 CRITICAL: AI AGENT COMMAND REQUIREMENTS

ALWAYS use uv run prefix for ALL Python-related commands. NEVER use vanilla commands.

CORRECT (Always use these)

✅ uv run python script.py          # NEVER: python script.py
✅ uv run pytest                    # NEVER: pytest
✅ uv run python -m pytest tests/   # NEVER: python -m pytest tests/
✅ uv run python -c "print('test')" # NEVER: python -c "print('test')"
✅ uv run ruff check .              # NEVER: ruff check .
✅ uv run ruff format .             # NEVER: ruff format .
✅ uv run mypy src/                 # NEVER: mypy src/
✅ uv run pip install package      # NEVER: pip install package

FORBIDDEN (Never use these)

❌ python (any form) ❌ pytest (any form) ❌ pip (any form) ❌ ruff (any form) ❌ mypy (any form) ❌ black, isort, flake8, or any other Python tools

Why? All development tools must go through uv run to ensure:

• Proper environment isolation
• Consistent dependency resolution
• No interference with global Python installations
• Reliable tool execution across different systems

This requirement is NON-NEGOTIABLE for AI agents working with this project.

Subagent Guidance

When invoking subagents or providing instructions to other AI agents, ALWAYS explicitly require them to use uv run prefixes for Python commands.

Include this requirement in your prompts:

IMPORTANT: Use `uv run` prefix for ALL Python commands:
- uv run python script.py (NEVER: python script.py)
- uv run pytest (NEVER: pytest)
- uv run ruff check . (NEVER: ruff check .)
- uv run pip install package (NEVER: pip install package)

Verify compliance: Always check that subagent responses use proper uv run prefixes before accepting their output.

Project Structure

gac/
├── src/gac/                    # Main package
│   ├── cli.py                  # CLI entrypoint
│   ├── main.py                 # Commit workflow orchestration
│   ├── ai.py                   # AI provider integration
│   ├── prompt.py               # Prompt building
│   ├── git.py                  # Git operations
│   ├── security.py             # Secret detection
│   ├── providers/              # 24 AI provider implementations
│   └── oauth/                  # OAuth authentication
├── tests/                      # Test suite (mirrors src/)
│   └── providers/              # Provider tests
├── docs/                       # Documentation
├── scripts/                    # Automation helpers
└── assets/                     # Screenshots and assets

Key Points:

• Package lives in src/gac
• Tests mirror source structure
• Each provider has dedicated implementation and test files
• Build artifacts (dist/, htmlcov/) are disposable

Essential Commands

Environment Setup

uv venv && uv pip install -e ".[dev]"

Testing

uv run -- pytest                 # All tests (excludes integration)
uv run -- pytest tests/test_cli.py  # Single file
make test-integration             # Integration tests only (requires API keys)

Code Quality

make lint                         # Check code quality
make format                       # Auto-fix formatting
make clean                        # Remove artifacts

Development Guidelines

Requirements:

• Python 3.10+
• uv (REQUIRED - no exceptions)
• Git
• Node.js (for markdownlint)

CLI Features:

gac -i                            # Interactive mode
gac --add-all                     # Stage all changes
gac --group                       # Group changes into multiple commits
gac --dry-run                     # Preview without committing
gac --message-only                # Output message only

Coding Standards:

• Type annotations required
• Ruff formatter, 120-char lines
• snake_case for modules/functions, CapWords for classes
• Keep files under 600 lines (refactor when exceeded)

Testing Structure

Provider Tests: Each provider has three test types:

1. Unit Tests - No external dependencies
2. Mocked Tests - HTTP calls mocked, inherit from BaseProviderTest
3. Integration Tests - Real API calls (marked @pytest.mark.integration)

Coverage:

make test-cov                     # Generate HTML coverage report
open htmlcov/index.html           # View details

Commit & PR Guidelines

Format: Conventional Commits with optional scopes

feat(ai): implement streaming
fix(providers): handle rate limits
docs: update examples

PR Checklist:

• Version bumped in __version__.py (if releasable)
• CHANGELOG.md updated
• Tests added/updated
• make format, make lint, make type-check, and make test passing
• No files exceed 600-line limit

Use gac for commits: gac -sy

Critical Dependencies

• httpx>=0.28.0 - HTTP client with async support and proper connection pooling
• pydantic>=2.12.0 - Data validation and serialization for provider configs
• click>=8.3.0 - CLI framework with rich formatting integration
• rich>=14.1.0 - Terminal formatting for beautiful CLI output

UV HARD REQUIREMENT:

This project's multi-provider architecture (25+ AI integrations) creates complex dependency trees that only UV can resolve consistently. The dependency lockfile (uv.lock) ensures reproducible builds across all environments - development, testing, CI/CD, and production.

NEVER use vanilla Python tools. They will:

• Break dependency resolution with the provider ecosystem
• Create environment inconsistencies between contributors
• Fail to reproduce the exact dependency versions tested in CI
• Introduce subtle bugs from version mismatches

ALWAYS use UV. It provides:

• Exact dependency locking via uv.lock
• 10-100x faster installation and caching
• Consistent behavior across all environments
• Proper handling of the complex provider dependency matrix