feat: Add AGENTS.md file with project guidance for AI coding agents

[AClerbois]

Description

This PR adds an AGENTS.md file to the repository, following the agents.md standard. This file provides dedicated guidance for AI coding agents working with this project.

What is AGENTS.md?

AGENTS.md is an open-source community standard (used by 60k+ open-source projects) that provides a dedicated, predictable place for AI coding agents to find project-specific context and instructions. It complements README.md by containing detailed technical guidance that agents need but might clutter a README.

What's included

The AGENTS.md file includes:

• Project Overview - Clear description of the repository structure and purpose
• Repository Structure - Visual tree of the project layout
• Setup Commands - Installation, build, and validation commands
• Development Workflow - Guidelines for working with agents, prompts, and instructions
• Code Style Guidelines - Markdown and JavaScript conventions
• Pull Request Guidelines - Comprehensive checklist for contributions
• Pre-commit Checklist - Essential steps before submitting PRs
• Testing Instructions - How to validate changes, including the fix-line-endings.sh script

Key Features

✅ Line Endings Management - Includes explicit instructions to run bash scripts/fix-line-endings.sh before committing
✅ Comprehensive Guidelines - Detailed requirements for all file types (agents, prompts, instructions)
✅ Pre-commit Checklist - Clear steps to follow before creating a PR
✅ Testing Commands - All essential npm scripts documented
✅ Standards Compliance - Follows the agents.md specification

Benefits

• Provides AI coding agents with clear, structured guidance
• Helps maintainers by reducing repetitive explanations
• Improves consistency in contributions
• Follows an established open-source standard
• Compatible with major AI coding tools (GitHub Copilot, Cursor, Aider, Jules, etc.)

Testing

• ✅ File follows AGENTS.md standard format
• ✅ All setup commands tested and working (npm ci, npm run build, npm run collection:validate)
• ✅ Line endings script tested and documented
• ✅ Guidelines match existing contribution patterns
• ✅ Markdown formatting validated

Related

• AGENTS.md specification: https://agents.md/
• Examples on GitHub: https://github.com/search?q=path%3AAGENTS.md
• OpenAI Codex example: https://github.com/openai/codex/blob/-/AGENTS.md

[Copilot]

Pull request overview

This PR introduces an AGENTS.md file following the agents.md open-source standard to provide AI coding agents with structured guidance about the repository. The file documents project structure, setup commands, development workflows, code style guidelines, and contribution requirements.

Key Changes:

• Adds comprehensive AGENTS.md file with setup instructions, development workflow, and contribution guidelines
• Documents front matter requirements for agent, prompt, and instruction files
• Includes pre-commit checklist emphasizing the line endings normalization script

[AClerbois]

Thanks @copilot for the thorough review! 🙏

I've addressed all the comments:

✅ Fixed the mode field issue (lines 54 & 133)

• Changed from mode field to agent field
• Updated description to match actual repository convention: value should be 'agent' wrapped in single quotes
• Applied fix in both the "Prompt Files" section and the "Code Review Checklist"

✅ Added AGENTS.md reference to README.md

• Added a reference in the "Contributing" section
• Positioned right after the Contributing Guidelines mention
• Makes it easy for AI coding agents and contributors to discover this resource

All changes have been pushed to the PR. The documentation now accurately reflects the actual codebase conventions. 🚀