docs: add comprehensive agent documentation

[mldangelo]

Summary

Adds comprehensive documentation for AI agents and developers working on the promptfoo-python repository.

Changes

New Files

• AGENTS.md: Comprehensive documentation covering:

  • Repository overview and architecture
  • Development policies and procedures
  • Release process with release-please
  • CI/CD pipeline details
  • Code standards and quality tools
  • Testing strategy
  • Security practices (OIDC publishing)
  • Common development workflows
  • Troubleshooting and FAQ

• CLAUDE.md: Simple pointer file (@AGENTS.md) for Claude Code context loading

Why This Matters

This documentation provides a single source of truth for:

1. AI Agents: Clear guidance on development policies (always use PRs, conventional commits, etc.)
2. Human Developers: Comprehensive reference for contributing to the project
3. Maintainers: Documented processes for releases, CI/CD, and security

Key Policies Documented

• ✅ Always create PRs, never commit to main
• ✅ Use conventional commits for all changes
• ✅ Follow semantic versioning (pre-1.0.0 rules)
• ✅ Automated releases via release-please
• ✅ Secure PyPI publishing via OIDC
• ✅ Multi-platform testing requirements

Benefits

• Ensures consistent development practices
• Reduces onboarding time for new contributors
• Documents tribal knowledge about the project
• Provides troubleshooting guidance
• Clarifies the automated release process

Review Notes

This is pure documentation - no code changes. Please review for:

• Accuracy of documented processes
• Completeness of coverage
• Clarity for both AI and human readers

🤖 Generated with Claude Code