isphere-ai-bridge/docs/superpowers/plans/2026-07-05-isphere-win-helper-first-phase.md

ISphereWinHelper First Phase Implementation Plan

For agentic workers: REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (- [x]) syntax for tracking.

Goal: Build the first C# read-only Windows helper for version, self_check, scan_windows, and dump_uia using the agreed Go/C# JSON boundary.

Architecture: The helper is a one-shot CLI process. Go will later send one JSON request on stdin and read one JSON response from stdout. This phase implements only read-only desktop/UIA probing and a PowerShell build script.

Tech Stack: C# .NET Framework, csc.exe, Windows UI Automation, Python unittest wrapper tests.

---

Task 1: Contract and build test

Files:

• Create: tests/test_win_helper.py

• Create: scripts/build-win-helper.ps1

• Create: native/ISphereWinHelper/Program.cs

• Create: native/ISphereWinHelper/HelperProtocol.cs

• Create: native/ISphereWinHelper/WindowScanner.cs

• Create: native/ISphereWinHelper/UiaDumper.cs

• Write a Python unittest that expects scripts/build-win-helper.ps1 to build runs/win-helper/ISphereWinHelper.exe.

• Run the test and verify it fails because the build script/helper does not exist yet.

• Add the minimal C# helper and build script.

• Run the build test and verify it passes.

Task 2: JSON operation tests

Files:

• Modify: tests/test_win_helper.py

• Modify: native/ISphereWinHelper/*.cs

• Add tests for version, self_check, scan_windows, invalid JSON, and unsupported op.

• Run tests and verify they fail for missing behavior.

• Implement JSON request/response handling and the four first-phase operations.

• Run tests and verify they pass.

Task 3: Verification

Files:

• No new production files.

• Run python -m unittest discover -s tests -p test_win_helper.py -v.

• Run python -m compileall -q tests.

• Run powershell -NoProfile -ExecutionPolicy Bypass -File scripts\build-win-helper.ps1.

• Run direct version, scan_windows, and dedicated WinForms dump_uia JSON requests against the helper.