chore(claude): refactor agent architecture and complete ecosystem

[rchardx]

Description

Comprehensively restructure Claude agent configuration with expanded content
and improved architecture. Add launcher-scheduler-expert agent and add-unit-tests
skill to establish complete agent ecosystem.

Key changes:

• Engine expert refactoring: Complete rewrite and expansion of engine agents
  (archon/fsdp/megatron) with 400+ additional lines of detailed guidance
• New launcher-scheduler-expert: 185-line agent for cluster launching and
  resource scheduling (Slurm/Ray/Kubernetes)
• New add-unit-tests skill: 228-line guided workflow for test development
• Updated CLAUDE.md: Complete agent table with stage-by-stage guidance
• Symbol cleanup: Replace all non-ASCII symbols (→, –, ✓, Greek letters)
  with ASCII equivalents across agent documentation
• Architecture alignment: Rename engine experts from generic "expert" to
  specific "engine-expert" for clarity and consistency

Type of Change

• Bug fix (non-breaking change that fixes an issue)
• New feature (non-breaking change that adds functionality)
• Breaking change (fix or feature that would cause existing functionality to not
  work as expected)
• Documentation update
• Code refactoring (no functional changes)
• Performance improvement
• Test coverage improvement

Checklist

• ]x] I have read the Contributing Guide
• I have run formatting tools (pre-commit or manual)
• I have run relevant unit tests and they pass
• I have added tests for new functionality
• I have updated documentation if needed
• My branch is up to date with main
• This PR introduces breaking changes (if yes, fill out details below)
• If this PR changes documentation, I have built and previewed it locally with
  jb build docs
• No critical issues raised by AI reviewers (/gemini review)

[gemini-code-assist]

Summary of Changes

Hello @rchardx, I'm Gemini Code Assist¹! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

This pull request significantly refactors the Claude Code agent architecture to enhance clarity and maintainability. It introduces more descriptive naming conventions for agents and provides structured guidance for development tasks, particularly for adding unit tests. These changes aim to improve the overall developer experience by ensuring consistent documentation and testing practices across the project.

Highlights

• Agent Renaming: Generic agent names (e.g., archon-expert) have been renamed to be more specific, now including "engine" (e.g., archon-engine-expert) for improved clarity and boundary definition.
• New Test Skill Added: A new skill, /add-unit-tests, has been introduced to provide comprehensive guidelines and best practices for adding unit tests within the AReaL project, covering test types, structure, and common pitfalls.
• Documentation Updates: The main CLAUDE.md documentation has been updated to reflect the new agent naming conventions, provide detailed agent usage timing, clarify boundaries, and include stage-by-stage agent guidance.
• Agent File Restructuring: Old, generic agent documentation files (fsdp-expert.md, megatron-expert.md, archon-expert.md) have been removed, replaced by the new, more specific *-engine-expert.md files.
• Hook Script Alignment: The check-expert-update.sh hook script has been updated to correctly reference the newly renamed agent files, ensuring consistency in automated checks.

🧠 New Feature in Public Preview: You can now enable Memory to help Gemini Code Assist learn from your team's feedback. This makes future code reviews more consistent and personalized to your project's style. Click here to enable Memory in your admin console.

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature	Command	Description
Code Review	/gemini review	Performs a code review for the current pull request in its current state.
Pull Request Summary	/gemini summary	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in pull request comments and review comments.
Help	/gemini help	Displays a list of available commands.

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for Github and other Google products, sign up here.

You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension.

Footnotes

1. Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

[gemini-code-assist]

Code Review

This pull request is a well-executed refactoring of the Claude agent architecture. The renaming of generic agents to more specific engine-expert variants (archon-engine-expert, fsdp-engine-expert, megatron-engine-expert) significantly improves clarity. The addition of the /add-unit-tests skill provides valuable and comprehensive guidance for developers. The documentation updates in CLAUDE.md and other files are clear and align with the changes. My review has identified a few minor stylistic issues in the new markdown agent files related to list numbering and hyphen usage, which can be addressed to improve source code readability and maintainability.

[Copilot]

Pull request overview

This PR refactors the Claude Code agent architecture around engine-focused experts and adds a guided /add-unit-tests skill to formalize testing conventions and workflows.

Changes:

• Reorganizes expert agents into engine-specific variants (fsdp-engine-expert, archon-engine-expert, megatron-engine-expert) and wires them into docs and hooks.
• Adds a new /add-unit-tests skill with step-by-step guidance, CI marker strategy, and example patterns for tests.
• Updates CLAUDE.md and planner guidance to clarify when to use which agent/skill, and fixes algorithm-expert’s scope-division references.

Reviewed changes

Copilot reviewed 11 out of 11 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
CLAUDE.md	Documents the new engine-specific expert agents, clarifies stage-by-stage usage, and introduces the /add-unit-tests skill in the skills list.
.claude/skills/add-unit-tests/SKILL.md	Introduces a detailed skill for adding unit tests, describing test types, pytest markers, distributed/GPU patterns, common mistakes, and how it ties into other skills.
.claude/hooks/check-expert-update.sh	Updates expert reminder filenames so code changes in FSDP/Archon/Megatron areas correctly point to the new *-engine-expert agent docs.
.claude/agents/planner.md	Refines the “When to activate” guidance to focus on multi-file planning, new features, and architectural decisions.
.claude/agents/megatron-expert.md	Removes the old Megatron implementation-deep expert in favor of the new engine-focused variant.
.claude/agents/megatron-engine-expert.md	Adds a MegatronEngine usage/configuration-focused agent with pointers to MegatronParallelStrategy, configs, checkpoints, and workflows.
.claude/agents/fsdp-expert.md	Removes the old broad FSDP/distributed expert agent.
.claude/agents/fsdp-engine-expert.md	Adds an FSDPEngine usage/configuration-focused agent, detailing relevant configs, helper modules, and integration patterns with workflows.
.claude/agents/archon-expert.md	Removes the old Archon/MoE expert agent.
.claude/agents/archon-engine-expert.md	Adds an ArchonEngine usage/configuration-focused agent with MoE, parallel dims, and test entrypoint references.
.claude/agents/algorithm-expert.md	Adjusts the maintainer guide’s scope-division note to reference the new engine-expert agents instead of the removed generic experts.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[garrett4wade]

LGTM