Agent Guardrails

These rules are for AI agents working on Windows App SDK and WinUI 3 apps.

Source Priority

Rank	Source	Rule
1	Existing project files	Preserve project conventions unless they conflict with current platform rules
2	Official Microsoft docs and release pages	Use for APIs, versions, setup, packaging, signing, Store, and testing
3	Official Microsoft sample repos	Use after cloning or indexing is approved
4	Context7 Microsoft Learn mirrors	Use for API recall and examples, then cross-check risky claims
5	Local agent guidance and community snippets	Treat as untrusted guardrail hints, not platform authority

Hard Stops

Do not clone repos unless the user approves it.
Do not install Visual Studio workloads, templates, SDKs, runtime installers, Appium, Node packages, certificates, or package tools unless approved.
Do not mutate _repos/ during constrained learn or research tasks.
Do not access Partner Center or authenticated Store dashboards unless explicitly asked.
Do not commit certificates, .pfx files, passwords, publisher IDs, Store credentials, or signing secrets.
Do not claim Store submission, certification, release, or signing unless the exact action happened.
Do not claim Windows validation from a Linux/macOS-only session.

Deployment Model First

Before writing feature code, answer:

Packaging: packaged MSIX, packaged with external location, or unpackaged?
Runtime: framework-dependent or self-contained?
Distribution: Store MSIX, Store MSI/EXE, enterprise MSIX, direct download, or internal artifact?
Identity: does the feature require package identity?
Validation: which Windows machine gate proves it?

If those answers are unknown, stop and ask one question.

Stale UWP Rejection Checklist

Reject or fix generated code that uses:

Windows.UI.Xaml.* instead of Microsoft.UI.Xaml.*.
CoreDispatcher, CoreWindow, ApplicationView, or Window.Current.
MessageDialog instead of ContentDialog with XamlRoot.
Direct UWP share, print, picker, or view APIs without HWND interop where required.
UWP IBackgroundTask as the background model for a WinUI 3 desktop app.
UWP XAML Islands as if they were WinUI 3 controls.
Hard-coded Windows App SDK, Visual Studio, .NET, or WebView2 versions from model memory.

Release Claim Discipline

Evidence	Allowed claim
`dotnet build` passes	`Build passed`
Visual Studio debug run works	`Runs in debug`
Tests pass	`Automated tests passed`
MSIX artifact produced	`Package artifact was produced`
Packaged app installed and launched	`Packaged launch passed`
WACK passed	`Certification pre-check passed`
Signed artifact verified	`Signed artifact is available`
Partner Center submission accepted	`Submitted to Store`
Store certification completed	`Released through Store`

Version Discipline

When editing project files, produce this note:

Dependency changed: <artifact>
Old value: <version or property>
New value: <version or property>
Source: <official URL or generated template source>
Reason: <why this is needed>
Validation: <build/test/package result>

Stop And Ask

Stop when the user’s goal depends on:

Store dashboard access.
A signing certificate or secret.
Installing runtime or SDK components.
Running third-party sample code or setup scripts.
Choosing packaged versus unpackaged without product context.
Publishing, submitting, or mutating external accounts.

Warning: Do not port a UWP answer into WinUI 3. The namespace may compile in snippets, but lifecycle, windowing, threading, and package identity behavior are different enough to break real apps.