# Work Plan: Sprint 0 — GodotIQ Scaffolding

Created Date: 2026-03-02
Type: feature
Estimated Duration: 1 day
Estimated Impact: 30+ files (new project scaffolding)
Related Issue/PR: N/A

## Related Documents
- Design Doc: [docs/design/sprint-0-scaffolding.md](/docs/design/sprint-0-scaffolding.md)
- Test Skeletons: [docs/plans/test-skeletons-sprint-0.md](/docs/plans/test-skeletons-sprint-0.md)
- Full Design: [DESIGN.md](/DESIGN.md)

## Objective

Create the complete working skeleton of the GodotIQ MCP server project. After this sprint, the project has a valid Python package that installs, a running MCP server with a single ping tool, placeholder parsers with dataclasses, a working FileCache, a configuration loader, and a full passing test suite. No business logic — just the foundation that all future sprints build on.

## Background

The project currently contains only `DESIGN.md` (full product design) and an empty `CLAUDE.md`. Every file, directory, configuration, and test must be created from scratch. This is Sprint 0: the scaffolding sprint.

## Phase Structure Diagram

```mermaid
graph TD
    P0["Phase 0: Test Preparation<br/>(Red state unit tests)"]
    P1["Phase 1: Foundation<br/>(directories, pyproject.toml, __init__.py)"]
    P2["Phase 2: Core Implementation<br/>(server, parsers, cache, config)"]
    P3["Phase 3: Integration<br/>(integration tests, E2E test, config files)"]
    P4["Phase 4: Quality Assurance<br/>(all AC verified, full green)"]

    P0 --> P1
    P1 --> P2
    P2 --> P3
    P3 --> P4
```

## Task Dependency Diagram

```mermaid
graph LR
    subgraph "Phase 0"
        T0A["T0.1: Unit test skeletons<br/>(Red state)"]
    end

    subgraph "Phase 1"
        T1A["T1.1: Directory structure<br/>+ __init__.py + .gitkeep"]
        T1B["T1.2: pyproject.toml"]
        T1C["T1.3: pip install -e .[dev]"]
    end

    subgraph "Phase 2"
        T2A["T2.1: server.py<br/>+ godotiq_ping"]
        T2B["T2.2: Parser placeholders<br/>+ dataclasses"]
        T2C["T2.3: file_cache.py<br/>(FileCache impl)"]
        T2D["T2.4: config.py<br/>(Config loader impl)"]
    end

    subgraph "Phase 3"
        T3A["T3.1: conftest.py +<br/>unit tests Green"]
        T3B["T3.2: Integration tests<br/>(INT-1, INT-2, INT-3)"]
        T3C["T3.3: E2E test<br/>(E2E-1)"]
        T3D["T3.4: Config files<br/>(.gitignore, CLAUDE.md,<br/>README.md, LICENSE,<br/>.godotiq.example.json)"]
    end

    subgraph "Phase 4"
        T4A["T4.1: Quality assurance<br/>+ AC verification"]
    end

    T0A --> T1A
    T1A --> T1B
    T1B --> T1C
    T1C --> T2A
    T1C --> T2B
    T1C --> T2C
    T1C --> T2D
    T2A --> T3A
    T2B --> T3A
    T2C --> T3A
    T2D --> T3A
    T3A --> T3B
    T2A --> T3B
    T3B --> T3C
    T3D -.-> T3C
    T3C --> T4A
```

**Parallel tasks**: T2.1, T2.2, T2.3, T2.4 can all be implemented in parallel after Phase 1 completes. T3.4 (config files) is independent and can be done any time during Phase 3.

## Risks and Countermeasures

### Technical Risks
- **Risk**: MCP SDK API may have changed since documentation was written
  - **Impact**: server.py registration pattern may not work as expected
  - **Countermeasure**: Verify MCP SDK version pinned in pyproject.toml; check SDK source/docs for current `@server.tool()` decorator API before implementation
  - **Detection**: INT-3 test will fail if tool registration does not work

- **Risk**: pytest-asyncio configuration mode differences across versions
  - **Impact**: Async tests may not auto-detect or may require explicit markers
  - **Countermeasure**: Pin `pytest-asyncio>=0.21`, set `asyncio_mode = "auto"` in pyproject.toml as specified in AC-2

- **Risk**: Editable install (`pip install -e .`) may behave differently with src layout
  - **Impact**: Import paths like `from src.server import server` may not resolve
  - **Countermeasure**: Verify hatchling configuration includes correct package discovery; test import immediately after install (Phase 1 verification)

### Schedule Risks
- **Risk**: None significant — Sprint 0 is mechanical scaffolding with well-defined outputs
  - **Countermeasure**: All tasks have clear completion criteria and small scope

## Implementation Phases

### Phase 0: Test Preparation — Red State (Estimated commits: 1)
**Purpose**: Write unit test skeletons that will fail (Red state), establishing the TDD anchor for Phase 2 implementation.

**Strategy**: Strategy A (Test-Driven Development) — test skeleton information is provided. Unit tests go Red here, Green during Phase 2/3 implementation. Integration and E2E tests are created and executed later (Phase 3).

#### Tasks
- [ ] **T0.1**: Create `tests/test_server.py` with 6 unit test stubs (Red state)
  - `test_server_instance_created` — AC-3: server object exists and is `mcp.server.Server`
  - `test_ping_tool_registered` — AC-3: "godotiq_ping" in registered tools
  - `test_ping_returns_expected` — AC-3: returns `{"status": "ok", "version": "0.1.0"}`
  - `test_parser_stubs_raise` — AC-4: all three `parse_*()` raise `NotImplementedError`
  - `test_config_defaults` — AC-6: `load_config()` returns defaults when no file
  - `test_config_loads_json` — AC-6: `load_config()` reads `.godotiq.json` correctly

  **Test case resolution**: 0/6 (all Red)

#### Phase Completion Criteria
- [ ] `tests/test_server.py` exists with 6 test functions containing real assertions
- [ ] All 6 tests fail with `ImportError` or `ModuleNotFoundError` (correct Red state)
- [ ] Tests are executable via `pytest tests/test_server.py` (they fail, but pytest collects them)

#### Operational Verification Procedures
1. Run `pytest tests/test_server.py --co` — should collect 6 tests
2. Run `pytest tests/test_server.py` — all 6 should FAIL (Red state confirmed)

---

### Phase 1: Foundation — Directory Structure and Build Configuration (Estimated commits: 2)
**Purpose**: Create the complete directory tree, all `__init__.py` files, `.gitkeep` files, and a valid `pyproject.toml` so that `pip install -e ".[dev]"` succeeds.

#### Tasks
- [ ] **T1.1**: Create full directory structure with `__init__.py` and `.gitkeep` files — AC-1 support
  - `src/__init__.py`
  - `src/parsers/__init__.py`
  - `src/tools/__init__.py`
  - `src/tools/{bridge,spatial,code,animation,flow,assets,memory,ui,navigation}/__init__.py` (9 dirs)
  - `src/cache/__init__.py`
  - `tests/__init__.py`
  - `tests/test_parsers/__init__.py`
  - `tests/test_tools/__init__.py`
  - `.gitkeep` in: `tests/fixtures/`, `tests/test_parsers/`, `tests/test_tools/`, `godot-addon/addons/godotiq/`
  - Create empty placeholder files: `src/server.py`, `src/config.py`, `src/parsers/tscn_parser.py`, `src/parsers/gd_parser.py`, `src/parsers/tres_parser.py`, `src/cache/file_cache.py`

- [ ] **T1.2**: Create `pyproject.toml` with hatchling build system — AC-2 support
  - `[build-system]` with hatchling
  - `[project]` with name `godotiq`, version `0.1.0`, python `>=3.10`
  - `dependencies = ["mcp>=1.0.0"]`
  - `[project.optional-dependencies] dev = ["pytest>=7.0", "pytest-asyncio>=0.21"]`
  - `[project.scripts] godotiq = "src.server:main"`
  - `[tool.pytest.ini_options] asyncio_mode = "auto"`
  - Package discovery configured for `src/` layout

- [ ] **T1.3**: Run `pip install -e ".[dev]"` and verify success — AC-7 partial

#### Phase Completion Criteria
- [ ] All 9 tool category directories exist under `src/tools/` with `__init__.py`
- [ ] Every Python package directory contains `__init__.py` (13 packages total)
- [ ] All `.gitkeep` files present in empty directories (4 locations)
- [ ] `pip install -e ".[dev]"` exits with code 0
- [ ] `python -c "import src"` works without error

#### Operational Verification Procedures
1. `find src -name "__init__.py" | wc -l` — should be 13
2. `find . -name ".gitkeep" | wc -l` — should be 4
3. `ls src/tools/` — should show 9 directories + `__init__.py`
4. `pip install -e ".[dev]"` — exit code 0
5. `python -c "import src; print('OK')"` — prints OK

---

### Phase 2: Core Implementation — Server, Parsers, Cache, Config (Estimated commits: 4)
**Purpose**: Implement all source modules. After this phase, every `from src.X import Y` works, the MCP server has a registered ping tool, FileCache is fully functional, and config loading works. Unit tests go from Red to Green.

#### Tasks
- [ ] **T2.1**: Implement `src/server.py` — MCP server with `godotiq_ping` tool — AC-3 support (3 items)
  - Import and instantiate `mcp.server.Server` as module-level `server`
  - Register `godotiq_ping` tool via `@server.tool()` decorator
  - Tool returns `{"status": "ok", "version": "0.1.0"}`
  - Implement `main()` function that starts server with `mcp.server.stdio.stdio_server` transport
  - Type hints on all functions, docstrings on all public functions
  - **Completion**: `test_server_instance_created`, `test_ping_tool_registered`, `test_ping_returns_expected` should pass

- [ ] **T2.2**: Implement parser placeholders with dataclasses — AC-4 support (3 items)
  - `src/parsers/tscn_parser.py`: `TscnNode` dataclass (name: str, type: str, properties: dict, children: list), `TscnScene` dataclass (nodes: list[TscnNode], resources: dict), `parse_tscn()` raises `NotImplementedError`
  - `src/parsers/gd_parser.py`: `GdSignal` dataclass (name: str, args: list), `GdFunction` dataclass (name: str, args: list, return_type: str), `GdScript` dataclass (signals: list, functions: list, extends: str), `parse_gd()` raises `NotImplementedError`
  - `src/parsers/tres_parser.py`: `parse_tres()` raises `NotImplementedError`
  - All dataclasses have type hints, field defaults, and docstrings
  - **Completion**: `test_parser_stubs_raise` should pass

- [ ] **T2.3**: Implement `src/cache/file_cache.py` — FileCache class — AC-5 support (5 items)
  - `CacheEntry` dataclass with fields: `path` (str), `mtime` (float), `content_hash` (str), `data` (Any)
  - `FileCache` class with methods:
    - `is_stale(path: str) -> bool` — compares stored mtime with current file mtime
    - `get(path: str) -> Optional[Any]` — returns cached data if not stale, None otherwise
    - `put(path: str, data: Any) -> None` — stores data with current mtime and content hash
    - `invalidate(path: str) -> None` — removes single cache entry
    - `clear() -> None` — removes all cache entries
  - Hash-based staleness detection using `os.path.getmtime()` and `hashlib`
  - Type hints, docstrings on all public methods

- [ ] **T2.4**: Implement `src/config.py` — Configuration loader — AC-6 support (2 items)
  - `GodotIQConfig` dataclass with all fields from Design Doc: project, conventions, asset_origins, rooms, protected_files, custom_rules, token_optimization
  - `load_config(path: Optional[str] = None) -> GodotIQConfig`:
    - Returns defaults when file missing (no error)
    - Parses `.godotiq.json` when present
  - Type hints, docstrings on all public functions
  - **Completion**: `test_config_defaults`, `test_config_loads_json` should pass

#### Phase Completion Criteria
- [ ] `from src.server import server, main` works
- [ ] `from src.parsers.tscn_parser import TscnNode, TscnScene, parse_tscn` works
- [ ] `from src.parsers.gd_parser import GdSignal, GdFunction, GdScript, parse_gd` works
- [ ] `from src.parsers.tres_parser import parse_tres` works
- [ ] `from src.cache.file_cache import FileCache, CacheEntry` works
- [ ] `from src.config import load_config, GodotIQConfig` works
- [ ] All 9 tool packages importable: `from src.tools.bridge import *` etc.
- [ ] All 6 unit tests in `test_server.py` pass (Green state)
- [ ] **Test case resolution: 6/6 unit tests Green**

#### Operational Verification Procedures
1. `python -c "from src.server import server; print(type(server))"` — prints Server class
2. `python -c "from src.parsers.tscn_parser import parse_tscn; parse_tscn('x')"` — raises NotImplementedError
3. `python -c "from src.cache.file_cache import FileCache; fc = FileCache(); print('OK')"` — prints OK
4. `python -c "from src.config import load_config; c = load_config(); print(c)"` — prints config with defaults
5. `pytest tests/test_server.py -v` — 6 passed, 0 failed

---

### Phase 3: Integration — Tests, Config Files, and Full Verification (Estimated commits: 3)
**Purpose**: Create `conftest.py`, implement integration tests (from test skeletons), E2E test, and all configuration files. After this phase, every test passes and the project is complete.

#### Tasks
- [ ] **T3.1**: Create `tests/conftest.py` with shared fixtures
  - `project_root` fixture returning project root `Path`
  - `tmp_config` fixture creating temporary `.godotiq.json` for config tests
  - Any other shared test utilities

- [ ] **T3.2**: Implement integration tests from skeletons — AC-1, AC-2, AC-3, AC-7, AC-8 support
  - Create `tests/test_scaffolding_int.py` based on test skeleton:
    - **INT-1** `TestProjectStructureComplete.test_ac1_ac8_project_structure_matches_specification` — AC-1, AC-8
      - Verifies all directories, `__init__.py`, `.gitkeep`, config files exist
      - @category: core-functionality, @dependency: filesystem, @complexity: medium
    - **INT-2** `TestAllModulesImportable.test_ac2_ac3_all_source_modules_import_without_error` — AC-2, AC-3
      - Imports every module and symbol, verifies no ImportError
      - @category: core-functionality, @dependency: src + pyproject.toml, @complexity: medium
    - **INT-3** `TestMcpServerPingToolRegistered.test_ac3_ping_tool_registered_and_returns_correct_response` — AC-3
      - Async test: lists tools, invokes godotiq_ping, checks exact response
      - @category: core-functionality, @dependency: src.server + mcp SDK, @complexity: high
  - **Test case resolution: 3/3 integration tests Green**

- [ ] **T3.3**: Implement E2E test from skeleton — AC-7 support
  - Create `tests/test_scaffolding_e2e.py` based on test skeleton:
    - **E2E-1** `TestFullInstallTestImportCycle.test_ac7_full_install_pytest_import_cycle` — AC-7
      - Subprocess: `pip install -e ".[dev]"` exits 0
      - Subprocess: `pytest` exits 0, 6+ tests collected, 0 failures
      - Subprocess: `python -c "from src.server import server; print('OK')"` exits 0
      - @category: e2e, @dependency: full-system, @complexity: high
  - **Test case resolution: 1/1 E2E test Green**

- [ ] **T3.4**: Create all configuration and documentation files — AC-8 support (5 items)
  - `.godotiq.example.json` — complete example with all fields (project, conventions, asset_origins, rooms, protected_files, custom_rules, token_optimization)
  - `.gitignore` — Python patterns (__pycache__, *.pyc, .eggs, dist/, *.egg-info, .venv/) + Godot patterns (.godot/, *.import) + IDE patterns (.vscode/, .idea/)
  - `CLAUDE.md` — project instructions for AI assistants (project structure, conventions, how to run tests)
  - `README.md` — project description, quick start (pip install, run server), architecture overview
  - `LICENSE` — MIT license

#### Phase Completion Criteria
- [ ] `tests/conftest.py` exists with shared fixtures
- [ ] `tests/test_scaffolding_int.py` has 3 integration tests, all passing
- [ ] `tests/test_scaffolding_e2e.py` has 1 E2E test, passing
- [ ] All 5 config/doc files exist at project root
- [ ] `.godotiq.example.json` is valid JSON with all config fields
- [ ] `pytest` reports 10+ tests collected, 0 failures
- [ ] **Test case resolution: 10/10 total (6 unit + 3 integration + 1 E2E)**

#### Operational Verification Procedures
1. `pytest tests/test_scaffolding_int.py -v` — 3 passed
2. `pytest tests/test_scaffolding_e2e.py -v` — 1 passed
3. `python -m json.tool .godotiq.example.json` — valid JSON
4. `cat .gitignore | head -5` — shows Python patterns
5. `pytest -v` — all tests pass, 10+ collected
6. `python -c "from src.server import server; print('OK')"` — prints OK

---

### Phase 4: Quality Assurance (Required) (Estimated commits: 1)
**Purpose**: Final verification of all acceptance criteria, code quality, and Design Doc compliance.

#### Tasks
- [ ] **T4.1**: Verify all Design Doc acceptance criteria achieved
  - [ ] AC-1: Directory structure matches specification exactly (INT-1 passes)
  - [ ] AC-2: pyproject.toml configuration correct (INT-2 passes, install works)
  - [ ] AC-3: MCP server entry point with godotiq_ping (INT-3 passes)
  - [ ] AC-4: Parser placeholders with dataclasses (unit test passes)
  - [ ] AC-5: FileCache class with all 5 methods (implementation review)
  - [ ] AC-6: Configuration loader with defaults (unit tests pass)
  - [ ] AC-7: Full install-test-import cycle (E2E-1 passes)
  - [ ] AC-8: All configuration files present (INT-1 passes)

- [ ] **T4.2**: Code quality verification
  - [ ] Type hints on all functions (manual review or mypy)
  - [ ] Docstrings on all public functions and classes
  - [ ] No business logic in parser placeholders
  - [ ] Only `mcp` and `pytest`/`pytest-asyncio` as dependencies
  - [ ] All code in English

- [ ] **T4.3**: Full test suite execution and verification
  - [ ] `pip install -e ".[dev]"` — exit code 0
  - [ ] `pytest -v` — ALL tests pass, 0 failures, 0 errors
  - [ ] `python -c "from src.server import server; print('OK')"` — prints OK
  - [ ] Test count >= 10 (6 unit + 3 integration + 1 E2E)

#### Phase Completion Criteria
- [ ] All 8 acceptance criteria verified and passing
- [ ] All tests green (0 failures, 0 errors, 0 skipped)
- [ ] Code quality standards met (type hints, docstrings, English)
- [ ] No extraneous dependencies
- [ ] **Unresolved tests: 0 (all 10/10 resolved)**

#### Operational Verification Procedures
1. `pip install -e ".[dev]"` — exit code 0
2. `pytest -v --tb=short` — all pass, 10+ tests
3. `python -c "from src.server import server; print('OK')"` — OK
4. `grep -r "def " src/ | grep -v "__" | head -20` — spot check type hints
5. Manual review: each AC checked against Design Doc specification

---

## Acceptance Criteria to Test Traceability

| AC | Unit Tests | Integration Tests | E2E Tests |
|----|-----------|-------------------|-----------|
| AC-1: Project Structure | — | INT-1 (1 item) | — |
| AC-2: pyproject.toml | — | INT-2 (1 item) | E2E-1 |
| AC-3: MCP Server | test_server_instance, test_ping_registered, test_ping_returns (3 items) | INT-2, INT-3 (2 items) | E2E-1 |
| AC-4: Parser Placeholders | test_parser_stubs_raise (1 item) | — | — |
| AC-5: Cache System | — (recommend adding in T3.1) | — | — |
| AC-6: Config Loader | test_config_defaults, test_config_loads_json (2 items) | — | — |
| AC-7: Tests Pass | — | — | E2E-1 (1 item) |
| AC-8: Config Files | — | INT-1 (1 item) | — |

**Total test coverage**: 6 unit + 3 integration + 1 E2E = **10 tests across all 8 ACs**

## Test Resolution Progress by Phase

| Phase | Unit Tests | Integration Tests | E2E Tests | Total Resolved |
|-------|-----------|-------------------|-----------|----------------|
| Phase 0 | 0/6 (Red) | — | — | 0/10 |
| Phase 1 | 0/6 (Red) | — | — | 0/10 |
| Phase 2 | 6/6 (Green) | — | — | 6/10 |
| Phase 3 | 6/6 | 3/3 (Green) | 1/1 (Green) | 10/10 |
| Phase 4 | 6/6 | 3/3 | 1/1 | **10/10 (all resolved)** |

## Completion Criteria

- [ ] All phases completed (Phase 0 through Phase 4)
- [ ] Each phase's operational verification procedures executed
- [ ] All 8 Design Doc acceptance criteria satisfied
- [ ] All tests pass (10/10 resolved, 0 failures)
- [ ] `pip install -e ".[dev]"` succeeds
- [ ] `pytest` — ALL green
- [ ] `python -c "from src.server import server; print('OK')"` — works
- [ ] Code quality verified (type hints, docstrings, English, no business logic in parsers)
- [ ] User review approval obtained

## Progress Tracking

### Phase 0
- Start:
- Complete:
- Notes:

### Phase 1
- Start:
- Complete:
- Notes:

### Phase 2
- Start:
- Complete:
- Notes:

### Phase 3
- Start:
- Complete:
- Notes:

### Phase 4
- Start:
- Complete:
- Notes:

## Notes

- **Implementation order within Phase 2**: Tasks T2.1-T2.4 are independent of each other and can be implemented in any order or in parallel. However, each should be followed by running `pytest tests/test_server.py` to verify the corresponding unit tests go Green.
- **AC-5 test gap**: The test skeletons note that FileCache is UNIT_LEVEL and was filtered from integration tests. Consider adding a small unit test for FileCache (e.g., put/get/is_stale/invalidate/clear cycle) during T3.1 or as part of T2.3. This is optional but recommended.
- **MCP SDK API verification**: Before implementing T2.1, check the actual MCP Python SDK API for `Server`, `@server.tool()`, and `stdio_server` patterns. The SDK may use `@server.call_tool()` or similar — confirm the exact decorator/method names.
- **pyproject.toml package discovery**: With hatchling and the `src/` layout, ensure `[tool.hatch.build.targets.wheel]` is configured correctly so that `from src.server import server` works after editable install. This is the highest-risk configuration item.
