AI-Assisted Development

The AReaL repository includes a comprehensive suite of AI-assisted development tools designed to streamline complex tasks such as adding new model architectures, managing distributed training clusters, and performing deep dependency upgrades. These tools are implemented as a collection of Domain Expert Agents, Repo-Local Skills, and Project Instructions compatible with tools like Claude Code, Cursor, and OpenCode.

AI Configuration Architecture

The AI assistance layer is organized into four primary directories, each serving a distinct role in the development lifecycle:

Directory	Purpose	Primary Tooling
.claude/agents/	Persona definitions for domain experts (FSDP, Megatron, Scheduling).	Claude Code
.agents/skills/	Cross-tooling automation (e.g., commit conventions, PR reviews).	General LLM Agents
.codex/	Project-wide context and rules for code generation.	Codex / GitHub Copilot
.opencode/	Native commands and skills for the OpenCode platform.	OpenCode

Data Flow: Natural Language to Code Entity

The following diagram illustrates how a natural language request from a developer is routed through the expert agents to interact with specific code entities.

Expert Agent Routing and Code Interaction

Sources: .claude/agents/launcher-scheduler-expert.md40-63 .claude/agents/archon-engine-expert.md79-119 .claude/agents/code-verifier.md28-86

---

Domain Expert Agents

Expert agents are Markdown-based persona definitions that provide deep context for specific subsystems.

Launcher & Scheduler Expert

Specializes in distributed deployments (Slurm, Ray, Local). It understands the relationship between ClusterSpecConfig and the Launcher hierarchy.

• Key Responsibilities: Troubleshooting CUDA_VISIBLE_DEVICES conflicts, managing BASE_ENVIRONS propagation, and validating NameResolveConfig .claude/agents/launcher-scheduler-expert.md42-86
• Implementation: Defined in .claude/agents/launcher-scheduler-expert.md14-20

ArchonEngine Expert

Focuses on the MoE-optimized ArchonEngine. It guides developers through the process of adding new HuggingFace models to the Archon backend.

• Key Responsibilities: Configuring ParallelStrategy (TP/PP/EP/CP), implementing BaseStateDictAdapter, and registering models via ModelSpec .claude/agents/archon-engine-expert.md32-119
• Implementation: Defined in .claude/agents/archon-engine-expert.md12-16

Code Verifier

A proactive agent that executes linting, formatting, and testing workflows.

• Key Responsibilities: Running pre-commit, executing pytest with GPU-awareness, and regenerating CLI documentation using docs/generate_cli_docs.py .claude/agents/code-verifier.md44-95
• Implementation: Defined in .claude/agents/code-verifier.md12-15

---

Repo-Local Skills and Commands

Skills are structured workflows that automate multi-step engineering processes.

Commit Conventions and PR Creation

AReaL enforces a strict Conventional Commits format with automatic scope inference based on file paths .agents/skills/commit-conventions/SKILL.md19-32

The /create-pr command automates the entire contribution lifecycle:

1. Rebase and Squash: Fetches origin/main and squashes local changes into a single clean commit .claude/commands/create-pr.md131-162
2. Scope Inference: Automatically maps file paths (e.g., areal/workflow/ to workflow) to commit scopes .claude/commands/create-pr.md239-253
3. PR Generation: Generates an intelligent title and description using gh pr create .claude/commands/create-pr.md254-272

Commit Scope Inference Mapping

File Path Pattern	Scope
areal/workflow/	workflow
areal/engine/	engine
areal/experimental/	archon
areal/infra/	infra
.agents/, .claude/	agents

Sources: .agents/skills/commit-conventions/SKILL.md53-71 .claude/commands/create-pr.md153-203

Intelligent PR Review (/review-pr)

The PR review skill performs a multi-phase analysis using specialized checklists and subagent consultation .agents/skills/review-pr/SKILL.md28-70

1. Risk Analysis: Categorizes PRs from LOW to CRITICAL based on touched files (e.g., archon_weight_sync.py triggers CRITICAL) .agents/skills/review-pr/MIGRATION.md40-110
2. Domain Templates: Selects from 12 L1 domains (Distributed Runtime, Numerics, etc.) to apply targeted checklists .agents/skills/review-pr/references/review-pr-templates.md8-14
3. Expert Consultation: Automatically invokes subagents like archon-expert or fsdp-expert for deep logic verification .agents/skills/review-pr/SKILL.md57-69

PR Review Workflow

Sources: .agents/skills/review-pr/SKILL.md37-70 .agents/skills/review-pr/references/review-pr-templates.md33-101

Unit Test Generation

The add-unit-tests skill enforces the project's testing conventions, specifically handling distributed mocks.

• Distributed Mocks: Uses torch.distributed.fake_pg and mocks dist.get_rank() for unit tests .claude/skills/add-unit-tests/SKILL.md108-142
• GPU Safety: Enforces the use of @pytest.mark.skipif(not torch.cuda.is_available()) .claude/skills/add-unit-tests/SKILL.md124-133

---

Configuration Reference

Directory Structure Details

Path	Description
.claude/agents/	Markdown files defining system prompts for Claude Code.
.agents/skills/	Cross-platform skills like commit-conventions and review-pr.
.opencode/skills/	OpenCode-specific implementations of repository skills.
.claude/commands/	Custom slash commands for Claude Code (e.g., /create-pr, /gen-commit-msg).

Key Review Signals

The following signals are used by the AI to determine review depth:

• Distributed Runtime: Triggered by process_group, collectives, or weight_sync .agents/skills/review-pr/references/review-pr-templates.md33-48
• Model Compute: Triggered by tree_attn, sdpa_varlen, or triton_kernel .agents/skills/review-pr/references/review-pr-templates.md50-63
• Numerics: Triggered by numerical_stability, mixed_precision_fp8, or reward_surface .agents/skills/review-pr/references/review-pr-templates.md115-127

Sources: .agents/skills/review-pr/MIGRATION.md57-88 .agents/skills/review-pr/references/review-pr-templates.md1-163 .claude/agents/launcher-scheduler-expert.md134-136