Skip to content

AGENTS.md

Latest commit

 

History

History
281 lines (203 loc) · 9.04 KB

AGENTS.md

File metadata and controls

281 lines (203 loc) · 9.04 KB

rh-ai-hooks Project Context

This file provides context for AI coding assistants and developers working on the rh-ai-hooks project.

Project Overview

Name: rh-ai-hooks Purpose: Pre-commit hooks to help Red Hat teams adopt AI coding assistants responsibly Repository: https://github.com/openshift-hyperfleet/rh-hooks-ai Language: Python 3 (hooks), Bash (bootstrap scripts) Framework: pre-commit.com hook system

Goal: Make it easy for Red Hat development teams to:

  1. Enforce baseline security compliance (rh-pre-commit)
  2. Maintain quality AI context files (AGENTS.md)
  3. Encourage AI attribution transparency
  4. Stay up-to-date with hook improvements

Architecture

Directory Structure

rh-ai-hooks/
├── hooks/                         # Hook implementations (Python scripts)
│   ├── check_rh_precommit.py     # Enforces rh-pre-commit installation
│   ├── validate_agents_md.py     # Validates AGENTS.md quality
│   ├── ai_attribution_reminder.py # One-time AI attribution tip
│   └── check_version.py          # Optional version update checker
├── configs/
│   └── baseline.yaml             # Example .pre-commit-config.yaml for users
├── templates/
│   ├── AGENTS.md.template        # Template for user repos
│   └── gitmessage.txt            # Git commit message template
├── bootstrap/
│   └── quick-setup.sh            # One-command setup script
├── .github/workflows/
│   └── release-please.yml        # Automated release workflow
├── .pre-commit-hooks.yaml        # Hook registry for pre-commit
├── .pre-commit-config.yaml       # Hooks used BY this repo (dogfooding)
└── CHANGELOG.md                  # Auto-generated by release-please

Hook Architecture

All hooks use language: script in .pre-commit-hooks.yaml:

  • Scripts run directly (no Python package installation needed)
  • All scripts have shebang: #!/usr/bin/env python3
  • Cross-platform compatible (Linux, macOS, Windows)

Release System

Automated via GitHub Actions:

  1. Conventional commits determine version bumps
  2. release-please creates release PRs with CHANGELOG
  3. When merged, GitHub release is tagged
  4. baseline.yaml auto-updates with new version tag

Coding Guidelines

Python Style

  • Formatter: black (enforced by pre-commit)
  • Line length: 88 characters (black default)
  • Python version: 3.7+ (for compatibility)
  • Imports: Standard library only (no external dependencies)
  • Error handling: Fail gracefully with helpful messages

Bash Style

  • Linter: shellcheck (enforced by pre-commit)
  • Shebang: #!/usr/bin/env bash
  • Error handling: set -e for critical operations
  • User feedback: Colored output with clear status messages

Commit Messages

MUST follow Conventional Commits format (enforced by pre-commit):

<type>[optional scope]: <description>

[optional body]

[optional footer]

Valid types:

  • feat: - New feature (minor version bump: v0.1.0 → v0.2.0)
  • fix: - Bug fix (patch version bump: v0.1.0 → v0.1.1)
  • docs: - Documentation only
  • chore: - Maintenance (no version bump)
  • refactor: - Code refactoring
  • test: - Test changes
  • ci: - CI/CD changes
  • feat!: or BREAKING CHANGE: - Major version bump (v0.1.0 → v1.0.0)

Hook Design Principles

  1. Helpful, not annoying: Non-blocking where possible, clear error messages
  2. Fast: Cache results, avoid slow network calls
  3. Fail gracefully: Network errors, missing files → don't crash
  4. Cross-platform: Use Python stdlib, avoid platform-specific commands
  5. Self-contained: No external dependencies, single-file scripts

Key Implementation Details

check_rh_precommit.py

  • Blocking: Yes (if rh-pre-commit not configured)
  • Warning only: If not installed globally
  • Checks: .pre-commit-config.yaml must reference rh-pre-commit repo
  • Output: Helpful error with exact fix commands

validate_agents_md.py

  • Blocking: Yes (if hook is enabled and file issues found)
  • Stage: Runs on git push (not every commit - less annoying)
  • Requirements: AGENTS.md must exist, not empty, >100 chars
  • Note: Teams must explicitly add this hook (opt-in enforcement)

ai_attribution_reminder.py

  • Blocking: No (always passes)
  • Frequency: One-time per repository
  • Marker: Creates .git/.ai-tip-shown
  • Message: Suggests Assisted-by: / Generated-by: trailers

check_version.py

  • Blocking: No (always passes)
  • Frequency: Once per 24 hours (cached)
  • Network: Fails silently if offline/timeout
  • Detection: Reads version from user's .pre-commit-config.yaml
  • Comparison: String comparison works for semantic versioning

quick-setup.sh

  • Fetch method: Always downloads from GitHub (not local files)
  • Reason: Users run in their own repos, not rh-ai-hooks clone
  • Downloads: baseline.yaml, gitmessage.txt, AGENTS.md.template
  • Configuration: Local git config only (not global)

Testing

Manual Testing

# Test individual hook
python3 hooks/check_rh_precommit.py

# Test all hooks
pre-commit run --all-files

# Test in clean repo
cd /tmp && mkdir test-repo && cd test-repo && git init
# Run hooks here

Pre-commit Hooks on This Repo

We dogfood our own hooks plus:

  • Conventional commit enforcement
  • Python formatting (black)
  • Shell linting (shellcheck)
  • Standard pre-commit hooks (trailing whitespace, YAML validation, etc.)

Testing Release Process

DO NOT manually create tags/releases. Let release-please handle it:

  1. Make conventional commits
  2. Push to main
  3. release-please creates PR
  4. Review and merge PR
  5. Release auto-created

Common Tasks

Adding a New Hook

  1. Create hooks/new_hook.py with shebang
  2. Make executable: chmod +x hooks/new_hook.py
  3. Add entry to .pre-commit-hooks.yaml
  4. Update configs/baseline.yaml (commented if optional)
  5. Document in README.md
  6. Test locally
  7. Commit with feat: add new hook description

Updating Documentation

  • Use docs: commit type (no version bump)
  • Update README.md, this AGENTS.md, or inline docstrings
  • Run pre-commit run --all-files to check formatting

Fixing Bugs

  • Use fix: commit type (patch version bump)
  • Add test case if possible
  • Ensure fix is cross-platform

Making Breaking Changes

  • Use feat!: or add BREAKING CHANGE: in commit footer
  • This triggers major version bump
  • Document migration path in commit body

Important Constraints

Security

  • Never commit secrets (enforced by rh-pre-commit in our config)
  • Validate inputs: User-provided file paths, config content
  • Fail safely: Don't expose sensitive info in error messages

Dependencies

  • Python: Standard library ONLY
    • pathlib, re, json, urllib, subprocess, sys
    • NO pip packages (no setup.py, no pyproject.toml)
  • Bash: Use curl for downloads (universally available)

GitHub API

  • Rate limits: check_version.py caches for 24h to avoid limits
  • Timeout: 2 second timeout on network calls
  • Authentication: Uses RELEASE_PLEASE_TOKEN secret for releases

Pre-commit Language

  • MUST use language: script not language: python
  • Why: Avoids package installation, runs scripts directly
  • Alternative would require setup.py/pyproject.toml

Resources

External Standards

Red Hat Internal

Project Links

Notes for AI Assistants

When Writing Code

  • Keep it simple: Single-file scripts, no complex abstractions
  • Helpful errors: Users should know exactly how to fix issues
  • Cross-platform: Test patterns work on Linux, macOS, Windows
  • No magic: Avoid clever tricks, prefer readable code

When Fixing Bugs

  • Check if it affects all platforms (Windows path handling, etc.)
  • Ensure error messages are actionable
  • Don't break backward compatibility without BREAKING CHANGE:

When Adding Features

  • Consider: Does this make commits slower? (Cache it!)
  • Consider: Will this annoy developers? (Make it non-blocking!)
  • Consider: Is this cross-platform? (Test on Windows!)
  • Remember: Start minimal, iterate based on feedback

Project Philosophy

"Helpful, not annoying"

  • Enforce security (blocking): rh-pre-commit must be configured
  • Validate quality (blocking if opted-in): AGENTS.md must be useful
  • Encourage practices (non-blocking): Attribution reminders, version checks