[kovtcharov]

Summary

Adds AGENTS.md establishing coordination rules for coding agents (Claude Code, Cursor, Copilot, custom orchestrators) working on GAIA in parallel. Complements CLAUDE.md without duplicating it — CLAUDE.md owns project conventions; AGENTS.md owns multi-agent coordination. Priority order is explicit (CLAUDE.md > AGENTS.md > default agent behavior).

Why

With v0.20.0 carrying 11+ consumer-critical PRs landing in parallel, coordination becomes the dominant cost — typing speed isn't the bottleneck anymore. Without explicit rules, parallel agents create merge conflicts, divergent component patterns, and incoherent UX. This documents the discipline once so it doesn't get reinvented per release.

Key rules established

• Stop-the-line discipline — foundational PRs (e.g. PR feat(memory): agent memory v2 — second brain with hybrid search, LLM extraction, and observability dashboard #606 memory v2) freeze touching their file paths until they land. Coding agents check gh pr list --label stop-the-line before opening PRs.
• Spec-before-PR — issues with consumer-critical label require implementation specs at the depth of Skill auto-synthesis: procedural memory layer extending PR #606 #887/feat(skills): Phase 1 runtime — SKILL.md loader, validator, discovery + gaia skill CLI core #888/Privacy & telemetry audit + verification UX — make zero-telemetry a property #890 before agent assignment. New spec-ready label gates agent-assignment.
• Review chain — every agent-authored PR runs through code-reviewer agent + (architecture-reviewer if applicable) + claude.yml Opus + human review
• No silent test skips — reinforces CLAUDE.md no-fallback rule at the test layer
• Pre-flight checks — agents must check stop-the-line PRs and claudia_list_tasks before opening PRs

Cross-references

• Issue Agent-orchestration playbook for v0.20.0 (parallel coding agents) #899 — agent orchestration playbook (consumes the rules in this file)
• Issue Pre-flight implementation specs for under-specified consumer-critical issues #900 — pre-flight implementation specs for under-specified consumer-critical issues
• Issue Stop-the-line for PR #606 (memory) — no merges to memory-touching files until landed #903 — stop-the-line for PR feat(memory): agent memory v2 — second brain with hybrid search, LLM extraction, and observability dashboard #606 (canonical example of the rule)
• PR feat(memory): agent memory v2 — second brain with hybrid search, LLM extraction, and observability dashboard #606 — currently the active stop-the-line PR

Test plan

• Markdown renders correctly on GitHub (visual check on this PR's Files tab)
• All cross-referenced issue numbers (feat(memory): agent memory v2 — second brain with hybrid search, LLM extraction, and observability dashboard #606, Skill auto-synthesis: procedural memory layer extending PR #606 #887, feat(skills): Phase 1 runtime — SKILL.md loader, validator, discovery + gaia skill CLI core #888, Privacy & telemetry audit + verification UX — make zero-telemetry a property #890, Agent-orchestration playbook for v0.20.0 (parallel coding agents) #899, Pre-flight implementation specs for under-specified consumer-critical issues #900, Stop-the-line for PR #606 (memory) — no merges to memory-touching files until landed #903) exist
• Priority order is explicit and doesn't conflict with CLAUDE.md
• Pre-flight check commands (gh pr list --label stop-the-line, claudia_list_tasks) are accurate

[antmikinka]

How can we rely on an LLM when its context bloated to be following rules?

[kovtcharov]

How can we rely on an LLM when its context bloated to be following rules?

Splitting into multiple specialized agents and enabling them to communicate with each other is our best bet. If you're referring to this specific agents.md, this is specific to Claude code for development, not Gaia agents and is just a helper to coordinate agents like Claude.md.