💡 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

[don-petry]

📋 Initiative planned by the BMAD Scrum Master (Bob).

Epic #642 — AGENTS.md Specification Alignment & Automated Structural Validation

5 stories created (inert — labelled initiative, NOT initiative:auto):

• [Phase 1] Define the AGENTS.md structural rule set and spec-alignment reference #643 (S) — [Phase 1] Define the AGENTS.md structural rule set and spec-alignment reference
• [Phase 2] Build the standalone AGENTS.md structural linter #644 (L) — [Phase 2] Build the standalone AGENTS.md structural linter
• [Phase 3] Integrate the linter into the compliance audit (informational) + org-repo import consistency #645 (M) — [Phase 3] Integrate the linter into the compliance audit (informational) + org-repo import consistency
• [Phase 3] Add local canonical-AGENTS.md self-validation to CI (informational) #646 (S) — [Phase 3] Add local canonical-AGENTS.md self-validation to CI (informational)
• [Phase 4] Promotion mechanism: informational to blocking after two clean audit cycles #647 (M) — [Phase 4] Promotion mechanism: informational to blocking after two clean audit cycles

Open questions for review:

• Exact required-vs-recommended section list for the v1 rule set: Phase 1 proposes a minimal structurally-stable 'required' set (single H1 title, valid heading hierarchy, resolvable cross-references) and leaves section-presence items as 'recommended' until confirmed. Maintainer should confirm which sections, if any, become 'required' before the Phase 4 promotion to blocking.
• Repo placement / tracking split: this epic is tracked in petry-projects/.github, but the compliance-audit orchestration (scripts/aw-standards-sync.sh) and its tests live in the .github-private tooling repo. The plan is grounded on the assumption that the linter + audit integration land in the tooling repo where aw-standards-sync.sh lives, while the canonical AGENTS.md it validates lives in petry-projects/.github. Confirm this placement before implementation.

---

Review the epic and its sub-issue DAG, adjust as needed, then add initiative:auto to epic #642 to hand it to initiative-driver for auto-implementation.