Working with AI Agents

Use this page when you want Codex, ChatGPT, Claude, or another coding agent to stay on the public AuraJS surface instead of wandering into stale internal notes.

Use This Order

1. Start on Start Here.
2. Move to the smallest handbook or exact-reference page that matches the task.
3. Open the full contract pages only after you know the namespace or subsystem.

That keeps the search space small and reduces the chance of mixing 2D, 3D, multiplayer, and optional-module behavior.

Public Retrieval Surfaces

Use these public inputs first:

• Docs home: https://www.aurajs.gg/docs
• Start Here: https://www.aurajs.gg/docs/start-here
• Starter helper reference: https://www.aurajs.gg/docs/starter-utils-reference
• Packs and bundles: https://www.aurajs.gg/docs/packs-and-bundles
• Code placement guide: https://www.aurajs.gg/docs/where-does-this-code-live
• LLM routing index: https://www.aurajs.gg/llm.txt
• Alternate LLM routing index: https://www.aurajs.gg/llms.txt
• Public API schema: https://www.aurajs.gg/aurajs-public-api-schema-v1.json
• Exact reference index: https://www.aurajs.gg/docs/reference

Agent Skill Setup

Inside your codebase:

cd <your-codebase>
npx -y skills add Aura-Industry/auramaxx

Then point the agent at:

• Docs home: https://www.aurajs.gg/docs
• Start Here: https://www.aurajs.gg/docs/start-here
• Starter Utils Reference
• Packs and Bundles
• Where Does This Code Live?
• the current project files it actually needs to edit

Good Working Set

For most tasks, give the agent only these surfaces:

1. the installed AuraMaxx skill
2. Start Here
3. auramaxx explain --json from the current project
4. auramaxx check --json from the current project
5. Packs and Bundles when optional lanes are involved
6. the matching exact-reference page
7. one current example that is close to the task

Ask The Project First

Inside a real AuraJS project, the fastest AI-friendly retrieval surfaces are:

auramaxx explain --json
auramaxx check --json
auramaxx vendor helpers --json
auramaxx replay run replay.json --compact
auramaxx evidence --replay replay.json --compact

Read these fields before searching the repo:

• sourceBoundary: which authored roots are valid import territory
• starterUtils: whether the scaffold-local helper lane exists and which local modules it exposes
• aiGuidance: the current paved-road lane, preferred import path, module picks, and example paths
• packs: optional packs and bundles already selected for the project
• surfaceDrift: machine-readable reason codes for boundary status, local helper availability, and starter-lane alignment

Inside packs.selected, pay attention to:

• ownershipMode: package-selection means the pack is selected but still package-owned, while vendored-game-content means the project now owns the copied payload
• vendoredPaths: the exact project roots an agent should edit when the pack has been vendored
• installMode and sourceMode: whether the pack came from npm, workspace, or another supported vendor source

That keeps the agent grounded in the current project instead of historical repo context.

When ownershipMode is vendored-game-content, prefer editing those vendoredPaths directly instead of wandering back into the source pack package or workspace catalog copy.

Use replay and evidence when you want the agent to diagnose a gameplay bug with artifacts instead of prose:

• auramaxx replay run gives the agent a deterministic replay report with seed, input steps, checkpoints, and divergence output
• auramaxx evidence --replay ... writes one bundle with summary.json, state.json, inspect.json, perf.json, replay.json, and replay-report.json
• auramaxx vendor helpers --json lets the agent seed or resync src/starter-utils/ without guessing which helper files belong there

Avoid sending the agent into internal docs, archive docs, or old task reports unless you explicitly want historical context.