[FEATURE] Create root AGENTS.md documenting all CI-enforced rules for coding agents

[Vicente-Pastor]

Is your feature request related to a problem? Please describe.

AI coding agents (GitHub Copilot, Copilot coding agent, the daily Test Improver workflow, and the CLI Consistency Checker workflow) work on PRs in this repo but have no single authoritative document describing the rules they must follow. As a result agents sometimes emit code that violates CI checks — using yaml.dump() to file handles instead of yaml_io.dump_yaml(), using str(path.relative_to(base)) instead of portable_relpath(), or producing CLI help text that fails the consistency checker. Every failure wastes a CI cycle and requires a human to explain the rule to the agent again.

Ironically, both daily-test-improver.md and cli-consistency-checker.md already contain the instruction "read AGENTS.md first" — but the file does not exist.

Describe the solution you'd like

Create AGENTS.md at the repository root (next to README.md) as the authoritative, agent-readable contract for all coding agents working in this repository. The file must be read by every agent before making any code change.

Task breakdown

1. Audit workflows for all agent-visible rules

• 1.1 Read every .github/workflows/ file and extract linting, testing, and convention rules an agent could violate
• 1.2 Read docs/cli-reference.md and extract CLI documentation conventions
• 1.3 Read docs/contributing.md (if present) for code style and contribution rules
• 1.4 Check for .pre-commit-config.yaml, pyproject.toml lint sections, or ruff.toml and extract enforced linting rules
• 1.5 Check pyproject.toml for pytest options, coverage thresholds, and markers

2. Write AGENTS.md

• 2.1 Create file at repo root with a clear purpose statement: "This file is for AI coding agents. Read it before making any code change."
• 2.2 Setup section: exact commands — uv sync --extra dev --extra build, uv run apm --version
• 2.3 Before every commit checklist: run unit tests, run linter, check YAML I/O rule, check path portability rule
• 2.4 Code conventions: Python 3.12; uv only (no pip); CommandLogger for output; yaml_io.dump_yaml() for YAML writes; portable_relpath() for path strings; no raw print()
• 2.5 CLI conventions: help text structure (Usage / Description / Options / Examples); flag naming (--verbose/-v, --dry-run, --yes/-y); every new command/flag must appear in docs/cli-reference.md; no TODO markers in help strings
• 2.6 Testing conventions: tests/unit/ vs tests/integration/; mock all network calls in unit tests; no new external test deps without a tracked issue; no generated files in commits
• 2.7 Security section: CodeQL runs on every PR; no secrets in source; path traversal validation required; use marketplace/archive.py safe extraction helpers
• 2.8 PR hygiene: branch naming convention; do not modify scripts/test-*.sh in the same PR as feature changes; integration tests always run from main branch scripts

3. Validate the file

• 3.1 Run the CI lint patterns (yaml-io grep, portable_relpath grep) against the repo to confirm documented patterns are accurate
• 3.2 Have a second agent follow only AGENTS.md and verify it can set up and pass CI from scratch
• 3.3 Confirm copilot-setup-steps.yml still passes after adding the file

4. Keep AGENTS.md in sync

• 4.1 Add a comment in each workflow file pointing to AGENTS.md as the agent-facing documentation for that rule
• 4.2 When any new lint check or CI rule is added in future PRs, update AGENTS.md in the same PR
• 4.3 Verify that daily-test-improver and cli-consistency-checker workflows honour the "read AGENTS.md first" instruction once the file exists

Rules currently enforced in CI (must all appear in AGENTS.md)

Source	Rule
ci.yml	Python 3.12; uv for all dep management
ci.yml lint	No yaml.dump() to file handles outside utils/yaml_io.py (use yaml_io.dump_yaml())
ci.yml lint	No str(x.relative_to(y)) — use portable_relpath() from apm_cli.utils.paths
ci.yml	uv run pytest tests/unit tests/test_console.py -n auto --dist worksteal must pass
ci-integration.yml	Fork PRs require maintainer approval; scripts/test-*.sh run from main only
codeql.yml	Python + Actions static analysis; no known CWEs
cli-consistency-checker	Consistent help text structure and flag naming; docs/cli-reference.md parity
daily-test-improver	Read AGENTS.md first; no new test deps; no generated files in commits

Describe alternatives you've considered

• Put the rules in CONTRIBUTING.md: human-oriented prose; agents need machine-scannable, structured, short directives. A separate AGENTS.md follows the convention established by projects like google/adk-python.
• Put the rules inline in each workflow file: agents would need to read ~6 workflow files to reconstruct the full ruleset on every task. A single AGENTS.md is faster and less error-prone.
• Rely on CI to teach agents by failure: wastes CI minutes and requires human intervention. Proactive documentation is strictly better.

Additional context

• Both daily-test-improver.md and cli-consistency-checker.md already contain "read AGENTS.md first" — the file is expected but absent. Creating it closes that gap immediately.
• copilot-setup-steps.yml should be updated to reference AGENTS.md so Copilot coding agents receive it as part of their initial context.
• The AGENTS.md convention is documented by Anthropic and widely adopted in open-source repositories that integrate AI coding agents.

[sergio-sisternes-epam]

Excellent issue, @Vicente-Pastor -- well-researched and pragmatic.

Accepting this. The gap is real: two workflows already reference "read AGENTS.md first" but the file doesn't exist, and agents waste CI cycles rediscovering rules by failure.

A few notes for implementation:

• APM already has .github/instructions/*.instructions.md files with detailed per-module rules. AGENTS.md should serve as the top-level entry point that agents read first, pointing to those detailed instruction files for specifics -- not duplicating their content.
• Keep it concise and machine-scannable -- structured directives, not prose.
• The CI rule audit in this issue is a great starting checklist.

We'll pick this up for implementation.