universal-linux-port

name	universal-linux-port
description	Port, reconstruct, modernize, or behaviorally reimplement Windows, macOS, and legacy applications as high-quality Linux applications. Use for executable or installed-application analysis, source recovery, platform adaptation, Linux rewrites, Electron or .NET migration, native reverse engineering, performance modernization, GUI reconstruction, and creation of applications that humans operate through a GUI while AI agents operate through documented MCP or CLI surfaces under the HAI-App contract.
license	Apache-2.0
compatibility	Linux-focused. Python 3.11+ runs the bundled validators and reference example. Optional external tools such as Ghidra, rev.ng, Wine, Frida, Qiling, DiE, Syft, compilers, GUI toolkits, and screenshot utilities may be selected by the agent as appropriate.
metadata	{"author":"vimalinx","version":"0.1.2","hai-app-contract":"0.1"}

Universal Linux Port

Produce the best Linux implementation of the supplied application while leaving its established human GUI unchanged by default. Do not mechanically translate its internal implementation when another approach yields a cleaner, faster, safer, or more maintainable result. A rewrite, toolkit change, performance modernization, or AI-native extension does not authorize any Agent-specific control, review, approval, or diagnostic surface inside the original GUI.

You own the engineering judgment. Select tools, investigation depth, component boundaries, migration strategy, implementation language, architecture, and validation method from the evidence and the user's goals. This skill deliberately does not prescribe a fixed analysis pipeline.

Non-negotiable outcome

The final application must:

1. provide a usable human surface, normally a GUI;
2. keep the original GUI, visual identity, information architecture, spatial layout, interaction patterns, terminology, shortcuts, density, and primary workflows unchanged unless the user explicitly authorizes a scoped redesign;
3. expose the same domain core to AI through documented MCP or CLI bindings that remain out of band and add no Agent-specific menus, buttons, panels, badges, status indicators, dialogs, notifications, or review controls to the human GUI;
4. keep Agent control, review, approval, diagnostics, screenshots, accessibility exports, receipts, and audit data in the Agent host, CLI, headless artifacts, or an optional separate companion that never auto-opens;
5. conform to HAI-App 0.1, including interfaceContinuity and surfaceSeparation for GUI work;
6. provide stable semantic resources, actions, receipts, and review evidence instead of requiring pixel-only automation;
7. provide an external AI-review path including semantic snapshots and, when practical, screenshots or accessibility captures;
8. make Agent adapters on-demand or host-managed so ordinary GUI use pays no meaningful Agent-integration startup or idle cost;
9. include measured performance results and document material regressions;
10. preserve user data ownership and obey applicable license, authorization, privacy, and security constraints.

Run the conformance validator before declaring completion:

python scripts/validate_hai_app.py /path/to/project/hai-app.yaml --strict

Operating principles

• Treat the original application as a behavioral oracle when it can be run lawfully and safely.
• Prefer useful behavior and user workflows over irrelevant implementation fidelity.
• Do not assume reverse engineering is necessary.
• Do not assume source recovery is preferable to reimplementation.
• Do not assume the original language, toolkit, process model, or storage format should be preserved internally. Preserve the user-facing GUI and interaction contract by default.
• Reuse high-quality portable components when that reduces risk and preserves performance.
• Capture an original-interface baseline before GUI work when the source application can be run. Treat missing evidence as a reason for conservative preservation, not creative freedom.
• Treat an existing human GUI as a sealed surface. Do not move controls, restyle the product, alter density, rename concepts, change shortcuts, or add any Agent-specific visible element unless the user explicitly requested and scoped it.
• Put MCP, CLI, review, approvals, diagnostics, screenshots, accessibility exports, and audit records outside the human GUI. A separate companion inspector is allowed only as an optional external program that stays closed during ordinary use.
• Prefer stdio, Unix sockets, in-process bindings, or other local on-demand transports. Do not start persistent network listeners, screenshot loops, or Agent daemons with the human GUI by default.
• Any necessary GUI deviation must be minimal, justified by a platform/accessibility/security/legal/bug constraint or explicit user request, recorded in interfaceContinuity, and supported by comparison evidence.
• Keep GUI, CLI, MCP, and other surfaces as adapters over one domain core. Do not route the GUI through MCP.
• Keep semantic control traffic separate from bulk data. Use resource handles, files, file descriptors, shared memory, streams, or GPU-native handles rather than embedding large binary payloads in JSON.
• Expose user intent as capabilities. Do not expose button clicks, dialog steps, coordinates, or DOM selectors as the canonical API.
• Make mutable resources revisioned. Reject stale writes rather than silently overwriting concurrent human changes.
• Emit structured receipts for meaningful changes and make undo or compensating actions explicit when supported.
• Give the agent freedom in analysis and implementation; enforce correctness at the output contract and tests.

Suggested working style, not a mandatory pipeline

Use the least expensive evidence that can answer the current engineering question. An agent may inspect packaging, source fragments, imports, runtime behavior, accessibility trees, traces, screenshots, data files, protocols, or decompiled code in any order. Form hypotheses only when useful, revise them when evidence changes, and implement meaningful vertical slices early enough to test against the original behavior.

The scripts in scripts/ are instruments, not a controller:

• toolbox_status.py inventories available analysis and build tools.
• inspect_artifact.py records deterministic static facts without executing the target.
• validate_hai_app.py validates the mandatory output contract.
• test_gui_continuity.py verifies that strict validation rejects unauthorized GUI redesign, embedded Agent chrome, human-GUI review surfaces, missing separation declarations, and incomplete parity evidence.
• check_mcp_surface.py checks that declared MCP capability/resource bindings exist without importing the SDK.
• compare_benchmarks.py compares baseline and rewritten performance.
• capture_window.py captures a desktop review image where supported.
• build_review_bundle.py assembles machine-readable and human-readable review evidence.
• scaffold_hai_app.py creates a small conformant application skeleton.
• run_closed_loop.py verifies this skill and its bundled reference application end to end.

Read references only when relevant

• Read references/hai-app-contract.md before designing the final application contract or adapters.
• Read references/engineering-playbook.md when choosing between porting, recovery, compatibility, and reimplementation.
• Read references/tool-catalog.md when selecting inspection, reverse-engineering, tracing, testing, or packaging tools.
• Read references/language-and-performance.md before choosing the rewritten language, GUI stack, process model, or optimization plan.
• Read references/gui-fidelity.md before reproducing, adapting, or testing an existing GUI.
• Read references/human-agent-surfaces.md when implementing GUI, CLI, MCP, resources, context, or transactions.
• Read references/review-and-evidence.md before designing screenshots, semantic snapshots, audit bundles, or AI review flows.
• Read references/linux-integration.md before packaging or integrating with the Linux desktop.
• Read references/legal-and-safety.md when authorization, unknown binaries, proprietary protocols, DRM, drivers, or sensitive data may be involved.

Completion gate

Do not claim the port is complete merely because it launches. Completion requires:

• the primary human workflows are operable through the GUI;
• the original GUI contract is preserved, including the absence of Agent-specific chrome, or every deviation is explicitly authorized or narrowly justified and evidenced;
• surfaceSeparation.mode is out-of-band for the ordinary migration case, with no human-GUI additions and no Agent control/review/approval location inside the GUI;
• GUI parity comparisons are complete rather than pending or failed;
• core AI workflows are discoverable and operable through MCP or CLI;
• capabilities shared by human and Agent surfaces call the same domain implementation; Agent-only review capabilities remain external;
• the declared HAI-App profiles validate;
• review evidence can be regenerated;
• behavioral and data-compatibility tests cover the important workflows;
• performance measurements exist for the dimensions that matter to this application;
• remaining compatibility wrappers, missing capabilities, unverified assumptions, and accepted regressions are listed explicitly.

The bundled examples/hai-notes application is a small executable reference showing the intended architecture. It is an example, not a required implementation language or UI toolkit.