# GodotIQ Phase 3 — From "Funziona" to "Indispensabile"

## La Visione

Phase 1 ha dato intelligenza (parser, analisi, comprensione spaziale).
Phase 2 ha dato le mani (bridge, editing, runtime interaction).
**Phase 3 dà il cervello**: l'agent sa COSA fare, COME verificarlo, e QUANDO è riuscito.

Dopo Phase 3, un agent con GodotIQ può:
1. Ricevere "sposta lo scaffale vicino alla stampante"
2. Capire lo spazio (scene_map) → scegliere la posizione → muovere (node_ops)
3. Muovere la camera dell'editor per guardare il risultato
4. Fare screenshot DALL'EDITOR (senza avviare il gioco)
5. Se qualcosa non va, eseguire codice arbitrario nell'editor per fixare
6. Salvare la scena
7. Avviare il gioco, verificare che i worker raggiungano lo scaffale
8. Tutto con risposte compatte che non bruciano token

---

## I 6 Sprint

### Sprint 5a — MCP Prompt (0 codice, impatto massimo)

**Cosa**: Prompt di ~2000-3000 parole iniettato nell'agent via MCP prompt protocol.
**Perché**: Senza prompt, l'agent non sa come orchestrare i 27 tool. GDAI ha un prompt — noi dobbiamo averne uno migliore.

Il prompt copre:
1. **Tool discovery workflow**: "chiama prima project_summary, poi scene_map o scene_tree"
2. **Editing workflow**: "scene_tree → node_ops → save_scene → screenshot per verificare"
3. **Debug workflow**: "run → state_inspect → perf_snapshot → screenshot → stop"
4. **Quando usare cosa**: "scene_map per analisi statica, scene_tree per stato live"
5. **GDScript conventions**: ordine sezioni, naming, type hints (da GDAI prompt + nostre aggiunte)
6. **Common patterns**: come spostare nodi (scene_map → find space → node_ops → verify), come debuggare (run → watch → read events), come creare nuovi script (validate → script_ops create)
7. **Token efficiency tips**: "usa detail=brief per check veloci, detail=full solo per debug"
8. **exec usage**: "editor exec per query veloci, game exec per stato runtime"

**Deliverable**: File `src/godotiq/prompts/godot_development.md` registrato come MCP prompt.
**Test**: Agent (Claude Code) riceve il prompt e sa orchestrare i tool senza istruzioni aggiuntive.

---

### Sprint 5b — Editor Exec + Save Scene (2 tool, impatto critico)

#### `godotiq_exec` upgrade → context parameter

Il DESIGN.md specifica chiaramente: "Execute arbitrary GDScript **in the Godot editor**". GDAI fa esattamente questo — il loro `execute_editor_script` gira nel contesto editor con accesso completo a `EditorInterface`, `get_tree()`, nodi della scena, tutto.

Noi abbiamo implementato exec solo game-side (via EngineDebugger → RefCounted sandbox → no get_node). Questo è un gap critico.

**Fix**: Aggiungere parametro `context: "editor" | "game"` al tool exec.

- `context: "editor"` (DEFAULT) → esegue in `godotiq_server.gd` direttamente. Il codice è un tool script con accesso a EditorInterface, scene root, nodi. Come GDAI.
- `context: "game"` → il comportamento attuale (via EngineDebugger → runtime). Utile per query runtime.

**Implementazione editor-side** (in `godotiq_server.gd`):
```gdscript
func _handle_exec_editor(peer_id: int, id: String, params: Dictionary) -> void:
    var code: String = params.get("code", "")
    # Safety checks (same as game-side)...
    
    var script := GDScript.new()
    # KEY DIFFERENCE: extends EditorScript, not RefCounted
    # This gives access to get_editor_interface(), get_scene(), get_tree()
    script.source_code = "@tool\nextends Node\n\n" + code
    
    var obj = script.new()
    add_child(obj)  # temporary child of server node → has get_tree()
    var result = obj.run()
    remove_child(obj)
    obj.queue_free()
    
    send_response(peer_id, id, {"status": "OK", "result": str(result)})
```

L'agent può ora fare:
```python
exec(code="func run():\n\tvar root = get_tree().edited_scene_root\n\treturn root.get_child_count()")
exec(code="func run():\n\tEditorInterface.save_scene()")
exec(code="func run():\n\tvar node = get_tree().edited_scene_root.get_node('Entities/Worker_1')\n\treturn node.position")
```

#### `godotiq_save_scene` — nuovo tool

Dedicato perché è un'azione critica che merita safety e conferma:

```python
async def save_scene(path: str = "") -> dict:
    """Save the current scene in the editor.
    Args:
        path: Optional new path. Empty = save in place.
    """
```

Implementazione: handler editor-side in `godotiq_server.gd`:
```gdscript
func _handle_save_scene(peer_id: int, id: String, params: Dictionary) -> void:
    var save_path: String = params.get("path", "")
    if save_path.is_empty():
        EditorInterface.save_scene()
    else:
        EditorInterface.save_scene_as(save_path)
    send_response(peer_id, id, {
        "saved": true,
        "scene": EditorInterface.get_edited_scene_root().scene_file_path
    })
```

**Deliverable**: 2 tool (exec upgrade + save_scene), test, handler GDScript.

---

### Sprint 5c — Editor Screenshot + Camera Control (2 tool, visual debugging)

L'agent DEVE poter "vedere" il viewport 3D dell'editor senza avviare il gioco. Questo è il gap più grande per il debug visivo.

#### `godotiq_screenshot` upgrade → viewport parameter

Aggiungere `viewport: "game" | "editor"`:
- `"game"` (default) → comportamento attuale via EngineDebugger
- `"editor"` → cattura viewport 3D dell'editor, direttamente da godotiq_server.gd

Editor screenshot (in `godotiq_server.gd`):
```gdscript
func _handle_editor_screenshot(peer_id: int, id: String, params: Dictionary) -> void:
    var scale: float = params.get("scale", 0.5)
    var viewport_3d := EditorInterface.get_editor_viewport_3d(0)
    var img := viewport_3d.get_texture().get_image()
    # resize, encode, base64... same pattern as game screenshot
```

#### `godotiq_camera` — nuovo tool

Controlla la camera 3D dell'editor:
```python
async def camera(
    action: str = "look_at",        # "look_at", "focus_node", "get_position", "orbit"
    target: list[float] | None = None,  # [x, y, z] for look_at
    node: str = "",                  # node name for focus_node
    distance: float = 5.0,          # camera distance
) -> dict:
```

Implementazione via `EditorInterface`:
```gdscript
# Get the 3D editor camera
var camera := EditorInterface.get_editor_viewport_3d(0).get_camera_3d()
camera.global_position = target_pos + Vector3(0, distance * 0.5, distance * 0.7)
camera.look_at(target_pos)
```

**Nota**: potrebbe servire un workaround. `get_editor_viewport_3d()` restituisce un SubViewport ma il controllo diretto della camera editor potrebbe richiedere accesso a `Node3DEditorViewport` che non è esposto. In quel caso, fallback a `exec` editor-side per manipolare la camera. Da investigare con ricerca API.

**Deliverable**: 2 tool (screenshot upgrade + camera), test, handler GDScript.

---

### Sprint 5d — Validazione Spaziale in node_ops (intelligence layer)

Il DESIGN.md promette:
```json
{"op": "move", "node": "StorageShelf", "position": [1.8, 0, -0.5], "validate": true}
```
Con risposta:
```json
{"status": "OK", "validation": "Position valid — 0.6m from nearest wall, on navmesh, no overlap"}
```
o:
```json
{"status": "WARNING", "validation": "Position inside Wall_East bounding box. Move to [1.5, 0, -0.5]?"}
```

Questo è ciò che rende GodotIQ INTELLIGENTE e non un wrapper API.

**Come funziona:**
1. Quando `validate: true` in un'operazione move/scale/add_child:
2. Prima di eseguire l'op, chiama internamente scene_map (Phase 1) per analizzare lo spazio
3. Verifica: distanza da muri, overlap con altri nodi, posizione su navmesh
4. Se OK → esegue
5. Se problematico → restituisce WARNING con alternativa suggerita
6. Se critico → restituisce BLOCKED e NON esegue

**Implementazione**: Lato Python. Il tool `node_ops` Python intercetta `validate: true`, chiama `scene_map` internamente per raccogliere dati spaziali, fa il check, poi decide se procedere con la WebSocket call.

Questo è il layer di intelligenza che GDAI non ha. Un agent con GDAI muove un nodo dentro un muro e non se ne accorge. Con GodotIQ, non può succedere.

**Deliverable**: Upgrade di node_ops con validazione spaziale, test.

---

### Sprint 5e — Token Optimization (tutti i tool)

Ogni tool riceve `detail: "brief" | "normal" | "full"`:

```
brief  → 5-15 linee, fatti chiave, per check veloci
normal → 30-80 linee, dati strutturati (DEFAULT)
full   → 100+ linee, dump completo, per deep debug
```

**Phase 1 tool** (scene_map, dependency_graph, signal_map, etc.):
- Aggiungere parametro `detail` con default `"normal"`
- `brief`: solo conteggi + anomalie critiche
- `full`: tutto

**Bridge tool** (scene_tree, state_inspect, perf_snapshot, etc.):
- Aggiungere parametro `detail`
- `brief`: solo valori richiesti, nessun metadata
- `full`: + metadata, timestamps, context

**Diff-based responses** (sprint futuro, complessità alta):
- Hash delle risposte, seconda chiamata restituisce solo delta
- Implementare con cache server-side per sessione
- Non in Sprint 5e — richiede design più approfondito

**Deliverable**: Parametro `detail` su tutti i tool, test che verificano output size.

---

### Sprint 5f — Polish + Test Completo su PFT

1. **Test end-to-end reale**: un task completo su PFT eseguito dall'agent con GodotIQ
   - "Aggiungi una stampante nella FDM Bay"
   - L'agent usa: project_summary → scene_map → placement → node_ops → camera → editor_screenshot → save_scene
   - Verificare che il workflow funzioni senza intervento umano

2. **README**: setup guide, .mcp.json esempio, demo workflow

3. **Bug fixes** da stress test

4. **Cleanup**: rimuovere print diagnostici, consolidare test

---

## Timeline

| Sprint | Focus | Durata stimata | Tool dopo |
|--------|-------|----------------|-----------|
| 5a | MCP Prompt | 2-3 giorni | 27 (prompt aggiunto) |
| 5b | Editor Exec + Save | 3-4 giorni | 29 |
| 5c | Editor Screenshot + Camera | 3-4 giorni | 30-31 |
| 5d | Validazione Spaziale | 3-4 giorni | 31 (upgrade) |
| 5e | Token Optimization | 2-3 giorni | 31 (upgrade) |
| 5f | Polish + Stress Test | 3-5 giorni | 31 (ready) |
| **Totale** | | **~3 settimane** | **31 tool, production-ready** |

---

## Dopo Phase 3

GodotIQ avrà:
- **31 tool** (13 filesystem + 14 bridge + 4 Phase 3)
- **MCP prompt** che guida l'agent
- **Intelligence layer**: validazione spaziale, debug visivo, exec con accesso completo
- **Token efficiency**: risposte compatte, detail levels

L'agent con GodotIQ sarà in grado di:
- Analizzare un progetto Godot in 1 chiamata
- Modificare scene 3D con validazione automatica
- Debuggare visivamente (camera + screenshot) senza intervento umano
- Scrivere e validare script con convention check
- Testare il gioco (run + input + watch + verify) in modo autonomo
- Fare in 1 minuto quello che un dev fa in 30 minuti

Poi: landing page, demo video, launch.
