chore(agents): simplify AGENTS.md

[fbeaudoincoveo]

What's All This Then?

This PR is a follow up to #7133

Initially, I wanted to add a maintaining-agents-files Agent Skill to verify that each AGENTS.md file in the repository had:

• Valid commands in the Commands section
• Accurate directory representation in the Structure section
• Up-to-date dependency major versions in the Technology section
• Overall correct structure (correct sections, correct structure in each section, no more than 200 lines, etc.)

However, after reviewing the following research paper, I have come to the conclusion that our AGENTS.md should be even more focused and minimal, and we don't need a dedicated Agent Skill to maintain them.

The paper makes a convincing case that:

• The current Structure sections, as they are, do not add value and could in fact impair AI agents. It's better to focus on truly essential parts of the repository / package structure.
• Specifying dependency versions in Technology section of the AGENTS.md (even only major versions) is probably not worth it. AI agents will be able to look up the specific version number in the package.json if needed. So it's best to only mention only the key technologies used in the monorepo (and in each package, in individual embedded AGENTS.md files) without any version.
• The current Principles section risks lowering task success rate rather than improving it. Even without these instructions, coding agents will respect most of the principles we have enumarated, so having them in the root AGENTS.md only introduces the risk that the agent will focus too much of its inference token budget on trying to strictly adhere to these guidelines rather than focusing on the issue at hand.
• Some of the current items in the Boundaries section are too narrow and will only clutter the context window with information that the model will think is important but really isn't.

What this PR Does

• Kept Commands sections mostly as is (simplified a few things, but these were in good shape).
• Considerably simplified the Structure sections: I only kept the "most important" packages for the root AGENTS.md (atomic, headless, quantic), and explained the src/components structure + the typical component folder structure in the Atomic AGENTS.md. I got rid of the ASCII representation in favor of unordered lists (easier to parse, fewer tokens used)
• I removed the Principles section entirely. I only kept one rule about useless inline comments, but I moved it to the Boundaries section
• I considerably simplified the Boundaries section, only keeping what will be useful all or most of the time.

Next Steps

In upcoming PRs, I will:

• Get rid of all .instructions.md files (I already extracted most of the important generic infromation into the proper AGENTS.md, but there's still a lot of info that should be kept and put into Agent Skills).
• Get rid of all .prompt.md files (these will be reworked as Agent Skills).
• Add assuming-personas Agent Skill: this one will enable agents to pick the best expert persona for the job at hand.
• Remove all .agent.md files (we will no longer need them with the assuming-personas Agent Skill)
• Rename .claude folder to .agents, update opencode.json config, and update all references in AGENTS.md and Agent Skills

https://coveord.atlassian.net/browse/KIT-5488

[github-actions]

⚠️ Secrets Reference Detected in Workflow Changes

This pull request modifies GitHub Actions workflow files and includes references to secrets.

Please ensure:

• The secret is properly configured in the repository/organization settings
• The secret name follows naming conventions
• The secret is not being exposed in logs or outputs
• Access to the secret is appropriately scoped

Why am I seeing this?

This comment is automatically added when workflow changes include the word secrets to remind reviewers to verify proper secret handling.

[github-actions]

🔗 Scratch Orgs ready to test this PR:

• ✅ LWS Enabled: Open Org
• ✅ LWS Disabled: Open Org

[Copilot]

Pull request overview

Adds a new Agent Skill intended to guide auditing and maintenance of AGENTS.md files across the monorepo (KIT-5488), by defining a repeatable verification process and section-by-section rules.

Changes:

• Introduces a new .claude/skills/maintaining-agents-files/ skill with a documented audit workflow.
• Defines expected AGENTS.md section structure for root vs package files and concrete verification rules for Commands/Structure/Technology/Principles/Boundaries.
• Adds general constraints for keeping AGENTS.md files concise and non-duplicative.