FaceBreathWin

Imported from NW-Lab/face_breath (Win/FaceBreathWin/AGENTS.md). Install upstream with npx skills add NW-Lab/face_breath --skill FaceBreathWin. Copyright stays with the author.

Copilot Agent Instructions -- WinUI 3 / WinAppSDK

Project Overview

This is a WinUI 3 desktop application built on the Windows App SDK. It uses MSIX packaging and supports x86, x64, and ARM64 architectures.

Source of truth for versions & names: Always read the project .csproj to determine the current TargetFramework, RuntimeIdentifiers, Platforms, RootNamespace, and Microsoft.WindowsAppSDK package version. Never hard-code project names or version numbers in instruction files.

Throughout this document and the instruction files, <ProjectName> is a placeholder -- replace it with the actual project folder/assembly name (derived from the .csproj filename).

Default TFM: Templates ship with net10.0 by default. Pass --dotnet-version <tfm> (for example net10.0) when running dotnet new ... or edit <TargetFramework> inside the generated .csproj before the first build if you need a newer framework. Keep <RuntimeIdentifiers> synchronized with the framework you pick.

Instruction Files Index

All detailed agent instructions are organized under .github/instructions/:

Core Agent Workflow

Every time you work on this codebase, follow this checklist:

Before Writing Code

1. Review the original goal -- Re-read the user's request and confirm you understand the intent.
2. Check existing code -- Search for related implementations to avoid duplication (DRY).
3. Find the right API -- If the task involves a platform capability (AI, UI controls, file access, notifications, windowing, widgets, sensors, etc.), first check the Windows APIs catalog and then look up the correct API in the WinUI 3 API Reference before writing code.
4. Plan the approach -- Consider SOLID principles and identify which classes/interfaces are involved.

While Writing Code

Agent Rule -- MANDATORY: Steps 5-8 are not passive references. You must actually open and read the linked instruction file before writing code that falls within its scope. Do not skip this -- these files contain rules, anti-patterns, and checklists that must be applied.

5. Apply Design Principles -- Read design-principles before adding/refactoring classes or logic. Apply DRY, KISS, SOLID, YAGNI.
6. Follow Fundamentals -- Read the applicable instruction files based on what you're changing:
   • Adding or changing UI controls / XAML? -> Read accessibility (AutomationProperties, keyboard nav, contrast) AND performance (x:Bind, x:Load, virtualization).
   • Adding or changing user-facing strings (labels, messages, tooltips)? -> Read globalization (.resw files, x:Uid, ResourceLoader).
   • Handling secrets, user input, HTTP, or permissions? -> Read security (no hard-coded secrets, input validation, least privilege).
   • Working on data binding, collections, async/IO, or layout? -> Read performance (x:Bind, virtualization, async patterns).
7. Respect Code Quality Rules -- Read code-quality before writing code. Follow all CA*/SA*/IDE* analyzer rules and naming conventions.
8. Follow WinUI Patterns -- Read winui-best-practices for MVVM, x:Bind, community toolkit, and API verification.

After Writing Code

9. Remove unused code -- Delete unused using statements, dead code, commented-out blocks.
10. Write unit tests -- Every new public method/class needs tests. Read testing for framework setup, naming conventions (MethodName_Scenario_ExpectedResult), AAA pattern, and dotnet test commands.
11. Build the project -- Detect the platform first ($Platform = $env:PROCESSOR_ARCHITECTURE), then run dotnet build -c Debug -p:Platform=$Platform from the project folder and fix all warnings/errors. If build errors occur, follow the Troubleshooting Build Errors workflow below.
12. Run tests -- Run tests related to the change using --filter (see testing). Run the full suite only when the change is cross-cutting.
13. Register the MSIX package -- See Build, Run & Deploy below.
14. Re-review against original goal -- Confirm the implementation matches the user's request.

Troubleshooting Build Errors

Agent Rule -- MANDATORY: When a build fails due to an unknown type, missing namespace, unresolved API, or similar definition error, follow this escalation order. Do NOT jump straight to reading .winmd files or using ildasm/decompilers -- always try web search first.

Step 1 -- Web Search (ALWAYS try first):

1. Open and read windows-apis.instructions.md -- it contains the API namespace catalog and lookup guidance.
2. Translate the unknown type/namespace into search keywords (e.g., ImageDescription -> "WinAppSDK ImageDescription API").
3. Use web_search or web_fetch to search the WinAppSDK API Reference and the Platform SDK API Reference for the correct namespace, class name, and method signatures.
4. Check the release notes to verify the API is available in the project's SDK version (read from .csproj).

Step 2 -- Sample Repos: If web search finds the API but usage is unclear, search the sample repositories listed in windows-apis.instructions.md for working examples.

Step 3 -- WinMD / Decompiler (last resort only): Only if Steps 1-2 fail to resolve the issue, then inspect .winmd metadata files or use decompilation tools to discover the exact type definitions. This is a fallback, not the default approach.

Build, Run & Deploy

This is an MSIX-packaged WinUI 3 app. You must pass both -c (Configuration) and -p:Platform= to every dotnet command.

Dotnet CLI Workflow

• Prefer dotnet new for scaffolding projects and items so namespaces, GUIDs, and resource wiring stay correct.
• Common commands:
  • dotnet new winui -n MyApp
  • dotnet new winui-page -n SettingsPage --project .\MyApp\MyApp.csproj
  • dotnet new winui-usercontrol -n ProfileCard --project .\MyApp\MyApp.csproj
• Discover available scaffolds with dotnet new winui --list (shows supported parameters such as --dotnet-version).
• Need a newer TFM? Supply --dotnet-version net10.0 during scaffold or edit <TargetFramework> afterward before the first build.

Prerequisites

• Developer Mode must be enabled on Windows. Verify with:

  # Check developer mode
  Get-WindowsDeveloperLicense
  # If not enabled: Settings -> System -> For developers -> Developer Mode -> On

Detect Platform

Always detect the machine's architecture first -- never hardcode a platform value. Run this once at the start of every build/test session:

# Detect the current machine's CPU architecture (returns x64, ARM64, or x86)
$Platform = $env:PROCESSOR_ARCHITECTURE

Use $Platform in all subsequent dotnet commands.

Build

# Run from the project folder containing the .csproj
cd <ProjectName>

# Detect platform
$Platform = $env:PROCESSOR_ARCHITECTURE

# Debug build (matches current machine)
dotnet build -c Debug -p:Platform=$Platform

# Release build
dotnet build -c Release -p:Platform=$Platform

Register & Run the MSIX Package (Sideload)

After building, register the app package so Windows can launch it:

$Platform = $env:PROCESSOR_ARCHITECTURE
$Rid = $Platform.ToLower()   # e.g. arm64, x64, x86

# Register the built MSIX package from the build output
# Read <TargetFramework> from the project .csproj to build the correct path.
Add-AppxPackage -Register ".\<ProjectName>\bin\$Platform\Debug\<TargetFramework>\win-$Rid\AppxManifest.xml"

Note: Replace <TargetFramework> with the actual value from .csproj (e.g., net10.0-windows10.0.26100.0).

Run from the CLI

• Quick smoke tests: dotnet run -c Debug -p:Platform=$Platform from the project folder.
• Launch a packaged build: winapp run .\<ProjectName>\bin\$Platform\Debug\<TargetFramework>\<ProjectName>.exe after registering the MSIX output.
• If the launch fails because an old instance is still running, terminate it with taskkill /IM <ProjectName>.exe /F before re-running.

Run Tests

# Run from the test project folder
cd <ProjectName>.Tests
$Platform = $env:PROCESSOR_ARCHITECTURE
dotnet test -c Debug -p:Platform=$Platform

Key Rules (Always Enforced)

• Every change must build and pass tests -- Run dotnet build and dotnet test (see Build, Run & Deploy) before considering any task complete.
• Follow all instruction files -- The detailed rules in .github/instructions/ are authoritative. You must actually open and read them (not just acknowledge they exist) when working within their scope. See the trigger conditions in steps 5-8 above.
• Web search before decompilation -- When facing unknown types or build errors, always search the web / API docs first. Only use WinMD/ILDASM as a last resort (see Troubleshooting Build Errors).

Windows AI Prerequisites

When integrating Phi Silica, Windows Vision, or other Windows AI APIs (see windows-apis.instructions.md):

1. Manifest capabilities: Add the required capabilities (for example internetClient, machineLearning, systemManagement) to the app manifest before calling these APIs.
2. LAF token: Phi Silica endpoints need a Local API key. Acquire it via the Windows AI documentation, store it securely (never in source), and document the manual step in the PR.
3. MSBuild overrides: Some scenarios need temporary <WindowsAppSDKSelfContained> or package-version overrides. Capture the reasoning in the PR description and remove overrides once upstream fixes land.
4. Fallback path: If LAF or required hardware is unavailable, use the Windows Vision / AI APIs that do not require the token and describe the limitations in the instruction files or README so Copilot can pick the right approach.