fieldworks-winapp

name	fieldworks-winapp
description	Control and document the FieldWorks desktop application with WinForms MCP or WinApp MCP. Use this skill whenever a task requires launching FieldWorks, restoring or opening a FieldWorks project, walking WinForms UI flows, collecting manual screenshots, reproducing UI bugs, or verifying a fix inside the live FLEx application.
license	MIT
compatibility	Requires a Windows/x64 FieldWorks workspace. Prefer WinForms MCP for hidden-desktop UIA2 automation when available; use WinApp MCP as the UIA3 fallback and for visible desktop/window diagnostics.
metadata	{"author":"FieldWorks team","version":"1.0"}

FieldWorks WinForms/WinApp Automation

Use this skill to launch, inspect, navigate, and capture evidence from the FieldWorks Language Explorer desktop app through WinForms MCP or WinApp MCP. Keep the workflow grounded in the live UI tree: inspect first, interact second, capture evidence after the target state is visible.

This skill is intentionally organized as a small index plus route-specific navigation files. Read only the route files needed for the task.

Core Rules

• Prefer WinForms MCP UIA2 tools for fresh FieldWorks runtime automation because FieldWorks is currently WinForms and the workspace config runs WinForms MCP in hidden-desktop mode.
• Use WinApp MCP UIA3 tools when WinForms MCP is unavailable, when a task needs visible desktop/window diagnostics, or when UIA2 cannot see the target surface.
• Prefer UI Automation IDs and names over coordinates. Use coordinates only after snapshots and element searches fail.
• Always inspect the current tree with winforms_get_element_tree, mcp_winapp_get_snapshot, or targeted element search before assuming a dialog structure.
• Treat FieldWorks UI automation as stateful. After opening menus, dialogs, or popups, re-query the snapshot or element list.
• Capture screenshots into a task-specific evidence folder before closing the app or dialog.
• Close evidence-only dialogs with Cancel or Escape unless the user asked to change project data.
• Do not globally register COM or add registry hacks. FieldWorks uses reg-free COM from the build output.

MCP Selection

• Default to WinForms MCP for launch/test/screenshot flows. Use winforms_launch_app, winforms_wait_for_element, winforms_get_element_tree, winforms_find_element, winforms_click_element, winforms_type_text, winforms_set_value, winforms_select_item, winforms_click_menu_item, and winforms_take_screenshot.
• Use WinForms MCP headless-safe operations only. Avoid winforms_send_keys, drag/drop, and double-clicks on hidden-desktop processes.
• Use WinApp MCP for visible desktop/window diagnostics, UIA3 comparison, fallback screenshots, or controls that WinForms MCP cannot operate.
• Read references/mcp-selection.md before changing a route from one MCP driver to the other.

How This Skill Is Organized

• SKILL.md: trigger metadata, global safety rules, and route index.
• navigation/*.md: one goal-oriented navigation path per file. These are the FieldWorks equivalent of Page Objects: each file owns the menu path, automation IDs, verification cues, and safe exit path for one user-facing destination or workflow.
• references/how-to-update.md: rules for adding or revising navigation paths.
• references/mcp-selection.md: rules for choosing WinForms MCP or WinApp MCP.
• references/research.md: source-backed rationale for this structure.

When a task names a destination, read the matching navigation file. When a task discovers a better route or a fragile selector, read and update references/how-to-update.md before changing the route file.

Navigation Path Index

• Launch or attach to FieldWorks: navigation/launch-or-attach.md
• Confirm or restore a sample project: navigation/project-loading.md
• Writing System Properties > Font tab: navigation/writing-system-font-options.md
• Styles dialog > Font tab: navigation/styles-font-tab.md
• Manual screenshot evidence: navigation/screenshot-evidence.md
• MCP driver selection: references/mcp-selection.md

Screenshot Evidence

For evidence tasks, read navigation/screenshot-evidence.md. Prefer committed OpenSpec evidence only when the screenshot should be part of review history; otherwise use Output/ManualEvidence/<ticket-or-change-id>/.

For target detection, descriptive filenames, inline review, annotation, and retake quality gates, also use ../smart-screenshot-capture/SKILL.md.

How To Update This Skill

Keep improving this skill as you explore FieldWorks and discover the most efficient ways to do things. When you find a reliable automation ID, keyboard route, menu path, restore flow, modal-dialog workaround, or screenshot trick, update the relevant route file in the same change set or propose the update to the user. Prefer short, verified notes over broad guesses.

Use references/how-to-update.md for the exact update checklist. In short:

• add one navigation file per distinct destination or workflow;
• keep each file task-focused and action-oriented;
• record stable automation IDs, entry state, verification cues, and exit path;
• move shared rules back to this index only when at least two route files need the same guidance;
• remove or revise stale routes when WinApp snapshots prove they changed.