feat: Add architecture plan for rig relocation and component modularization

.codex/agents/architect.toml

@@ -21,6 +21,8 @@ You are the Lead Systems Architect. Refer to `AGENTS.md` for project directory s
    - Target Nodes / Classes modified.
    - Signal interfaces & static type contracts.
    - Layout/Theme updates required.
+   - **Visual Diagrams & Schematics:** Include ASCII diagrams or Mermaid charts illustrating node hierarchies, state transitions, or signal flow interactions.
+   - **Concrete Examples & Data Flows:** Provide code/data examples demonstrating practical usage, sample dictionary shapes, or step-by-step state transformations.
    - **Architectural Suggestions & Alternatives:** (Optional/Required if applicable) Highlight alternative approaches, potential pitfalls, or future-proofing ideas that improve the feature.
-3. **Handoff:** Save to `specs/[feature-name].md` and stop for user approval.
+3. **Handoff:** Save to `specs/[feature-name].md` and display a summary including key diagrams and practical examples, then stop for user approval.
 """

plans/PHASE_8_RIG_MODULARIZATION.md

@@ -0,0 +1,79 @@
+# Architecture Plan: Rig Relocation & Component Modularization
+
+### **Objective**
+
+Relocate `master_rig.tscn` to `res://scenes/stickman_rig.tscn` and decouple `stickman_rig.gd` into dedicated, single-responsibility sub-components to improve maintainability, testability, and concern separation.
+
+---
+
+### **Phase 1: File Operations & Scene Relocation**
+
+1. Move `res://master_rig.tscn` to `res://scenes/stickman_rig.tscn` within Godot to maintain internal UID mappings and resource links.
+
+2. Verify sub-resource integrity after relocation.
+
+---
+
+### **Phase 2: Script Modularization (`stickman_rig.gd`)**
+
+Extract key responsibilities into sub-nodes or dedicated helper scripts attached to `stickman_rig.tscn`:
+
+- **Ragdoll & Recovery Component (`StickmanRagdoll`)**
+- Move ragdoll body/joint tables (`RAGDOLL_BODIES`, `RAGDOLL_JOINTS`) and joint limit bands.
+
+- Move procedural physics node instantiation (`RagdollBodyContainer`), pin joint setups, and impulse application (`apply_ragdoll_velocity_boost`).
+
+- Extract rest detection polling (`REST_LINEAR_THRESHOLD`, `REST_ANGULAR_THRESHOLD`), rest timers, and stand-up recovery tweens (`request_recovery`, `snap_to_standing`).
+
+- **Locomotion & Terrain Subsystem (`StickmanLocomotion`)**
+- Extract surface raycast probing (`_probe_ground_y`, `_probe_terrain_fan`) and root elevation adjustments (`_reanchor_root_to_landing`).
+
+- Move airborne physics, horizontal drag calculations (`AIR_DRAG_X`), downward gravity acceleration, and procedural wind-drag pose flailing.
+
+- Extract landing impact velocity capture and knee-compression crouch/spring recovery tweens.
+
+- **Director & Action Runner (`StickmanActionRunner`)**
+- Extract the action queue data structure (`action_queue`) and execution state machines (`RunnerState`, `ActionPhase`).
+
+- Move pathfinding coordination (`NavigationAgent2D`), kinematic `walk_to` execution, and `FOOT_OFFSET` alignment.
+
+- Handle speech bubble triggers (`speak`), wait timers, and rule-injected reactive action clearing (`clear_reactive_actions`).
+
+- **Core Rig Coordinator (`StickmanRig`)**
+- Retain core rig state management (`ANIMATED`, `RAGDOLL`, `RECOVERING`).
+
+- Focus strictly on facing profiles (`FacingProfile`), TwoBoneIK bend direction toggles (`BendDirection`), and draw-order sorting (`Z_ORDER_BY_PROFILE`).
+
+- Serve as the root coordinator relaying signals and state transitions to sub-components.
+
+---
+
+### **Phase 3: Reference & Script Updates**
+
+Update hardcoded string references from `"res://master_rig.tscn"` to `"res://scenes/stickman_rig.tscn"`:
+
+- **`scripts/stickman_factory.gd`**: Update `spawn_from_data()` instantiation target.
+
+- **`scripts/test_harness.gd`**, **`scripts/stk_rig_adapter.gd`**, **`scripts/create_animations.gd`**: Update script comments, tool headers, and path constants.
+
+- **`tests/` Suite**: Search and replace hardcoded scene path string literals across all unit tests.
+
+---
+
+### **Phase 4: Documentation Updates**
+
+Update path references across project markdown files:
+
+- `README.md`, `AGENTS.md`, `RIGGING.md`, and relevant files in `specs/` and `plans/`.
+
+---
+
+### **Phase 5: Verification & Acceptance Criteria**
+
+1. **Separation & Testability**: Confirm that locomotion raycasting and action runner execution can be tested independently without instantiating ragdoll physics.
+
+2. **Factory Instantiation**: Verify `StickmanFactory.spawn()` loads `res://scenes/stickman_rig.tscn` cleanly without path errors.
+
+3. **Test Harness Verification**: Run `res://scenes/test_harness.tscn` via **F6** to ensure walk, speak, wait, and ragdoll actions execute cleanly.
+
+4. **Automated Suite**: Run the full project unit test suite in `tests/` to confirm all assertions pass.