# Sprint 0 — GodotIQ Scaffolding

## Obiettivo
Creare la struttura completa del progetto GodotIQ: un MCP server Python che si avvia correttamente, con la struttura di cartelle definitiva, configurazione pyproject.toml, e un primo test che passa. Nessuna logica di business — solo lo scheletro funzionante.

## Contesto
GodotIQ è un MCP server (Model Context Protocol) per Godot 4.x. Usa Python 3.10+, l'SDK MCP ufficiale (`mcp`), trasporto stdio. Zero dipendenze esterne oltre a `mcp` e `pytest` per i test.

## Acceptance Criteria

### AC-1: Project Structure
- Directory structure matches the specification exactly
- All `__init__.py` files present in every Python package
- All `.gitkeep` files in empty directories
- 9 tool category directories under `src/tools/` (bridge, spatial, code, animation, flow, assets, memory, ui, navigation)

### AC-2: pyproject.toml Configuration
- Build system uses hatchling
- Dependencies include only `mcp>=1.0.0`
- Dev dependencies include `pytest>=7.0` and `pytest-asyncio>=0.21`
- Entry point `godotiq = "src.server:main"` configured
- pytest configured with `asyncio_mode = "auto"`

### AC-3: MCP Server Entry Point
- `src/server.py` imports and initializes `mcp.server.Server`
- Registers a `godotiq_ping` tool returning `{"status": "ok", "version": "0.1.0"}`
- Has a `main()` function that starts the server with stdio transport
- Type hints on all functions
- Docstrings on all functions

### AC-4: Parser Placeholders
- `tscn_parser.py`: `TscnNode` and `TscnScene` dataclasses, `parse_tscn()` raises `NotImplementedError`
- `gd_parser.py`: `GdSignal`, `GdFunction`, `GdScript` dataclasses, `parse_gd()` raises `NotImplementedError`
- `tres_parser.py`: `parse_tres()` raises `NotImplementedError`
- All dataclasses have type hints and field defaults

### AC-5: Cache System Placeholder
- `FileCache` class with `is_stale()`, `get()`, `put()`, `invalidate()`, `clear()` methods
- Uses `CacheEntry` dataclass with path, mtime, content_hash, data
- Hash-based staleness detection using file mtime

### AC-6: Configuration Loader
- `load_config()` returns `GodotIQConfig` with defaults when file missing
- Correctly parses `.godotiq.json` with project, conventions, asset_origins, rooms, protected_files, custom_rules, token_optimization
- `GodotIQConfig` dataclass with all fields

### AC-7: Tests Pass
- `pip install -e ".[dev]"` completes without errors
- `pytest` runs and ALL tests pass (6+ tests)
- `python -c "from src.server import server; print('OK')"` works

### AC-8: Configuration Files
- `.godotiq.example.json` with complete example configuration
- `.gitignore` with Python and Godot patterns
- `CLAUDE.md` with project instructions
- `README.md` with project description and quick start

## Struttura cartelle da creare

```
godotiq/
├── src/
│   ├── __init__.py
│   ├── server.py
│   ├── parsers/
│   │   ├── __init__.py
│   │   ├── tscn_parser.py
│   │   ├── gd_parser.py
│   │   └── tres_parser.py
│   ├── tools/
│   │   ├── __init__.py
│   │   ├── bridge/__init__.py
│   │   ├── spatial/__init__.py
│   │   ├── code/__init__.py
│   │   ├── animation/__init__.py
│   │   ├── flow/__init__.py
│   │   ├── assets/__init__.py
│   │   ├── memory/__init__.py
│   │   ├── ui/__init__.py
│   │   └── navigation/__init__.py
│   ├── cache/
│   │   ├── __init__.py
│   │   └── file_cache.py
│   └── config.py
├── tests/
│   ├── __init__.py
│   ├── conftest.py
│   ├── fixtures/.gitkeep
│   ├── test_server.py
│   ├── test_parsers/__init__.py
│   ├── test_parsers/.gitkeep
│   ├── test_tools/__init__.py
│   └── test_tools/.gitkeep
├── godot-addon/addons/godotiq/.gitkeep
├── .godotiq.example.json
├── CLAUDE.md
├── README.md
├── pyproject.toml
├── .gitignore
└── LICENSE
```

## Constraints
- NO business logic in parsers (only dataclass + NotImplementedError)
- NO dependencies beyond `mcp` and `pytest`/`pytest-asyncio`
- NO files in the Godot addon (only .gitkeep)
- NO modifying existing fixture files
- Every placeholder must have a docstring explaining future purpose
