Rules

Rules are markdown files in .claude/rules/ that define how the orchestrator behaves, what agents are allowed to do autonomously, and conventions for VCS, builds, testing, and memory management.

All rules#

File	Rule	Purpose
00-orchestrator.md	Orchestrator	Routes requests to agents, defines complexity scaling and delegation format
01-autonomy.md	Autonomy	What can be done without asking vs what requires confirmation
02-context-management.md	Context management	Auto-compaction at 70%, what to preserve and discard
03-self-learning.md	Self-learning	Friction log format, trigger conditions for /update
04-error-handling.md	Error handling	Graceful degradation: skip failing component, retry once, use fallback
05-memory-management.md	Memory management	Dual-wiki scopes, on-demand loading, SESSION_CONTEXT lifecycle
06-vcs.md	Version control	Git and Perforce workflows, safe vs ask-first commands, binary file handling
07-build-system.md	Build system	Error parsing table, reflection macro specifics, module dependency conventions
08-testing-gates.md	Testing gates	Playtest gate protocol, test step template, when to gate
09-optional-plugins.md	Optional plugins	Commandlet plugin configuration, Blueprint inspection without a commandlet

---

Rule details#

00-orchestrator: Routing#

Defines how the orchestrator classifies requests and delegates to agents.

Context discipline: The orchestrator reads Docs/, CLAUDE.md, .uproject, and .claude/ files directly. It delegates reads of source code (Source/, Plugins/**/Source/, engine headers) to subagents to avoid consuming main context.

Routing posture: Proactive by default. Act first, report results. The only exceptions are VCS submit and playtest gates (human-only actions).

Complexity scaling:

• Simple: 1 agent, fewer than 5 tool calls
• Standard: 2–3 agents, 10–15 calls each
• Complex: 5–7 agents, serial pipeline

Bulk migration pattern: When copying code between plugins or modules, the planner builds a complete file inventory first. The implementer marks files DONE as it processes them. The explorer verifies completeness after all implementer invocations finish.

01-autonomy: What can be done without asking#

Autonomous (just do it): Read any project file, edit/create C++ source and config files, write documentation, search the codebase, search the web, run VCS safe commands, run /build.

Ask first: Large-scale refactors touching 10+ files, deleting source files, changes to .uproject or Build.cs, installing tools or packages.

Overengineering prevention: Do not add features beyond what was asked, do not add docstrings to unchanged code, do not create utility classes for one-time operations, do not add error handling for scenarios that cannot occur.

02-context-management: Auto-compaction#

Context is managed by auto-compaction at 70% usage.

Preserve on compaction: Current checkpoint ID and plan reference, all replication/authority decisions, GAS architecture decisions, list of all modified source files (full paths), build status, playtest gate status, pending Blueprint work.

Safe to discard: Raw file contents read but not modified, verbose build output from successful builds, intermediate search results.

03-self-learning: Friction logging#

When a user correction or recurring problem occurs, a one-line entry is logged in Docs/_working/retro/YYYY-MM.md with format: - YYYY-MM-DD [CATEGORY] observation (context).

On session start, unprocessed entries are counted. At 5+ entries, /update is recommended. At 10+ entries, it is strongly recommended.

Categories logged: ROUTING_CORRECTION, CORRECTION, PATTERN, SKILL_UNDERTRIGGER, SKILL_OVERTRIGGER, FRICTION, WIN.

04-error-handling: Graceful degradation#

Core principle: skip the failing component, note what was skipped, continue. Never retry the same operation more than once.

• Agent failure: Report to user, retry once with simplified objective, then use routing fallback
• Build failure: Parse errors, categorize, fix, rebuild. Never suppress errors.
• VCS errors: Report once per session, skip VCS operations if not configured
• Missing files: Create scaffolding for Docs/ files; ask about missing source files
• Permission denied: Report the missing permission and suggest the settings.json fix

05-memory-management: Dual wiki and on-demand loading#

Session-scoped (Docs/_working/sessions/): Debug traces, commandlet output, plans, exploration results. Ephemeral, not searchable by /recall.

Persistent (Docs/Design/, Docs/Dev/, Docs/Decisions/, Docs/_working/notes/): Updated only on confirmed events: VCS commit, explicit user request, or /map-* commands.

Default load rule: At session start, load only Docs/index.md. Do not load other wiki files until a specific need arises.

Dual-wiki retrieval: For gameplay debugging, load BOTH the relevant Design page (what should happen) and the Dev page (how it is implemented).

06-vcs: Version control#

VCS type is auto-detected by /setup and stored in project-config.json.

Git safe commands (autonomous): status, diff, log, add, commit, branch, stash, fetch, merge (fast-forward only), checkout, show, blame.

Git ask-first: push, rebase, reset --hard, force-push, branch -D.

Perforce safe commands (autonomous): edit, add, reopen, reconcile, opened, fstat, diff, describe, changes, sync, info, where, have, filelog, change, revert.

Perforce ask-first: submit. Submissions are shared and irreversible.

Perforce discipline: All p4 edit and p4 add must use -c <CL#>. Create a named changelist with p4 change first.

Binary files: .uasset, .umap, .fbx, .png, .wav must NOT be edited by text tools. Check locks before attempting any operation.

07-build-system: Build conventions#

All build invocation goes through the /build skill, which reads the command from project-config.json. Error patterns and their common fixes are listed in the rule for quick reference during manual debugging.

Module dependency convention: when adding new includes, check which module provides the type (grep engine headers), then add it to PublicDependencyModuleNames or PrivateDependencyModuleNames in Build.cs. Common modules: GameplayAbilities, GameplayTags, GameplayTasks, EnhancedInput, NetCore, AIModule.

08-testing-gates: Playtest protocol#

After implementing a gameplay feature: run /build (zero errors required), write numbered test steps, then STOP and wait for you to test in PIE.

Always gate: New abilities, gameplay bug fixes, hit detection/damage/combat changes, replication changes, UI/HUD changes, animation/montage changes, audio changes.

Never gate: Build-only fixes, documentation changes, code review, codebase exploration, config changes requiring editor restart.

09-optional-plugins: Blueprint inspection#

For projects with a commandlet plugin, it can be configured in project-config.json under plugins.commandlets to export Blueprint CDO properties from the command line.

Without a commandlet, Blueprint and asset data is accessed by reading C++ base classes, tracing UCLASS inheritance via /map-codebase, scanning the Content directory structure, and asking you to describe Blueprint graph contents when needed.