feat: Add AGENTS.md support alongside SHAI.md for agent instructions

[ElGigi]

Summary

This PR proposes adding support for the AGENTS.md file format as an alternative to the existing SHAI.md convention, enabling broader compatibility with the emerging ecosystem of AI coding agents.

Motivation

AGENTS.md is becoming a de facto standard for providing repository-specific instructions to AI agents, adopted by multiple tools and platforms. Supporting both formats would:

• Improve interoperability — Users already maintaining AGENTS.md files wouldn't need to duplicate content into SHAI.md
• Lower adoption friction — New users familiar with AGENTS.md can onboard SHAI without learning a new convention
• Maintain backward compatibility — Existing SHAI.md files continue to work as expected

Proposed Behavior

File resolution order (first match wins):

1. SHAI.md — Project-specific, takes precedence
2. AGENTS.md — Fallback if no SHAI.md exists

This allows teams to:

• Use SHAI.md for SHAI-specific instructions
• Use AGENTS.md for shared instructions across multiple AI tools
• Use both, with SHAI.md overriding when needed

Implementation Scope

• Update file discovery logic to check for both filenames
• Document the resolution order in README
• Add tests covering fallback behavior

References

• AGENTS.md convention: https://github.com/anthropics/anthropic-cookbook/blob/main/misc/prompt_caching/AGENTS.md
• Related discussion in AI tooling community regarding standardization
• https://agents.md/

Questions for Maintainers

• Should SHAI.md always take strict precedence, or consider a merge strategy?
• Any preference on handling nested/directory-level instruction files?