docs: add AGENTS.md — agent coding conventions and project reference

[neuron-tech-ai]

Adds AGENTS.md to give AI coding tools (Claude Code, Cursor, Copilot) a structured reference for project conventions, file structure, test requirements, and contribution workflow.

Without this file, agents navigating the codebase have to infer conventions from reading source files — this leads to inconsistent formatting, skipped tests, and PRs that don't follow project patterns. AGENTS.md is the explicit handshake.

What's in it: project layout overview, how to run tests, pre-commit hook expectations, naming conventions, and notes on the Python/Rust/TypeScript split.

Summary by CodeRabbit

• Documentation
  • Added a comprehensive AI agents reference guide covering project architecture, repository layout, development/test/lint/build commands, submission checklist, CI expectations, guidance on platform/ML import rules, considerations to avoid CI/dependency issues, and available agent workflows with invocation notes.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 1d1be96d-2fe1-4fb4-b7c1-18fb65891cd1

📥 Commits

Reviewing files that changed from the base of the PR and between e764785 and 782731b.

📒 Files selected for processing (1)

• AGENTS.md

---

📝 Walkthrough

Walkthrough

This PR adds AGENTS.md, a repository reference for AI agents that documents Voicebox architecture, repository layout, auto-generated artifact rules, development/test/lint/build commands, submission guidance, architecture notes, CI expectations, and available .agents/skills/ workflows.

Changes

Agent Documentation

Layer / File(s)

Summary

Agent repository reference guide AGENTS.md

Adds a comprehensive reference for AI agents: project overview (Voicebox architecture/components), repository structure, rules for auto-generated files (frontend API client, OpenAPI snapshot), common dev/test/lint/build commands, submission checklist, TTS backend layout and voice profiles, platform-specific MLX import rules, MCP server pointers, CI job expectations, "things to avoid" guidance, and .agents/skills/ workflow invocation examples.

Estimated code review effort

🎯 1 (Trivial) | ⏱️ ~5 minutes

Poem

🐰 A guide for agents bold and true,
Maps the Voicebox paths anew,
Auto files, CI flows, commands galore,
Follow the steps and explore more,
Hopping through docs — knowledge to pursue.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title directly and clearly describes the main change: adding AGENTS.md documentation for agent coding conventions and project reference.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

Tip

💬 Introducing Slack Agent: The best way for teams to turn conversations into code.

Slack Agent is built on CodeRabbit's deep understanding of your code, so your team can collaborate across the entire SDLC without losing context.

• Generate code and open pull requests
• Plan features and break down work
• Investigate incidents and troubleshoot customer tickets together
• Automate recurring tasks and respond to alerts with triggers
• Summarize progress and report instantly

Built for teams:

• Shared memory across your entire org—no repeating context
• Per-thread sandboxes to safely plan and execute work
• Governance built-in—scoped access, auditability, and budget controls

One agent for your entire SDLC. Right inside Slack.

👉 Get started

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@AGENTS.md`:
- Around line 15-38: The fenced repository tree block in AGENTS.md (the
triple-backtick block that lists the voicebox/ directory structure) lacks a
language identifier and should be changed to include one (for example ```text)
to satisfy markdownlint MD040; update the opening fence for that repository tree
block to use ```text so the tree is treated as plain text by the linter.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: e335b33f-e93e-49ab-b1b2-b1170506962b

📥 Commits

Reviewing files that changed from the base of the PR and between b35b909 and e764785.

📒 Files selected for processing (1)

• AGENTS.md

[neuron-tech-ai]

Fixed: added text language identifier to the repository tree fenced code block to satisfy MD040.