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:

Unit Tests - No external dependencies
Mocked Tests - HTTP calls mocked, inherit from
```
BaseProviderTest
```
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

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:

Unit Tests - No external dependencies
Mocked Tests - HTTP calls mocked, inherit from
```
BaseProviderTest
```
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

Repository Guidelines

Repository Guidelines

🚨 CRITICAL: AI AGENT COMMAND REQUIREMENTS

CORRECT (Always use these)

FORBIDDEN (Never use these)

Subagent Guidance

Project Structure

Essential Commands

Environment Setup

Testing

Code Quality

Development Guidelines

Testing Structure

Commit & PR Guidelines

Critical Dependencies

Related Skills

Markdown Converter

Nano Banana Pro

1password

Repository Guidelines

🚨 CRITICAL: AI AGENT COMMAND REQUIREMENTS

CORRECT (Always use these)

FORBIDDEN (Never use these)

Subagent Guidance

Project Structure

Essential Commands

Environment Setup

Testing

Code Quality

Development Guidelines

Testing Structure

Commit & PR Guidelines

Critical Dependencies