Agents

Agents are specialists the orchestrator routes to automatically based on your request. You describe what you need and the orchestrator picks the right agent.

All agents#

Agent	Model	Role	Max turns
planner	Claude Opus	Create checkpoint-based implementation plans	40
implementer	Claude Sonnet	Write and edit C++ code per checkpoint	50
debugger	Claude Opus	Diagnose and fix bugs, crashes, and unexpected behavior	40
reviewer	Claude Opus	Review code changes for correctness and risk	20
researcher	Claude Opus	Research engine APIs and gameplay patterns	30
explorer	Claude Sonnet	Navigate and understand the codebase (read-only)	30
performance-analyst	Claude Opus	Identify performance bottlenecks and recommend optimizations	30

---

planner#

Creates checkpoint-based implementation plans for features, refactors, and multi-step fixes. The orchestrator routes to this agent when you ask to "add a new ability", "implement knockback", or anything requiring multi-step planning with build and playtest gates.

What it does: Reads the relevant wiki pages, searches the codebase for involved files and dependencies, designs the approach considering replication model, GAS hierarchy, UPROPERTY/GC safety, and Blueprint-side work, then writes a plan to Docs/_working/sessions/<task-name>.md.

Plan structure: Each plan has a goal, non-goals, assumptions, numbered checkpoints (PT-01, PT-02...), Blueprint callouts, and a rollback section. Each checkpoint leaves the project compilable.

Migration tasks: For bulk code migrations (copying between plugins or modules), the planner first builds a complete file inventory in a <task-name>-INVENTORY.md file before designing checkpoints. The implementer uses this inventory as a checklist.

Does not: Write code, run builds, or do web research.

---

implementer#

Writes and edits game code for a specific plan checkpoint or focused change. One checkpoint per invocation. The orchestrator routes here when a plan exists and code needs writing.

What it does: Reads all files it will modify before making changes, implements exactly the scope described in the checkpoint, then reports files changed, a summary of changes, and any Blueprint callouts (editor steps needed for .uasset files).

UE conventions enforced: Preserves all UCLASS, USTRUCT, UENUM, UFUNCTION, UPROPERTY macros and specifiers; preserves GENERATED_BODY(); uses correct includes for new types; adds replication annotations for multiplayer-visible state.

Does not: Plan, review, do research, or edit binary assets (.uasset, .umap, .fbx, .png, .wav). For binary assets it writes exact editor steps and stops.

---

debugger#

Diagnoses and fixes gameplay bugs, crashes, and unexpected behavior. The orchestrator routes here when you report a crash, provide a callstack or log snippet, or when playtest results indicate a failure.

What it does: Reads the error message or repro steps, forms 2–3 ranked hypotheses, investigates the relevant code to eliminate theories, confirms the root cause by tracing the code path end to end, applies the minimal fix, and describes how to verify it.

UE bug categories it specializes in:

• Crashes from missing UPROPERTY/GC on UObject pointers, null checks, CDO initialization
• Replication bugs: authority checks, NetExecutionPolicy, RPC parameters, OnRep correctness
• GAS bugs: ability tags, GameplayEffect stacking, attribute modifiers, cue triggers
• Animation: montage notify timing, state machine transitions
• Build errors: includes, forward declarations, reflection macros, Build.cs

Does not: Add features, refactor code beyond the fix, or edit binary assets.

---

reviewer#

Reviews code changes for correctness, engine best practices, and risk. The orchestrator routes here when you ask to "review", "check my changes", or "audit the code" before submitting to version control.

What it does: Gets the change list from VCS (git diff, p4 diff), reads all changed files in full, applies the game development review rubric, and produces a prioritized findings report.

Review rubric:

• CRITICAL: crashes, GC hazards, authority bugs, data corruption, missing reflection macros
• WARNING: performance in hot paths, lifecycle issues, threading, missing null checks
• SUGGESTION: style, naming, Blueprint exposure, testability

Read-only. The reviewer never modifies code.

---

researcher#

Researches engine APIs, gameplay patterns, and technical approaches. The orchestrator routes here when you ask "how does GAS handle ability activation", "what is the best approach for replicating cooldowns", or need background on engine systems.

What it does: Checks the project's own wiki pages first, then searches the codebase for relevant headers and config, then uses web search for official UE documentation, Epic Developer Community, and Unreal Engine source headers. Returns a structured note with summary bullets, file paths, API references, and actionable takeaways.

Research budget: 10 tool calls (quick lookup), 20 (standard), 30 (deep investigation). Reports what was found and what remains unknown within the budget.

Does not: Write code, modify files, or run commands.

---

explorer#

Navigates and understands the codebase. The orchestrator routes here for "where is the hit detection class", "find the projectile base class", "what calls ApplyGameplayEffectToSelf", or when codebase facts are needed before routing to another agent.

What it does: Searches for files and symbols using Glob and Grep, reads files to verify context or trace logic, and returns findings with full file paths and line numbers. Casts wide first (directory structure, class hierarchy) then narrows.

UE search patterns: UCLASS(, UFUNCTION(, UPROPERTY(, GetLifetimeReplicatedProps, DOREPLIFETIME, CreateDefaultSubobject, ability subclasses, Build.cs dependency chains.

Read-only. The explorer never modifies files.

---

performance-analyst#

Identifies performance bottlenecks and produces prioritized optimization recommendations. The orchestrator routes here when you report FPS drops, hitching, high tick cost, or provide Unreal Insights profiling data.

What it does: Reads profiling data or Unreal Insights traces if provided, or analyzes code for known hotspot patterns if no profiling data is available. Estimates per-call cost and frame budget impact for each issue. Returns findings grouped by impact (HIGH / MEDIUM / LOW) with recommended fixes and expected gains.

Hotspot checklist: Tick functions doing per-frame work that could be event-driven, GAS GameplayEffect evaluation on every tick, redundant collision traces per frame, FString operations in hot paths, transient UObjects causing GC spikes, excessive RPCs per frame, over-replication of derivable state.

Read-only. The performance analyst never modifies files. It recommends changes for the implementer to apply.

---

How routing works#

The orchestrator matches your request to the routing table in 00-orchestrator and delegates to the appropriate agent. For complex tasks it chains agents in sequence (planner → implementer → reviewer). For independent investigations it can run agents in parallel.

You can influence routing by being specific: "debug this crash" routes to debugger, "plan how to add knockback" routes to planner, "find where damage is calculated" routes to explorer.