docs: add repo-local AGENTS.md with deterministic validation workflow guidance

[devin-ai-integration]

docs: add repo-local AGENTS.md with deterministic validation workflow guidance

Summary

Closes #4564.

Adds a repo-local AGENTS.md at the repository root to give AI coding assistants and contributors deterministic, machine-readable guidance for validating changes before opening PRs. This is distinct from the existing lib/crewai/src/crewai/cli/templates/AGENTS.md template (which is scaffolded into end-user projects via crewai create).

The file documents:

• Repository layout — workspace structure, package locations, config files
• Environment setup — uv sync commands, Python version requirement
• Deterministic validation workflow — ordered steps: ruff lint → ruff format → mypy → pytest → pre-commit
• CI workflows — maps to the actual GitHub Actions (linter.yml, tests.yml, type-checker.yml)
• Safety boundaries — secrets, VCR cassettes, network blocking, test integrity, dependency management
• Commit convention — Conventional Commits via Commitizen
• Testing & code style conventions — async markers, VCR usage, import rules, type annotation style

Also adds 22 parametrized regression tests (lib/crewai/tests/test_agents_md.py) that validate the file exists and contains all required sections, validation commands, safety rules, and workspace member references.

Review & Testing Checklist for Human

• Verify AGENTS.md accuracy: Cross-check the documented commands (ruff, mypy, pytest invocations) against the actual CI workflow files (.github/workflows/linter.yml, tests.yml, type-checker.yml) and pyproject.toml to confirm nothing is stale or misleading
• Test path assumption: test_agents_md.py uses Path(__file__).resolve().parents[3] to locate the repo root — confirm this resolves correctly in CI where test working directory may differ
• Test string-matching fragility: The tests assert exact substrings (e.g., "Never commit secrets", "Deterministic Validation Workflow"). Decide if this level of coupling is acceptable for catching future drift vs. being too brittle for section rewrites
• Scope check: Verify this file shouldn't also cover additional topics (e.g., how to re-record VCR cassettes end-to-end, branch naming conventions, PR review process) that the team considers important for automation agents

Notes

• All 22 tests pass locally on Python 3.13.
• The ruff linter expectedly produces syntax errors when pointed at AGENTS.md (it's Markdown, not Python) — CI only lints changed .py files so this won't affect the lint workflow.
• Link to Devin run: https://app.devin.ai/sessions/205ec048a55141c384f65afd6cabbf16
• Requested by: João

[devin-ai-integration]

Prompt hidden (unlisted session)

[devin-ai-integration]

🤖 Devin AI Engineer

I'll be helping with this pull request! Here's what you should know:

✅ I will automatically:

• Address comments on this PR. Add '(aside)' to your comment to have me ignore it.
• Look at CI failures and help fix them

Note: I can only respond to comments from users who have write access to this repository.

⚙️ Control Options:

• Disable automatic comment and CI monitoring

[devin-ai-integration]

Closing due to inactivity for more than 7 days. Configure here.