💡 AGENTS.md Specification Alignment & Automated Validation

[github-actions[bot]]

Summary

The AGENTS.md convention has reached institutional maturity — now stewarded by the Agentic AI Foundation under the Linux Foundation, read by 30+ AI tools (Claude Code, Copilot, Cursor, Codex, Gemini CLI, Windsurf, Devin, Aider, Amazon Q), and adopted by 60,000+ repositories. This org was an early adopter with a comprehensive AGENTS.md. A CI validation step would ensure the org's AGENTS.md stays structurally aligned with the evolving spec, catches cross-repo drift, and validates that agent-facing instructions remain parseable by all target tools.

Market Signal

• AGENTS.md spec now under the Agentic AI Foundation (AAIF), part of the Linux Foundation — giving it institutional governance and a formal spec process
• 30+ AI tools parse AGENTS.md natively: Claude Code, Copilot, Cursor, Codex, Gemini CLI, Windsurf, Devin, Aider, Amazon Q, Augment Code, and others
• 60,000+ repositories have adopted the convention, creating a de facto standard
• Google's Agent-to-Agent (A2A) protocol provides complementary multi-agent communication standards with 50+ technology partners
• Emerging best practices emphasize short, deterministic, agent-useful instructions — not encyclopedic docs

User Signal

• Cross-repo standards drift detection is tracked as idea 💡 Cross-Repo Standards Drift Detection via Multi-Repo Analysis #341 — AGENTS.md validation is a concrete instantiation
• The org maintains AGENTS.md in .github as the canonical source with downstream repos (Broodly, TalkTerm, markets) extending it
• No automated validation currently exists to catch structural drift or spec divergence
• The org already validates other configuration files (workflow YAML, CODEOWNERS, dependabot.yml) in its compliance audit

Technical Opportunity

The compliance audit framework validates config files across repos. Add an AGENTS.md structural validator:

1. Section presence — required headings per the AAIF spec
2. Heading hierarchy — valid Markdown structure parseable by tools
3. Cross-reference integrity — links to other files, CLAUDE.md, SKILL.md resolve
4. Org-repo consistency — downstream repos' AGENTS.md imports from the org-level file correctly
5. Parsability smoke test — basic structural checks that all major tools agree on

Assessment

Dimension	Score	Rationale
Feasibility	high	Markdown linting + compliance audit extension — no new infrastructure
Impact	med	Prevents invisible drift that silently degrades agent behavior across repos
Urgency	low	No immediate deadline, but value grows with each new tool reading the file

Adversarial Review

Strongest objection: The AGENTS.md spec is too young and evolving too rapidly to build validation against. Tooling for a moving target wastes effort and creates false positives.

Rebuttal: Focus on stable structural elements all tools already rely on — section headings, Markdown structure, cross-references — not semantic content. Start with an informational (non-blocking) check. The cost of NOT validating is invisible drift where agent instructions become unparseable by one or more tools without anyone noticing. The org's compliance audit already validates other living documents.

Suggested Next Step

1. Review the emerging AGENTS.md spec from AAIF for stable structural requirements
2. Write a minimal linter checking section presence, heading hierarchy, and cross-repo import consistency
3. Add to the compliance audit as an informational (non-blocking) check initially
4. Promote to blocking after 2 audit cycles of zero false positives