refactor: Update architect and spec-pipeline documentation for clarity and detail; add new Prop Editor plan

2026-09-20 00:26:11 -04:00
parent ed9a2d0d18
commit e3689c86c8
3 changed files with 219 additions and 23 deletions
@@ -1,28 +1,52 @@
 name = "architect"
-description = "Defines system requirements, evaluates architectural choices, and suggests technical improvements for Godot features."
+description = "Evaluates architectural choices, proposes Godot 4 best practices, asks interactive clarification questions, and writes implementation specs."
 model = "gpt-5.6-sol"
 model_reasoning_effort = "high"
 sandbox_mode = "read-only"
 developer_instructions = """
-You are the Lead Systems Architect. Refer to `AGENTS.md` for project directory standards and coding rules.
+You are the Lead Systems Architect specializing in Godot 4 and idiomatic GDScript. Refer to `AGENTS.md` for project directory standards and coding rules.
 ## Responsibilities
-
+1. **Analyze:** Read existing code patterns and node structures before designing.
-1. **Analyze:** Read existing code patterns before designing.
+2. **Critique & Innovate:** Identify edge cases, performance bottlenecks, or over-engineered designs. Offer superior GDScript patterns (e.g., Custom Resources, Component-based Nodes, Signal Bus, State Machines) if a better path exists.
-2. **Critique & Innovate:** Proactively identify edge cases, performance bottlenecks, or over-engineered designs. Offer superior alternative architectures or simpler GDScript patterns if you identify a better path.
+3. **Design:** Define API payload shapes, static GDScript type hints, node hierarchies, and signal flows.
 3. **Design:** Define API payload shapes, GDScript type hints, and signal flows.
 4. **Log:** Append trade-offs to `docs/tech_debt_and_optimizations.md`.
-## Workflow
+---
-1. **Scope, Critique & Clarify:** Ask up to 3 high-impact questions if requirements are ambiguous. If you see a simpler, more performant, or more scalable way to implement the feature, pitch it briefly before finalizing the spec.
+## TWO-PHASE WORKFLOW
-2. **Spec Creation:** Output a minimal specification containing:
+
-   - Target Nodes / Classes modified.
+### PHASE 1: Scope, Critique & Pitch (DEFAULT FIRST TURN)
-   - Signal interfaces & static type contracts.
+Unless explicitly instructed by the prompt to "Skip clarification and build spec immediately," DO NOT write to `specs/[feature-name].md` during your first response. 
 Instead, analyze the requirement and output a **Clarification & Architecture Brief**:
 1. **Clarification Questions (Up to 3):**
   - Identify structural ambiguities (e.g., node hierarchy, state handling, physics, static vs. dynamic loading).
   - For every question, present 2–3 choices and explicitly mark your recommended choice with `[Recommended]`.
 2. **Godot 4 Architectural Ideas & Best Practices:**
   - Pitch 1–3 engine-specific optimizations or architectural alternatives (e.g., leveraging `Resource` scripts for data separation, Composition over Inheritance, custom signals vs. direct calls).
   - Briefly explain *why* each option improves scalability, memory, or developer ergonomics.
 3. **Stop & Await Input:**
   - End with a request for the user to confirm the recommended defaults, choose alternatives, or approve suggested additions.
 ---
 ### PHASE 2: Spec Creation & Handoff (AFTER USER FEEDBACK)
 Once the user responds to Phase 1 (or approves the pitch), perform the following:
 1. **Generate Spec:** Output the complete specification into `specs/[feature-name].md` containing:
   - Target Nodes / Classes modified (with full static typing `class_name` contracts).
   - Signal interfaces & static payload shapes.
   - Layout/Theme updates required.
-   - **Visual Diagrams & Schematics:** Include ASCII diagrams or Mermaid charts illustrating node hierarchies, state transitions, or signal flow interactions.
+   - **Visual Diagrams & Schematics:** ASCII diagrams or Mermaid charts illustrating node hierarchies, state transitions, or signal interactions.
-   - **Concrete Examples & Data Flows:** Provide code/data examples demonstrating practical usage, sample dictionary shapes, or step-by-step state transformations.
+   - **Concrete Examples & Data Flows:** Code snippets, sample dictionary/resource 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.
+   - **Architectural Trade-offs:** Document choices made based on user feedback.
-3. **Handoff:** Save to `specs/[feature-name].md` and display a summary including key diagrams and practical examples, then stop for user approval.
+
 2. **Log Debt:** Append key architectural trade-offs to `docs/tech_debt_and_optimizations.md`.
 3. **Display Summary:** Summarize key diagrams and decisions in your final chat output and stop for user approval.
 """
@@ -1,23 +1,28 @@
 ---
 name: spec-pipeline
-description: "Lean implementation loop: Architect -> Developer -> User Verification."
+description: "Lean implementation loop: Architect (Clarify -> Spec) -> Developer -> User Verification."
 ---
 ## Execution Logic
-1. **Phase 1: Architecture (Optional for small edits)**
+1. **Phase 1a: Architecture Proposal & Clarification**
-   - `@architect` defines signatures, node structures, or spec updates in `specs/[feature-name].md`.
+   - `@architect` analyzes existing patterns, pitches 1–3 Godot best-practice ideas, and asks up to 3 clarification questions with `[Recommended]` options.
-   - **STOP:** Wait for user approval on design choices before invoking developer.
+   - `@architect` stops without writing the spec file yet.
-2. **Phase 2: Implementation & Engine Validation**
+2. **Phase 1b: User Feedback & Spec Generation**
-   - `@developer` updates code and scenes using targeted diffs/snippets.
+   - User approves, modifies, or selects choices from `@architect`'s proposal.
   - `@architect` writes the finalized specification to `specs/[feature-name].md` and logs decisions in `docs/tech_debt_and_optimizations.md`.
   - **STOP:** Wait for final user sign-off on the spec before invoking developer.
 3. **Phase 2: Implementation & Engine Validation**
   - `@developer` updates code and scenes using targeted diffs/snippets based on `specs/[feature-name].md`.
   - `@developer` runs headless syntax verification:
     `& "C:\Godot4\Godot_v4.7.1-stable_win64_console.exe" --headless --check-only --script "res://path/to/script.gd" --path "C:\Godot4\project"`
   - If static check fails, `@developer` fixes the code immediately.
-3. **Phase 3: User Hand-off (Stop)**
+4. **Phase 3: User Hand-off (Stop)**
   - Present the changes to the user to test inside the Godot Editor.
   - Do NOT update READMEs or documentation yet.
-4. **Phase 4: Documentation (Triggered manually by user)**
+5. **Phase 4: Documentation (Triggered manually by user)**
   - Only call `@writer` after the user confirms: _"Feature verified and working."_
@@ -0,0 +1,167 @@
 ### Objective Summary
 This revised plan details the addition of an **Attach** mode to the Prop Editor (`[ Arrange | Reshape | Attach ]`), introducing a flexible, **Role-Based Dynamic Anchor Architecture** for vector prop files (`.prop`). Instead of hardcoding weapon-centric anchors (like a fixed muzzle), anchors are defined as named dictionary entries assigned specific functional roles—such as `pivot`, `grip`, `emitter`, `impact`, or `mount`. Coupled with interactive canvas gizmos, a live semi-transparent Stickman Hand Preview silhouette, and `StickmanRig` IK attachment logic, this system allows any prop (from flashlights and magic staves to broadswords and rifles) to be held, flipped, and interacted with accurately across all facing profiles.
 ---
 ### 1. Dynamic Role-Based Anchor Data Architecture (`.prop` Schema)
 The `.prop` JSON file stores anchors in a flexible dictionary where each key represents a unique anchor identifier and contains an explicit `"role"` attribute.
 #### JSON Data Layout
 ```json
 {
  "version": "1.0",
  "prop_name": "Arcane Staff",
  "anchors": {
    "origin": {
      "role": "pivot",
      "x": 0.0,
      "y": 0.0
    },
    "primary_grip": {
      "role": "grip",
      "x": 0.0,
      "y": 18.0,
      "rotation_deg": 0.0,
      "z_index_offset": 1,
      "allowed_hands": "both"
    },
    "secondary_grip": {
      "role": "grip",
      "x": 0.0,
      "y": -12.0,
      "rotation_deg": 0.0,
      "z_index_offset": 1,
      "allowed_hands": "left_only"
    },
    "crystal_head": {
      "role": "emitter",
      "x": 0.0,
      "y": -48.0,
      "rotation_deg": -90.0
    }
  }
 }
 ```
 #### Key Parameter Schema
 - **`role`**: Enforced category enum (`pivot`, `grip`, `emitter`, `impact`, `mount`, `custom`) defining visual gizmo styling and runtime behavior.
 - **`x`, `y**`: Pixel offset relative to the prop’s root origin point (0,0).
 - **`rotation_deg`**: Angular rotation applied to the prop geometry when attached, aligning prop handles seamlessly with a stickman’s hand/wrist joint.
 - **`z_index_offset`**: Integer sorting shift (e.g., -1 or +1) controlling whether prop elements render behind or in front of the holding hand.
 - **`allowed_hands`**: Hand access permission (`both`, `left_only`, `right_only`) used during character interaction checks.
 #### Standard Anchor Role Registry
 - **`pivot`**: The mandatory root origin (0,0) used for spawning, ground collision, terrain placement, and linear/angular center-of-mass physics when thrown.
 - **`grip`**: Hand attachment targets for primary or secondary holding locations.
 - **`emitter`**: Action output coordinates for spell particles, flashlights/light cones, projectile spawns, spray nozzles, or laser beams.
 - **`impact`**: Point-of-contact coordinates for melee striking edges, spear points, or hammer heads.
 - **`mount`**: Auxiliary attachment locations for modular accessories, scopes, or vehicle mounts.
 ---
 ### 2. UI Integration & 'Attach' Mode Setup
 #### Segmented Mode Switcher
 - Expand the canvas toolbar mode control to three tabs: **`[ Arrange | Reshape | Attach ]`**.
 - Selecting **Attach** hides shape vertex handles and activates the anchor editing overlay.
 #### Attach Mode Toolbar
 - **Show Hand Overlay**: Toggle button to display/hide the semi-transparent stickman lower-arm and hand preview.
 - **Snap to Grid**: Toggle button for snapping anchor translation coordinates.
 - **Show Inactive Gizmos**: Toggle visibility for non-selected background anchors.
 #### Anchor Management Panel (Sidebar Inspector)
 - **Anchor List Control**:
 - Scrollable list showing all defined anchors with **Add Anchor**, **Delete**, and **Rename** buttons.
 - Ability to add dynamic custom anchors and assign them any standard role.
 - **Property Fields**:
 - **Role Selector**: Dropdown menu (`Pivot`, `Grip`, `Emitter`, `Impact`, `Mount`, `Custom`).
 - **Position Inputs**: Numeric fields for X and Y coordinates with arrow incrementors.
 - **Rotation Slider**: Angle adjustment (-180° to +180°) with numeric spinbox.
 - **Z-Index Offset**: Integer field (-5 to +5) for layer sorting relative to hands.
 - **Allowed Hands**: Dropdown (`Both`, `Left Only`, `Right Only`).
 - **Quick Preset Generator**: Buttons to instantly apply standard layouts (e.g., _One-Handed Grip_, _Two-Handed Weapon_, _Tool / Extinguisher Nozzle_, _Melee Edge_).
 ---
 ### 3. Canvas Visual Tools & Interactive Editing
 #### Role-Based Gizmo Markers
 Each anchor role renders with a distinct visual icon and color code on the canvas:
 - **`pivot`**: Yellow Crosshair (locked to or editable near origin).
 - **`grip`**: Cyan / Orange Hand Icon (primary vs. secondary grips).
 - **`emitter`**: Red Target Reticle (shows direction vector arrow for particle/beam orientation).
 - **`impact`**: Bright Pink Diamond / Slash Marker (indicates tip or edge).
 - **`mount`**: Purple Ring Anchor.
 #### Canvas Interaction Mechanics
 - **Translation Dragging**: Click and drag any anchor gizmo across the viewport with full grid-snap support.
 - **Rotation Arc Ring**: Selecting a `grip` or `emitter` anchor displays a surrounding rotation ring handle. Dragging the ring dynamically dials in `rotation_deg` while updating the live inspector readout.
 #### Stickman Hand Preview Silhouette Overlay
 - **Visual Representation**: When enabled, draws a semi-transparent stickman lower-arm and hand silhouette attached directly to the currently selected `grip` anchor.
 - **Real-Time Alignment**:
 - The arm and hand rotate dynamically in response to `rotation_deg` adjustments.
 - The preview respects `z_index_offset`, rendering the hand over or under prop geometry to give immediate visual feedback.
 - Guarantees sword hilts, briefcase handles, and tool grips fit stickman hands before running gameplay tests.
 ---
 ### 4. Rig Compatibility & Runtime Behavior (`StickmanRig`)
 - **IK Hand Attachment**:
 - `StickmanRig` queries the prop's `grip` anchors during pick-up or equip actions, snapping the wrist joint of `LeftLowerArm` or `RightLowerArm` to the exact anchor location.
 - **Facing Profile Mirroring**:
 - When a character flips (e.g., facing left with `scale.x = -1`), the prop mirrors along with the rig.
 - Symmetrical anchor positioning ensures tools and weapons flip naturally without offset errors.
 - **Action & Effect Dispatching**:
 - When firing, casting, or emitting light, runtime scripts search for anchors with the `emitter` role to instantiate particles, light nodes, or hitscan traces.
 - Melee collision scripts query `impact` anchors to detect high-velocity hit points.
 - **Throwing Physics**:
 - Dropping or throwing a prop applies linear/angular velocity calculations relative to the `pivot` anchor position.
 ---
 ### 5. Implementation Roadmap
 1. **Anchor Data Model & JSON Updates**:
 - Refactor internal dictionary parsers to support role-based dynamic key schemas.
 - Update `.prop` saving and loading procedures to serialize custom anchor entries and their `role` tags.
 2. **UI Switcher & Sidebar Panel**:
 - Add the `Attach` tab to the primary mode control `[ Arrange | Reshape | Attach ]`.
 - Build the Anchor Management sidebar panel with role selectors, dynamic list controls, and property spinboxes.
 3. **Canvas Rendering & Gizmo Input**:
 - Implement canvas drawing routines for role-specific gizmos (`pivot`, `grip`, `emitter`, `impact`, `mount`).
 - Add gizmo click-picking, drag translation, and rotation ring interaction handles.
 4. **Hand Preview Silhouette System**:
 - Create the semi-transparent lower-arm and hand preview overlay attached to `grip` anchors.
 - Connect real-time rotation and Z-order sorting updates to the overlay renderer.
 5. **Autosave, Thumbnail & Runtime Verification**:
 - Hook anchor adjustments into editor dirty-state tracking, undo/redo stacks, and autosave routines.
 - Verify exported `.prop` files in the asset selector preview and validate runtime IK snapping on the test stage.