/app-it-windows

name: app-it-windows
description: >-
  Create Windows beta desktop launchers for local web projects: WPF + WebView2
  .exe, Start Menu shortcut, .ico, warm server, quit cleanup. Use when the user
  asks for app-it-windows, a Windows app, .exe launcher, Start Menu shortcut,
  Windows package, or desktop icon. CI-guarded but untested on Windows hardware;
  never claim runtime success without a Windows maintainer.

app-it-windows - Make a project launchable on Windows (beta)

**Windows beta: scaffolded, untested on real hardware, maintainer wanted.**

The macOS `app-it` lane is proven. This Windows sibling mirrors the contract with Windows primitives, but every runtime behavior that needs a real Windows desktop must be marked deferred: `this needs a Windows maintainer - see docs/WINDOWS.md`.

Non-Negotiables

1. Run `templates/inspect.ps1` first and read the output before editing. 2. Trust disk over docs. Verify project type, scripts, ports, and desktop signals from files. 3. Build everything a Mac or CI can build; never claim Windows runtime behavior works unless it was verified on real Windows hardware. 4. Prefer the WPF + WebView2 host. Edge `--app=` is a fallback, not the default. 5. Keep Windows visibly beta in every report and user-facing summary. 6. Copy shipped templates and customize through `scripts\app-it.config.json`. Do not re-derive launcher patterns. 7. Verify build/lint/config checks, then list hardware-only checks as deferred.

Reference Map

Open only what the inspection or chosen path needs:

• `references/maintainer-contract.md` - what a Mac can produce, what must be

deferred, and the exact Windows-maintainer phrase.

• `references/inspection-and-strategies.md` - project inspection, toolchain

probes, strategy tree, W-Native, W-Edge, W-Static, W-Multi, B, and D.

• `references/generated-files.md` - template roster, allowed target files,

config JSON, package scripts, and Start Menu destination.

• `references/wrapper-host.md` - WebView2 host, lifecycle, Job Object ownership,

single-instance behavior, and wrapper argument contract.

• `references/verification.md` - buildable checks, Windows-only checks, and

deferred rows.

• `references/report-template.md` - exact beta report format.

Templates

Templates live next to this file in `templates/`. Copy them into the target project and keep their contracts intact:

templates/
  wrapper-windows/
  desktop-build.ps1
  desktop-install.ps1
  desktop-quit.ps1
  inspect.ps1
  run-template.ps1
  run-template-edge.ps1
  desktop-icons.ps1
  placeholder-icon-gen.ps1
  PSScriptAnalyzerSettings.psd1
  app-it.config.example.json

The comments inside templates encode Windows traps: PATH augmentation, WebView2/.NET prerequisites, free-port probing, Job Object ownership, Start Menu shortcuts, SmartScreen, and icon-cache behavior. Read the matching reference before changing launcher internals.

Workflow

1. Inspect

Run the bundled probe from the target project root:

pwsh -File path\to\plugins\app-it-windows\skills\app-it-windows\templates\inspect.ps1

Read `references/inspection-and-strategies.md` before deciding project shape, ports, existing desktop tooling, names, icons, or strategy.

2. Decide

For each user-facing app:

Existing Electron/Tauri/NW.js Windows target?
  yes -> Strategy B
  no  -> native desktop requirement beyond web shell?
           yes -> Strategy D
           no  -> .NET 8 buildable and WebView2 expected?
                    no  -> W-Edge fallback
                    yes -> static built bundle, no server?
                             yes -> W-Static
                             no  -> cohabiting frontend + backend?
                                      yes -> W-Multi
                                      no  -> W-Native (default)

WebView2 is Chromium, so File System Access and other Chromium APIs are reasons to prefer the WPF host, not reasons for a polyfill.

3. Build

Touch as little project surface as possible. Copy the selected templates, write `scripts\app-it.config.json`, add `desktop:*` package scripts, and generate the `.ico`/published output when tooling is present.

Read `references/generated-files.md` before editing scripts/config/docs, and `references/wrapper-host.md` before changing the host or PowerShell lifecycle.

4. Verify

On macOS, only claim buildable evidence: .NET publish when available, PowerShell lint when available, manifest/config parse, and placeholder icon round-trip in Windows CI. Everything involving a real window, Taskbar identity, tray Quit, Start Menu icon cache, SmartScreen, DPI, or Job Object tree reaping stays deferred with the maintainer phrase.

Read `references/verification.md` before reporting results.

5. Report

Use `references/report-template.md` inline and in `docs\desktop-launcher.app-it-report.md`. Keep beta wording visible, separate build/lint evidence from runtime unknowns, and append decision history.

Stage files only when the local convention or user request asks for it. Do not commit unless asked.

Quick Defaults

• Install destination:

`%APPDATA%\Microsoft\Windows\Start Menu\Programs\app-it\`.

• Runtime state:

`%LOCALAPPDATA%\app-it\<slug>\`.

• Bundle ID/key prefix: `com.user.<slug>`.
• Default strategy: W-Native when .NET 8 can build and WebView2 is expected.
• Fallback: W-Edge only when host prerequisites are unavailable.
• Icon sizes: `16, 32, 48, 64, 128, 256`.
• First-run signing stance: unsigned; SmartScreen click-through documented.

Stop Signs

Stop and mark deferred or blocked when only Windows hardware can decide, when the required build toolchain is missing and no fallback fits, when a port cannot be made env-driven, when a template needed for the selected strategy is absent, or when the requested claim would imply real Windows runtime verification that has not happened.