Agent Instructions — FERRO AXIS

Workspace ownership

Cursor and Codex share one canonical git clone. Read Docs/AGENT-WORKSPACE.md before editing.

• Writable path only: /Users/mosesgonzales/Developer/ferro-axis-xcode-native-local/ferro-axis-xcode-native
• Do not edit the iCloud copy under Mobile Documents or use the sibling zip as a working tree
• Use cursor/<topic> or codex/<topic> branches; claim Active agent / Branch / Scope in Docs/BMAD-V6-HANDOFF.md before overlapping work
• Sync through GitHub origin; never force-push main

Product invariant

This is a calm, premium, full-metal 3D disassembly puzzle. Difficulty comes from spatial reasoning and deeper movable layers—not lives, currencies, timers, ads, random failure, or physics luck.

Architecture invariant

• GameSession and immutable definitions are the only authority for legal moves.
• Keep gameplay on integer GridPoint coordinates.
• RealityKit consumes snapshots and animates them; it must never become game-state authority.
• Axis changes are atomic: validate every active piece before committing.
• A blocked move must not mutate the snapshot. A partially open route may commit to the last legal node.
• Preserve deterministic undo by storing snapshots, not inverse animation guesses.

Visual invariant

• Match DesignReferences/01-core-gameplay.png first.
• Near-black graphite background, brushed steel/titanium pieces, cyan selected route, amber segmented axis ring, red contact only.
• Keep the HUD sparse and outside the central mechanism.
• Use procedural RealityKit geometry unless an authored USDZ materially improves readability.
• Never add hearts, life counters, coins, energy, boosters, or ad affordances.

Coding rules

• Native SwiftUI + RealityKit; no SceneKit and no third-party dependencies without an explicit architecture decision.
• Target iOS 18+, Swift 5 language mode, Xcode 16+.
• New rule behavior requires an XCTest before renderer polish.
• Keep UI on @MainActor and avoid mutable global state.
• Prefer small named methods and semantic feedback events over inline side effects.
• Treat accessibility labels, reduced motion, and haptic opt-out as production requirements.

Verification

Before handing off a change:

1. Build the FerroAxis scheme for an iPhone simulator.

2. Run FerroAxisTests.

3. Exercise select, blocked move, partial move, extraction, X ↔ Z reroute, depth cycle, undo, restart, hint, orbit, and zoom.

4. Compare a device screenshot to Docs/VISUAL-TARGET.md.