Issue Station
Sign In
Tools hereToolbox

crewai - ✅(Solved) Fix Add repo-local AGENTS.md with deterministic validation workflow guidance [2 pull requests, 2 comments, 2 participants]

Official PRs (…)
ON THIS PAGE

Recommended Tools

×6

Utilities matched from this issue’s tags and category — try them while you read without losing context.

GitHub issue graph ai analysis

Paste a GitHub issue URL. We fetch that issue, discover linked issues from bodies/comments/timeline, collect linked pull requests, and produce a structured English report.

The report is written in English Markdown for sharing and archival.

Helpful · Quick feedback

Loading…
GitHub stats
crewAIInc/crewAI#4564•Fetched 2026-04-08 00:41:15
View on GitHub
Comments
2
Participants
2
Timeline
8
Reactions
0
Author
davidahmanndavidahmann
Participants
davidahmanndavidahmanngithub-actions[bot]github-actions[bot]
Timeline (top)
commented ×2cross-referenced ×2referenced ×2closed ×1

Root Cause

Current behavior is insufficient because there is no repo-local AGENTS.md to codify deterministic validation, safety boundaries, and contribution workflow expectations.

Fix Action

Fixed

PR fix notes

PR #4565: docs: add repo-local AGENTS.md contributor guidance

Description (problem / solution / changelog)

Problem

This repo lacked a repo-local AGENTS instruction file, causing inconsistent machine-guided validation behavior.

Why now

This is active operator friction in current workflows and needs deterministic behavior for repeatable triage/replay.

What changed

Added root AGENTS.md with deterministic setup/validation commands and safety/PR hygiene guardrails aligned to current repo workflows.

Validation

  • test -f AGENTS.md (pass)

Refs #4564

<!-- CURSOR_SUMMARY -->

[!NOTE] Low Risk Documentation-only change that doesn’t alter runtime behavior or interfaces.

Overview Adds a new root AGENTS.md file with machine-readable contributor guidance, including environment setup (uv), a repo-local validation checklist (ruff/mypy/pytest/build), and engineering/PR hygiene guardrails emphasizing deterministic execution and fail-closed safety boundaries.

<sup>Written by Cursor Bugbot for commit dbf2d8b0d7f87eebd9ecc4a86abbe03d6e20602d. This will update automatically on new commits. Configure here.</sup>

<!-- /CURSOR_SUMMARY -->

Changed files

  • AGENTS.md (added, +47/-0)

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

Description (problem / solution / changelog)

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

Changed files

  • AGENTS.md (added, +233/-0)
  • lib/crewai/tests/test_agents_md.py (added, +129/-0)
RAW_BUFFERClick to expand / collapse

Contributors and automation agents lack a single machine-readable instruction file, leading to inconsistent local validation and avoidable PR churn.

Current behavior is insufficient because there is no repo-local AGENTS.md to codify deterministic validation, safety boundaries, and contribution workflow expectations.

Why now: cross-repo orchestration assumes repo-local guidance parity and this repo currently diverges.

Claim-to-codepath map:

  • Contributor guidance surface in README.md and contributing docs.
  • Validation workflow expectations for lib/crewai test/lint/format paths.

Requested behavior: introduce a repo-local AGENTS.md with explicit validation commands and safety rules aligned to current repo workflows.

Evidence Packet

  • Commit under test: 51754899
  • Runtime environment:
    • OS: Darwin 25.3.0 arm64
    • Python 3.14.0
    • go version go1.25.7 darwin/arm64
    • Node: v22.19.0
  • Minimal repro:
    1. Follow the repo's current local validation/CI-triage path.
    2. Observe the behavior described above for this issue.
  • Expected behavior: deterministic, documented behavior matching acceptance criteria below.
  • Actual behavior: behavior can be inconsistent for the scenario described above.

Acceptance Criteria

  • Implement the smallest code change that addresses the proven pain point.
  • Add focused regression test coverage for the changed behavior.
  • Ensure backward compatibility expectations are explicit in tests/docs.

extent analysis

Fix Plan

To address the issue, we will introduce a repo-local AGENTS.md file with explicit validation commands and safety rules.

Step-by-Step Solution:

  • Create a new file named AGENTS.md in the repository root.
  • Add the following content to AGENTS.md:
# Validation Commands
* `python -m unittest discover -s test`
* `go test -v ./...`
* `npm run lint`

# Safety Rules
* All code changes must be reviewed by at least one maintainer.
* All validation commands must pass before merging a pull request.
  • Update README.md and contributing documentation to reference the new AGENTS.md file.
  • Add regression test coverage to ensure the new validation commands and safety rules are enforced.

Example Code:

# tests/test_validation.py
import unittest
import subprocess

class TestValidationCommands(unittest.TestCase):
    def test_python_validation(self):
        subprocess.check_call(['python', '-m', 'unittest', 'discover', '-s', 'test'])

    def test_go_validation(self):
        subprocess.check_call(['go', 'test', '-v', './...'])

    def test_npm_validation(self):
        subprocess.check_call(['npm', 'run', 'lint'])

Verification

To verify the fix, follow these steps:

  • Run the validation commands listed in AGENTS.md to ensure they pass.
  • Create a new pull request with a code change that triggers the validation commands.
  • Verify that the pull request is blocked if the validation commands fail.

Extra Tips

  • Regularly review and update the AGENTS.md file to ensure it remains accurate and effective.
  • Consider automating the validation commands using CI/CD pipelines to reduce manual effort.

Vote matrix · Quick signals

Works
Did the solution work? Tap to confirm.
Easy Fix
Was it a quick fix?
Time Saver
Did it save you time?
Blocking
Was it severely blocking?
Common Issue
Are others likely hitting this too?
Flaky / Intermittent
Is it intermittent?
Verified / Reproducible
Can you reproduce it reliably?
Loading…
#api#ssr#installation#tensor shape#autograd error#search optimization#API routing#API middleware#SSR setup#ISR setup

Still need to ship something?

×6

Another batch ranked right after the header list — different links, same matching logic.

Back to top recommendations

TRENDING

crewai - ✅(Solved) Fix Add repo-local AGENTS.md with deterministic validation workflow guidance [2 pull requests, 2 comments, 2 participants]