-This repository hosts samples for the [Windows App SDK](https://github.com/microsoft/WindowsAppSDK). Samples for various features shipping in the Windows App SDK will be added to this repository. For more information about the Windows App SDK, visit the [Windows App SDK Documentation](https://docs.microsoft.com/windows/apps/windows-app-sdk/). To learn more about the Windows App SDK design or to contribute to the project, make feature proposals, or start discussions, visit the [Windows App SDK GitHub page](https://github.com/microsoft/WindowsAppSDK).
+
Windows App SDK samples
-## List of samples
This repository hosts samples for the [Windows App SDK](https://github.com/microsoft/WindowsAppSDK). Samples for various features shipping in the Windows App SDK will be added to this repository. For more information about the Windows App SDK, visit the [Windows App SDK documentation](https://docs.microsoft.com/windows/apps/windows-app-sdk/). To learn more about the Windows App SDK design or to contribute to the project, make feature proposals, or start discussions, visit the [Windows App SDK GitHub page](https://github.com/microsoft/WindowsAppSDK).
@@ -30,28 +33,33 @@ This repository hosts samples for the [Windows App SDK](https://github.com/micro
#### Data and Files
- [Resource Management](Samples/ResourceManagement): These samples demonstrates app resource management using the MRT Core APIs.
-#### Deployment
+### Deployment
- [Deployment Manager](Samples/DeploymentManager): This sample demonstrates how to initialize and access deployment information for the Windows App SDK runtime.
- [Installer](Samples/Installer): This sample demonstrates how to launch the Windows App SDK installer without a console window.
- [Unpackaged](Samples/Unpackaged): These samples demonstrate auto-initialization with the Windows App SDK package from non-MSIX (unpackaged) application.
-#### Dynamic Dependencies
+### Dynamic Dependencies
- [DirectX](DynamicDependenciesSample/DynamicDependencies): This sample demonstrates how to use the Dynamic Dependencies API to dynamically load the DirectX Runtime MSIX framework package.
-#### Graphics
+### Graphics
+- [Mica](Samples/Mica): These samples demonstrate how to use the Mica material in different apps and frameworks.
- [Text Rendering](Samples/TextRendering): This sample is a gallery of the DWriteCore APIs demonstrating text rendering.
-#### Notifications
+### Islands
+- [Islands](Samples/Islands): This sample shows how to add a WinAppSDK island with Xaml content to a Win32 app.
+
+### Notifications
- [Push Notifications](Samples/Notifications/Push): This is a sample app that showcases Push Notifications.
- [App Notifications](Samples/Notifications/App): This is a sample app that showcases App Notifications.
-#### Runtime Components
+### Runtime Components
- [Custom Controls](Samples/CustomControls): This sample shows how to author a Windows Runtime Component in C# with custom WinUI controls.
-#### User Interface and Input
+### User Interface and Input
+
- [Windowing](Samples/Windowing): This sample demonstrates how to manage app windows using the Windowing APIs.
-- [Windows Input and Composition Gallery](https://github.com/microsoft/WindowsCompositionSamples): This collection of samples showcases Microsoft.UI.Composition and Microsoft.UI.Input APIs.
-- [WinUI 3 Gallery](https://github.com/microsoft/WinUI-Gallery/): This is a sample app that showcases all of the WinUI 3 controls in action.
+- [Windows Composition, Input and SceneGraph](Samples/SceneGraph): This collection of samples showcases Microsoft.UI.Composition, Microsoft.UI.Input and SceneGraph APIs.
+- [WinUI 3 Gallery](https://github.com/microsoft/WinUI-Gallery): This is a sample app that showcases all of the WinUI 3 controls in action.
### Widgets
- [Widgets](Samples/Widgets): These samples demonstrate how to author Windows Widgets with the Windows App SDK.
@@ -64,38 +72,38 @@ Thes Windows App SDK samples have the following system requirements:
- [Visual Studio 2022](https://visualstudio.microsoft.com/downloads/) or Visual Studio 2019 version 16.9 or later, with the following workloads and components:
- - Universal Windows Platform development
+ - Windows application development
- .NET Desktop Development (needed even if you're only building C++ Win32 apps)
- Desktop development with C++ (needed even if you're only building .NET apps)
- Windows SDK version 2004 (build 19041) or later. This is installed with Visual Studio by default.
-- Building .NET C# samples with Windows App SDK 1.1 also requires one of the following .NET SDK versions or later:
- - 6.0.202
- - 6.0.104
- - 5.0.407
- - 5.0.213
-
Refer to the docs on [system requirements](https://docs.microsoft.com/windows/apps/windows-app-sdk/system-requirements) and [tools for Windows app development](https://docs.microsoft.com/windows/apps/windows-app-sdk/set-up-your-development-environment) for a detalied list of requirements for developing apps with the Windows App SDK.
-## Using the samples
+## 🚀 Using the samples
To use the samples with Git, clone the WindowsAppSDK-Samples repository by running `git clone https://github.com/microsoft/WindowsAppSDK-Samples.git` from a command prompt. You can then navigate to the directory of a sample and open the solution file in Visual Studio.
The easiest way to use these samples without Git is to download the ZIP file. Select *Download ZIP* from the download dropdown, unzip the entire archive and open the samples in Visual Studio.
-### Samples versioning
+## 📄 Samples versioning
The samples will be updated with GA releases of the Windows App SDK. The `main` branch includes the latest samples, which may also include experimental or preview features. Specific release branches are named `release/x.y` and contain samples that reference the corresponding GA version of the Windows App SDK. This repository currently includes the following release branches:
+- [release/experimental](https://github.com/microsoft/WindowsAppSDK-Samples/tree/release/experimental)
+- [release/1.8](https://github.com/microsoft/WindowsAppSDK-Samples/tree/release/1.8-stable)
+- [release/1.7](https://github.com/microsoft/WindowsAppSDK-Samples/tree/release/1.7-stable)
+- [release/1.6](https://github.com/microsoft/WindowsAppSDK-Samples/tree/release/1.6-stable)
+- [release/1.5](https://github.com/microsoft/WindowsAppSDK-Samples/tree/release/1.5-stable)
+- [release/1.1](https://github.com/microsoft/WindowsAppSDK-Samples/tree/release/1.1)
- [release/1.0](https://github.com/microsoft/WindowsAppSDK-Samples/tree/release/1.0)
- [release/0.8](https://github.com/microsoft/WindowsAppSDK-Samples/tree/release/0.8)
- [release/0.5](https://github.com/microsoft/WindowsAppSDK-Samples/tree/release/0.5)
-## Contributing
+## 🏆 Contributing
These samples are provided by feature teams and we welcome your input on issues and suggestions for new samples. We encourage you to [file a new issue](https://github.com/microsoft/WindowsAppSDK-Samples/issues/new) for any feedback or questions!
-Sample authors should follow the [samples guidelines](docs/samples-guidelines.md) to begin developing their samples. For WinUI-based Windows App SDK samples, use the [sample templates](Templates/README.md). The VSIX file is available for download in the Github releases page [here](https://github.com/microsoft/WindowsAppSDK-Samples/releases).
+Sample authors should follow the [samples guidelines](docs/samples-guidelines.md) to begin developing their samples. For WinUI-based Windows App SDK samples, use the [sample templates](Templates/README.md). The VSIX file is available for download in the GitHub releases page [here](https://github.com/microsoft/WindowsAppSDK-Samples/releases).
This project has adopted the [Microsoft Open Source Code of Conduct](https://opensource.microsoft.com/codeofconduct/). For more information, see the Code of Conduct FAQ or contact opencode@microsoft.com with any additional questions or comments.
From cb610366408f4c67ef910007a2074431e5b79fd2 Mon Sep 17 00:00:00 2001
From: Gordon Lam <73506701+yeelam-gordon@users.noreply.github.com>
Date: Mon, 12 Jan 2026 13:49:20 +0800
Subject: [PATCH 2/3] Add AI Contributor Guidelines and Prompts for GitHub
Copilot Integration (#583)
* Add comprehensive guidelines and prompts for GitHub Copilot integration
- Introduced a new instruction file for creating high-quality prompt files for GitHub Copilot, detailing frontmatter requirements, file naming conventions, body structure, and quality assurance.
- Created prompts for generating commit titles, pull request summaries, and issue fixes, ensuring adherence to WindowsAppSDK-Samples conventions.
- Developed a review prompt for GitHub issues, including scoring and generating implementation plans.
- Implemented a detailed review prompt for pull requests, outlining a structured review process with incremental review capabilities and smart filtering.
- Added an AI Contributor Guide for Windows App SDK Samples, covering build, run, verify processes, project structure, style enforcement, and copyright headers.
* fix(build): improve sample path validation in Get-Solutions function
* chore(vscode): add settings and tasks configuration for GitHub Copilot
* refactor(review): enhance incremental review detection and update workflow
* Update .github/prompts/create-pr-summary.prompt.md
Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
* Update AGENTS.md
Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
* Update .github/instructions/instructions.instructions.md
Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
---------
Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
---
.github/copilot-instructions.md | 83 +-
.github/instructions/agents.instructions.md | 791 ++++++++++++++++++
.../azure-devops-pipelines.instructions.md | 228 +++++
.github/instructions/csharp.instructions.md | 79 ++
.../instructions/instructions.instructions.md | 256 ++++++
.../instructions/powershell.instructions.md | 394 +++++++++
.github/instructions/prompt.instructions.md | 88 ++
.github/prompts/create-commit-title.prompt.md | 50 ++
.github/prompts/create-pr-summary.prompt.md | 25 +
.github/prompts/fix-issue.prompt.md | 68 ++
.github/prompts/review-issue.prompt.md | 160 ++++
.github/prompts/review-pr.prompt.md | 184 ++++
.gitignore | 3 -
.vscode/settings.json | 17 +
.vscode/tasks.json | 70 ++
AGENTS.md | 73 ++
build.ps1 | 31 +-
17 files changed, 2551 insertions(+), 49 deletions(-)
create mode 100644 .github/instructions/agents.instructions.md
create mode 100644 .github/instructions/azure-devops-pipelines.instructions.md
create mode 100644 .github/instructions/csharp.instructions.md
create mode 100644 .github/instructions/instructions.instructions.md
create mode 100644 .github/instructions/powershell.instructions.md
create mode 100644 .github/instructions/prompt.instructions.md
create mode 100644 .github/prompts/create-commit-title.prompt.md
create mode 100644 .github/prompts/create-pr-summary.prompt.md
create mode 100644 .github/prompts/fix-issue.prompt.md
create mode 100644 .github/prompts/review-issue.prompt.md
create mode 100644 .github/prompts/review-pr.prompt.md
create mode 100644 .vscode/settings.json
create mode 100644 .vscode/tasks.json
create mode 100644 AGENTS.md
diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md
index ec2bf49ba..a2346ef1e 100644
--- a/.github/copilot-instructions.md
+++ b/.github/copilot-instructions.md
@@ -1,44 +1,41 @@
-# GitHub Copilot Instructions (WindowsAppSDK-Samples)
-
-Read scripts first; improve their headers instead of duplicating detail here.
-
-## Build
-Use only `build.ps1` / `build.cmd`. Read `build.ps1` before invoking. It auto: detects platform, picks solutions (current dir > selected sample > all), initializes VS DevShell, restores via local nuget, emits `.binlog` per solution. Do NOT hand-roll msbuild/nuget restore logic.
-
-## Versions
-Run `UpdateVersions.ps1` only after reading it. Get the WinAppSDK version string from: https://www.nuget.org/packages/Microsoft.WindowsAppSdk/ (stable/preview/servicing) and pass as `-WinAppSDKVersion`.
-
-## Coding Guidelines
-- Small, focused diffs; no mass reformatting; ensure SOLID principles.
-- Preserve APIs, encoding, line endings, relative paths.
-- PowerShell: approved verbs; each new script has Synopsis/Description/Parameters/Examples header.
-- C#/C++: follow existing style; lean headers; forward declare where practical; keep samples illustrative.
-- Minimal necessary comments; avoid noise. Centralize user strings for localization.
-- Never log secrets or absolute external paths.
-
-## Language style rules
-- Always enforce repo analyzers: root `.editorconfig` plus any `stylecop.json`.
-- C# code follows StyleCop.Analyzers and Microsoft.CodeAnalysis.NetAnalyzers.
-- C++ code honors `.clang-format` plus `.clang-tidy` (modernize/cppcoreguidelines/readability).
-- Markdown files wrap at 80 characters and use ATX headers with fenced code blocks that include language tags.
-- YAML files indent two spaces and add comments for complex settings while keeping keys clear.
-- PowerShell scripts use Verb-Noun names and prefer single-quoted literals while documenting parameters and satisfying PSScriptAnalyzer.
-
-## PR Guidance
-- One intent per PR. Update script README/header if behavior changes.
-- Provide summary: what / why / validation.
-- Run a targeted build (e.g. `pwsh -File build.ps1 -Sample AppLifecycle`).
-- For version bumps: inspect at least one changed project file.
-- No new warnings/errors or large cosmetic churn.
-
-## Design Docs (Large / Cross-Sample)
-Before broad edits create `DESIGN-.md`:
-- Single sample: `Samples//DESIGN-.md`
-- Multi-sample/shared: repo root.
-Include: Problem, Goals/Non-Goals, Affected Areas, Approach, Risks, Validation Plan. Reference doc in PR.
-
-## When Unsure
-Draft a design doc or WIP PR summarizing assumptions—don't guess.
-
---
-Keep this file lean; source-of-truth for behavior lives in script headers.
\ No newline at end of file
+description: 'Windows App SDK Samples AI contributor guidance'
+---
+
+# Windows App SDK Samples – Copilot Instructions
+
+Concise guidance for AI contributions to Windows App SDK Samples. For complete details, see [AGENTS.md](../AGENTS.md).
+
+## Quick Reference
+
+- **Build**: `build.ps1` / `build.cmd` (supports `-Sample ` for targeted builds)
+- **Run**: Test on x64, x86, ARM64 in Debug and Release
+- **Verify**: Run WACK on Release builds
+- **Exit code 0 = success** – do not proceed if build fails
+
+## Key Rules
+
+- Samples should be **complete but simple** – demonstrate correct API usage
+- Follow **scenario-based design** – one scenario per API usage pattern
+- Support all platforms: x64, x86, ARM64 (Debug and Release)
+- Minimum OS: Windows 10 version 1809 (build 17763)
+- Include copyright headers; build clean with no warnings
+
+## Style Enforcement
+
+- **C#**: Follow `.editorconfig` at repo root
+- **C++**: Use C++/WinRT; check `Samples/WindowsML/` for `.clang-format`
+
+## When to Ask for Clarification
+
+- Ambiguous sample requirements after reviewing docs
+- Cross-feature impact unclear
+- API usage patterns not well documented
+
+## Detailed Documentation
+
+- [AGENTS.md](../AGENTS.md) – Full AI contributor guide
+- [Samples Guidelines](../docs/samples-guidelines.md) – Complete guidelines and checklist
+- [Contributing](../CONTRIBUTING.md) – Contribution requirements
+- [PR Template](../docs/pull_request_template.md) – Pull request checklist
+- [Windows App SDK Docs](https://docs.microsoft.com/windows/apps/windows-app-sdk/) – Official documentation
diff --git a/.github/instructions/agents.instructions.md b/.github/instructions/agents.instructions.md
new file mode 100644
index 000000000..8d602c881
--- /dev/null
+++ b/.github/instructions/agents.instructions.md
@@ -0,0 +1,791 @@
+---
+description: 'Guidelines for creating custom agent files for GitHub Copilot'
+applyTo: '**/*.agent.md'
+---
+
+# Custom Agent File Guidelines
+
+Instructions for creating effective and maintainable custom agent files that provide specialized expertise for specific development tasks in GitHub Copilot.
+
+## Project Context
+
+- Target audience: Developers creating custom agents for GitHub Copilot
+- File format: Markdown with YAML frontmatter
+- File naming convention: lowercase with hyphens (e.g., `test-specialist.agent.md`)
+- Location: `.github/agents/` directory (repository-level) or `agents/` directory (organization/enterprise-level)
+- Purpose: Define specialized agents with tailored expertise, tools, and instructions for specific tasks
+- Official documentation: https://docs.github.com/en/copilot/how-tos/use-copilot-agents/coding-agent/create-custom-agents
+
+## Required Frontmatter
+
+Every agent file must include YAML frontmatter with the following fields:
+
+```yaml
+---
+description: 'Brief description of the agent purpose and capabilities'
+name: 'Agent Display Name'
+tools: ['read', 'edit', 'search']
+model: 'Claude Sonnet 4.5'
+target: 'vscode'
+infer: true
+---
+```
+
+### Core Frontmatter Properties
+
+#### **description** (REQUIRED)
+- Single-quoted string, clearly stating the agent's purpose and domain expertise
+- Should be concise (50-150 characters) and actionable
+- Example: `'Focuses on test coverage, quality, and testing best practices'`
+
+#### **name** (OPTIONAL)
+- Display name for the agent in the UI
+- If omitted, defaults to filename (without `.md` or `.agent.md`)
+- Use title case and be descriptive
+- Example: `'Testing Specialist'`
+
+#### **tools** (OPTIONAL)
+- List of tool names or aliases the agent can use
+- Supports comma-separated string or YAML array format
+- If omitted, agent has access to all available tools
+- See "Tool Configuration" section below for details
+
+#### **model** (STRONGLY RECOMMENDED)
+- Specifies which AI model the agent should use
+- Supported in VS Code, JetBrains IDEs, Eclipse, and Xcode
+- Example: `'Claude Sonnet 4.5'`, `'gpt-4'`, `'gpt-4o'`
+- Choose based on agent complexity and required capabilities
+
+#### **target** (OPTIONAL)
+- Specifies target environment: `'vscode'` or `'github-copilot'`
+- If omitted, agent is available in both environments
+- Use when agent has environment-specific features
+
+#### **infer** (OPTIONAL)
+- Boolean controlling whether Copilot can automatically use this agent based on context
+- Default: `true` if omitted
+- Set to `false` to require manual agent selection
+
+#### **metadata** (OPTIONAL, GitHub.com only)
+- Object with name-value pairs for agent annotation
+- Example: `metadata: { category: 'testing', version: '1.0' }`
+- Not supported in VS Code
+
+#### **mcp-servers** (OPTIONAL, Organization/Enterprise only)
+- Configure MCP servers available only to this agent
+- Only supported for organization/enterprise level agents
+- See "MCP Server Configuration" section below
+
+## Tool Configuration
+
+### Tool Specification Strategies
+
+**Enable all tools** (default):
+```yaml
+# Omit tools property entirely, or use:
+tools: ['*']
+```
+
+**Enable specific tools**:
+```yaml
+tools: ['read', 'edit', 'search', 'execute']
+```
+
+**Enable MCP server tools**:
+```yaml
+tools: ['read', 'edit', 'github/*', 'playwright/navigate']
+```
+
+**Disable all tools**:
+```yaml
+tools: []
+```
+
+### Standard Tool Aliases
+
+All aliases are case-insensitive:
+
+| Alias | Alternative Names | Category | Description |
+|-------|------------------|----------|-------------|
+| `execute` | shell, Bash, powershell | Shell execution | Execute commands in appropriate shell |
+| `read` | Read, NotebookRead, view | File reading | Read file contents |
+| `edit` | Edit, MultiEdit, Write, NotebookEdit | File editing | Edit and modify files |
+| `search` | Grep, Glob, search | Code search | Search for files or text in files |
+| `agent` | custom-agent, Task | Agent invocation | Invoke other custom agents |
+| `web` | WebSearch, WebFetch | Web access | Fetch web content and search |
+| `todo` | TodoWrite | Task management | Create and manage task lists (VS Code only) |
+
+### Built-in MCP Server Tools
+
+**GitHub MCP Server**:
+```yaml
+tools: ['github/*'] # All GitHub tools
+tools: ['github/get_file_contents', 'github/search_repositories'] # Specific tools
+```
+- All read-only tools available by default
+- Token scoped to source repository
+
+**Playwright MCP Server**:
+```yaml
+tools: ['playwright/*'] # All Playwright tools
+tools: ['playwright/navigate', 'playwright/screenshot'] # Specific tools
+```
+- Configured to access localhost only
+- Useful for browser automation and testing
+
+### Tool Selection Best Practices
+
+- **Principle of Least Privilege**: Only enable tools necessary for the agent's purpose
+- **Security**: Limit `execute` access unless explicitly required
+- **Focus**: Fewer tools = clearer agent purpose and better performance
+- **Documentation**: Comment why specific tools are required for complex configurations
+
+## Sub-Agent Invocation (Agent Orchestration)
+
+Agents can invoke other agents using `runSubagent` to orchestrate multi-step workflows.
+
+### How It Works
+
+Include `agent` in tools list to enable sub-agent invocation:
+
+```yaml
+tools: ['read', 'edit', 'search', 'agent']
+```
+
+Then invoke other agents with `runSubagent`:
+
+```javascript
+const result = await runSubagent({
+ description: 'What this step does',
+ prompt: `You are the [Specialist] specialist.
+
+Context:
+- Parameter: ${parameterValue}
+- Input: ${inputPath}
+- Output: ${outputPath}
+
+Task:
+1. Do the specific work
+2. Write results to output location
+3. Return summary of completion`
+});
+```
+
+### Basic Pattern
+
+Structure each sub-agent call with:
+
+1. **description**: Clear one-line purpose of the sub-agent invocation
+2. **prompt**: Detailed instructions with substituted variables
+
+The prompt should include:
+- Who the sub-agent is (specialist role)
+- What context it needs (parameters, paths)
+- What to do (concrete tasks)
+- Where to write output
+- What to return (summary)
+
+### Example: Multi-Step Processing
+
+```javascript
+// Step 1: Process data
+const processing = await runSubagent({
+ description: 'Transform raw input data',
+ prompt: `You are the Data Processor specialist.
+
+Project: ${projectName}
+Input: ${basePath}/raw/
+Output: ${basePath}/processed/
+
+Task:
+1. Read all files from input directory
+2. Apply transformations
+3. Write processed files to output
+4. Create summary: ${basePath}/processed/summary.md
+
+Return: Number of files processed and any issues found`
+});
+
+// Step 2: Analyze (depends on Step 1)
+const analysis = await runSubagent({
+ description: 'Analyze processed data',
+ prompt: `You are the Data Analyst specialist.
+
+Project: ${projectName}
+Input: ${basePath}/processed/
+Output: ${basePath}/analysis/
+
+Task:
+1. Read processed files from input
+2. Generate analysis report
+3. Write to: ${basePath}/analysis/report.md
+
+Return: Key findings and identified patterns`
+});
+```
+
+### Key Points
+
+- **Pass variables in prompts**: Use `${variableName}` for all dynamic values
+- **Keep prompts focused**: Clear, specific tasks for each sub-agent
+- **Return summaries**: Each sub-agent should report what it accomplished
+- **Sequential execution**: Use `await` to maintain order when steps depend on each other
+- **Error handling**: Check results before proceeding to dependent steps
+
+### ⚠️ Tool Availability Requirement
+
+**Critical**: If a sub-agent requires specific tools (e.g., `edit`, `execute`, `search`), the orchestrator must include those tools in its own `tools` list. Sub-agents cannot access tools that aren't available to their parent orchestrator.
+
+**Example**:
+```yaml
+# If your sub-agents need to edit files, execute commands, or search code
+tools: ['read', 'edit', 'search', 'execute', 'agent']
+```
+
+The orchestrator's tool permissions act as a ceiling for all invoked sub-agents. Plan your tool list carefully to ensure all sub-agents have the tools they need.
+
+### ⚠️ Important Limitation
+
+**Sub-agent orchestration is NOT suitable for large-scale data processing.** Avoid using `runSubagent` when:
+- Processing hundreds or thousands of files
+- Handling large datasets
+- Performing bulk transformations on big codebases
+- Orchestrating more than 5-10 sequential steps
+
+Each sub-agent call adds latency and context overhead. For high-volume processing, implement logic directly in a single agent instead. Use orchestration only for coordinating specialized tasks on focused, manageable datasets.
+
+## Agent Prompt Structure
+
+The markdown content below the frontmatter defines the agent's behavior, expertise, and instructions. Well-structured prompts typically include:
+
+1. **Agent Identity and Role**: Who the agent is and its primary role
+2. **Core Responsibilities**: What specific tasks the agent performs
+3. **Approach and Methodology**: How the agent works to accomplish tasks
+4. **Guidelines and Constraints**: What to do/avoid and quality standards
+5. **Output Expectations**: Expected output format and quality
+
+### Prompt Writing Best Practices
+
+- **Be Specific and Direct**: Use imperative mood ("Analyze", "Generate"); avoid vague terms
+- **Define Boundaries**: Clearly state scope limits and constraints
+- **Include Context**: Explain domain expertise and reference relevant frameworks
+- **Focus on Behavior**: Describe how the agent should think and work
+- **Use Structured Format**: Headers, bullets, and lists make prompts scannable
+
+## Variable Definition and Extraction
+
+Agents can define dynamic parameters to extract values from user input and use them throughout the agent's behavior and sub-agent communications. This enables flexible, context-aware agents that adapt to user-provided data.
+
+### When to Use Variables
+
+**Use variables when**:
+- Agent behavior depends on user input
+- Need to pass dynamic values to sub-agents
+- Want to make agents reusable across different contexts
+- Require parameterized workflows
+- Need to track or reference user-provided context
+
+**Examples**:
+- Extract project name from user prompt
+- Capture certification name for pipeline processing
+- Identify file paths or directories
+- Extract configuration options
+- Parse feature names or module identifiers
+
+### Variable Declaration Pattern
+
+Define variables section early in the agent prompt to document expected parameters:
+
+```markdown
+# Agent Name
+
+## Dynamic Parameters
+
+- **Parameter Name**: Description and usage
+- **Another Parameter**: How it's extracted and used
+
+## Your Mission
+
+Process [PARAMETER_NAME] to accomplish [task].
+```
+
+### Variable Extraction Methods
+
+#### 1. **Explicit User Input**
+Ask the user to provide the variable if not detected in the prompt:
+
+```markdown
+## Your Mission
+
+Process the project by analyzing your codebase.
+
+### Step 1: Identify Project
+If no project name is provided, **ASK THE USER** for:
+- Project name or identifier
+- Base path or directory location
+- Configuration type (if applicable)
+
+Use this information to contextualize all subsequent tasks.
+```
+
+#### 2. **Implicit Extraction from Prompt**
+Automatically extract variables from the user's natural language input:
+
+```javascript
+// Example: Extract certification name from user input
+const userInput = "Process My Certification";
+
+// Extract key information
+const certificationName = extractCertificationName(userInput);
+// Result: "My Certification"
+
+const basePath = `certifications/${certificationName}`;
+// Result: "certifications/My Certification"
+```
+
+#### 3. **Contextual Variable Resolution**
+Use file context or workspace information to derive variables:
+
+```markdown
+## Variable Resolution Strategy
+
+1. **From User Prompt**: First, look for explicit mentions in user input
+2. **From File Context**: Check current file name or path
+3. **From Workspace**: Use workspace folder or active project
+4. **From Settings**: Reference configuration files
+5. **Ask User**: If all else fails, request missing information
+```
+
+### Using Variables in Agent Prompts
+
+#### Variable Substitution in Instructions
+
+Use template variables in agent prompts to make them dynamic:
+
+```markdown
+# Agent Name
+
+## Dynamic Parameters
+- **Project Name**: ${projectName}
+- **Base Path**: ${basePath}
+- **Output Directory**: ${outputDir}
+
+## Your Mission
+
+Process the **${projectName}** project located at `${basePath}`.
+
+## Process Steps
+
+1. Read input from: `${basePath}/input/`
+2. Process files according to project configuration
+3. Write results to: `${outputDir}/`
+4. Generate summary report
+
+## Quality Standards
+
+- Maintain project-specific coding standards for **${projectName}**
+- Follow directory structure: `${basePath}/[structure]`
+```
+
+#### Passing Variables to Sub-Agents
+
+When invoking a sub-agent, pass all context through template variables in the prompt:
+
+```javascript
+// Extract and prepare variables
+const basePath = `projects/${projectName}`;
+const inputPath = `${basePath}/src/`;
+const outputPath = `${basePath}/docs/`;
+
+// Pass to sub-agent with all variables substituted
+const result = await runSubagent({
+ description: 'Generate project documentation',
+ prompt: `You are the Documentation specialist.
+
+Project: ${projectName}
+Input: ${inputPath}
+Output: ${outputPath}
+
+Task:
+1. Read source files from ${inputPath}
+2. Generate comprehensive documentation
+3. Write to ${outputPath}/index.md
+4. Include code examples and usage guides
+
+Return: Summary of documentation generated (file count, word count)`
+});
+```
+
+The sub-agent receives all necessary context embedded in the prompt. Variables are resolved before sending the prompt, so the sub-agent works with concrete paths and values, not variable placeholders.
+
+### Real-World Example: Code Review Orchestrator
+
+Example of a simple orchestrator that validates code through multiple specialized agents:
+
+```javascript
+async function reviewCodePipeline(repositoryName, prNumber) {
+ const basePath = `projects/${repositoryName}/pr-${prNumber}`;
+
+ // Step 1: Security Review
+ const security = await runSubagent({
+ description: 'Scan for security vulnerabilities',
+ prompt: `You are the Security Reviewer specialist.
+
+Repository: ${repositoryName}
+PR: ${prNumber}
+Code: ${basePath}/changes/
+
+Task:
+1. Scan code for OWASP Top 10 vulnerabilities
+2. Check for injection attacks, auth flaws
+3. Write findings to ${basePath}/security-review.md
+
+Return: List of critical, high, and medium issues found`
+ });
+
+ // Step 2: Test Coverage Check
+ const coverage = await runSubagent({
+ description: 'Verify test coverage for changes',
+ prompt: `You are the Test Coverage specialist.
+
+Repository: ${repositoryName}
+PR: ${prNumber}
+Changes: ${basePath}/changes/
+
+Task:
+1. Analyze code coverage for modified files
+2. Identify untested critical paths
+3. Write report to ${basePath}/coverage-report.md
+
+Return: Current coverage percentage and gaps`
+ });
+
+ // Step 3: Aggregate Results
+ const finalReport = await runSubagent({
+ description: 'Compile all review findings',
+ prompt: `You are the Review Aggregator specialist.
+
+Repository: ${repositoryName}
+Reports: ${basePath}/*.md
+
+Task:
+1. Read all review reports from ${basePath}/
+2. Synthesize findings into single report
+3. Determine overall verdict (APPROVE/NEEDS_FIXES/BLOCK)
+4. Write to ${basePath}/final-review.md
+
+Return: Final verdict and executive summary`
+ });
+
+ return finalReport;
+}
+```
+
+This pattern applies to any orchestration scenario: extract variables, call sub-agents with clear context, await results.
+
+
+### Variable Best Practices
+
+#### 1. **Clear Documentation**
+Always document what variables are expected:
+
+```markdown
+## Required Variables
+- **projectName**: The name of the project (string, required)
+- **basePath**: Root directory for project files (path, required)
+
+## Optional Variables
+- **mode**: Processing mode - quick/standard/detailed (enum, default: standard)
+- **outputFormat**: Output format - markdown/json/html (enum, default: markdown)
+
+## Derived Variables
+- **outputDir**: Automatically set to ${basePath}/output
+- **logFile**: Automatically set to ${basePath}/.log.md
+```
+
+#### 2. **Consistent Naming**
+Use consistent variable naming conventions:
+
+```javascript
+// Good: Clear, descriptive naming
+const variables = {
+ projectName, // What project to work on
+ basePath, // Where project files are located
+ outputDirectory, // Where to save results
+ processingMode, // How to process (detail level)
+ configurationPath // Where config files are
+};
+
+// Avoid: Ambiguous or inconsistent
+const bad_variables = {
+ name, // Too generic
+ path, // Unclear which path
+ mode, // Too short
+ config // Too vague
+};
+```
+
+#### 3. **Validation and Constraints**
+Document valid values and constraints:
+
+```markdown
+## Variable Constraints
+
+**projectName**:
+- Type: string (alphanumeric, hyphens, underscores allowed)
+- Length: 1-100 characters
+- Required: yes
+- Pattern: `/^[a-zA-Z0-9_-]+$/`
+
+**processingMode**:
+- Type: enum
+- Valid values: "quick" (< 5min), "standard" (5-15min), "detailed" (15+ min)
+- Default: "standard"
+- Required: no
+```
+
+## MCP Server Configuration (Organization/Enterprise Only)
+
+MCP servers extend agent capabilities with additional tools. Only supported for organization and enterprise-level agents.
+
+### Configuration Format
+
+```yaml
+---
+name: my-custom-agent
+description: 'Agent with MCP integration'
+tools: ['read', 'edit', 'custom-mcp/tool-1']
+mcp-servers:
+ custom-mcp:
+ type: 'local'
+ command: 'some-command'
+ args: ['--arg1', '--arg2']
+ tools: ["*"]
+ env:
+ ENV_VAR_NAME: ${{ secrets.API_KEY }}
+---
+```
+
+### MCP Server Properties
+
+- **type**: Server type (`'local'` or `'stdio'`)
+- **command**: Command to start the MCP server
+- **args**: Array of command arguments
+- **tools**: Tools to enable from this server (`["*"]` for all)
+- **env**: Environment variables (supports secrets)
+
+### Environment Variables and Secrets
+
+Secrets must be configured in repository settings under "copilot" environment.
+
+**Supported syntax**:
+```yaml
+env:
+ # Environment variable only
+ VAR_NAME: COPILOT_MCP_ENV_VAR_VALUE
+
+ # Variable with header
+ VAR_NAME: $COPILOT_MCP_ENV_VAR_VALUE
+ VAR_NAME: ${COPILOT_MCP_ENV_VAR_VALUE}
+
+ # GitHub Actions-style (YAML only)
+ VAR_NAME: ${{ secrets.COPILOT_MCP_ENV_VAR_VALUE }}
+ VAR_NAME: ${{ var.COPILOT_MCP_ENV_VAR_VALUE }}
+```
+
+## File Organization and Naming
+
+### Repository-Level Agents
+- Location: `.github/agents/`
+- Scope: Available only in the specific repository
+- Access: Uses repository-configured MCP servers
+
+### Organization/Enterprise-Level Agents
+- Location: `.github-private/agents/` (then move to `agents/` root)
+- Scope: Available across all repositories in org/enterprise
+- Access: Can configure dedicated MCP servers
+
+### Naming Conventions
+- Use lowercase with hyphens: `test-specialist.agent.md`
+- Name should reflect agent purpose
+- Filename becomes default agent name (if `name` not specified)
+- Allowed characters: `.`, `-`, `_`, `a-z`, `A-Z`, `0-9`
+
+## Agent Processing and Behavior
+
+### Versioning
+- Based on Git commit SHAs for the agent file
+- Create branches/tags for different agent versions
+- Instantiated using latest version for repository/branch
+- PR interactions use same agent version for consistency
+
+### Name Conflicts
+Priority (highest to lowest):
+1. Repository-level agent
+2. Organization-level agent
+3. Enterprise-level agent
+
+Lower-level configurations override higher-level ones with the same name.
+
+### Tool Processing
+- `tools` list filters available tools (built-in and MCP)
+- No tools specified = all tools enabled
+- Empty list (`[]`) = all tools disabled
+- Specific list = only those tools enabled
+- Unrecognized tool names are ignored (allows environment-specific tools)
+
+### MCP Server Processing Order
+1. Out-of-the-box MCP servers (e.g., GitHub MCP)
+2. Custom agent MCP configuration (org/enterprise only)
+3. Repository-level MCP configurations
+
+Each level can override settings from previous levels.
+
+## Agent Creation Checklist
+
+### Frontmatter
+- [ ] `description` field present and descriptive (50-150 chars)
+- [ ] `description` wrapped in single quotes
+- [ ] `name` specified (optional but recommended)
+- [ ] `tools` configured appropriately (or intentionally omitted)
+- [ ] `model` specified for optimal performance
+- [ ] `target` set if environment-specific
+- [ ] `infer` set to `false` if manual selection required
+
+### Prompt Content
+- [ ] Clear agent identity and role defined
+- [ ] Core responsibilities listed explicitly
+- [ ] Approach and methodology explained
+- [ ] Guidelines and constraints specified
+- [ ] Output expectations documented
+- [ ] Examples provided where helpful
+- [ ] Instructions are specific and actionable
+- [ ] Scope and boundaries clearly defined
+- [ ] Total content under 30,000 characters
+
+### File Structure
+- [ ] Filename follows lowercase-with-hyphens convention
+- [ ] File placed in correct directory (`.github/agents/` or `agents/`)
+- [ ] Filename uses only allowed characters
+- [ ] File extension is `.agent.md`
+
+### Quality Assurance
+- [ ] Agent purpose is unique and not duplicative
+- [ ] Tools are minimal and necessary
+- [ ] Instructions are clear and unambiguous
+- [ ] Agent has been tested with representative tasks
+- [ ] Documentation references are current
+- [ ] Security considerations addressed (if applicable)
+
+## Common Agent Patterns
+
+### Testing Specialist
+**Purpose**: Focus on test coverage and quality
+**Tools**: All tools (for comprehensive test creation)
+**Approach**: Analyze, identify gaps, write tests, avoid production code changes
+
+### Implementation Planner
+**Purpose**: Create detailed technical plans and specifications
+**Tools**: Limited to `['read', 'search', 'edit']`
+**Approach**: Analyze requirements, create documentation, avoid implementation
+
+### Code Reviewer
+**Purpose**: Review code quality and provide feedback
+**Tools**: `['read', 'search']` only
+**Approach**: Analyze, suggest improvements, no direct modifications
+
+### Refactoring Specialist
+**Purpose**: Improve code structure and maintainability
+**Tools**: `['read', 'search', 'edit']`
+**Approach**: Analyze patterns, propose refactorings, implement safely
+
+### Security Auditor
+**Purpose**: Identify security issues and vulnerabilities
+**Tools**: `['read', 'search', 'web']`
+**Approach**: Scan code, check against OWASP, report findings
+
+## Common Mistakes to Avoid
+
+### Frontmatter Errors
+- ❌ Missing `description` field
+- ❌ Description not wrapped in quotes
+- ❌ Invalid tool names without checking documentation
+- ❌ Incorrect YAML syntax (indentation, quotes)
+
+### Tool Configuration Issues
+- ❌ Granting excessive tool access unnecessarily
+- ❌ Missing required tools for agent's purpose
+- ❌ Not using tool aliases consistently
+- ❌ Forgetting MCP server namespace (`server-name/tool`)
+
+### Prompt Content Problems
+- ❌ Vague, ambiguous instructions
+- ❌ Conflicting or contradictory guidelines
+- ❌ Lack of clear scope definition
+- ❌ Missing output expectations
+- ❌ Overly verbose instructions (exceeding character limits)
+- ❌ No examples or context for complex tasks
+
+### Organizational Issues
+- ❌ Filename doesn't reflect agent purpose
+- ❌ Wrong directory (confusing repo vs org level)
+- ❌ Using spaces or special characters in filename
+- ❌ Duplicate agent names causing conflicts
+
+## Testing and Validation
+
+### Manual Testing
+1. Create the agent file with proper frontmatter
+2. Reload VS Code or refresh GitHub.com
+3. Select the agent from the dropdown in Copilot Chat
+4. Test with representative user queries
+5. Verify tool access works as expected
+6. Confirm output meets expectations
+
+### Integration Testing
+- Test agent with different file types in scope
+- Verify MCP server connectivity (if configured)
+- Check agent behavior with missing context
+- Test error handling and edge cases
+- Validate agent switching and handoffs
+
+### Quality Checks
+- Run through agent creation checklist
+- Review against common mistakes list
+- Compare with example agents in repository
+- Get peer review for complex agents
+- Document any special configuration needs
+
+## Additional Resources
+
+### Official Documentation
+- [Creating Custom Agents](https://docs.github.com/en/copilot/how-tos/use-copilot-agents/coding-agent/create-custom-agents)
+- [Custom Agents Configuration](https://docs.github.com/en/copilot/reference/custom-agents-configuration)
+- [Custom Agents in VS Code](https://code.visualstudio.com/docs/copilot/customization/custom-agents)
+- [MCP Integration](https://docs.github.com/en/copilot/how-tos/use-copilot-agents/coding-agent/extend-coding-agent-with-mcp)
+
+### Community Resources
+- [Awesome Copilot Agents Collection](https://github.com/github/awesome-copilot/tree/main/agents)
+- [Customization Library Examples](https://docs.github.com/en/copilot/tutorials/customization-library/custom-agents)
+- [Your First Custom Agent Tutorial](https://docs.github.com/en/copilot/tutorials/customization-library/custom-agents/your-first-custom-agent)
+
+### Related Files
+- [Prompt Files Guidelines](./prompt.instructions.md) - For creating prompt files
+- [Instructions Guidelines](./instructions.instructions.md) - For creating instruction files
+
+## Version Compatibility Notes
+
+### GitHub.com (Coding Agent)
+- ✅ Fully supports all standard frontmatter properties
+- ✅ Repository and org/enterprise level agents
+- ✅ MCP server configuration (org/enterprise)
+- ❌ Does not support `model`, `argument-hint`, `handoffs` properties
+
+### VS Code / JetBrains / Eclipse / Xcode
+- ✅ Supports `model` property for AI model selection
+- ✅ Supports `argument-hint` and `handoffs` properties
+- ✅ User profile and workspace-level agents
+- ❌ Cannot configure MCP servers at repository level
+- ⚠️ Some properties may behave differently
+
+When creating agents for multiple environments, focus on common properties and test in all target environments. Use `target` property to create environment-specific agents when necessary.
diff --git a/.github/instructions/azure-devops-pipelines.instructions.md b/.github/instructions/azure-devops-pipelines.instructions.md
new file mode 100644
index 000000000..de366c0a6
--- /dev/null
+++ b/.github/instructions/azure-devops-pipelines.instructions.md
@@ -0,0 +1,228 @@
+---
+description: 'Best practices for Azure DevOps Pipeline YAML files'
+applyTo: '**/azure-pipelines.yml, **/azure-pipelines*.yml, **/*.pipeline.yml, **/SamplesCI-*.yml, **/WindowsAppSDK-*.yml'
+---
+
+# Azure DevOps Pipeline YAML Best Practices
+
+Guidelines for creating maintainable, secure, and efficient Azure DevOps pipelines in WindowsAppSDK-Samples.
+
+## General Guidelines
+
+- Use YAML syntax consistently with proper indentation (2 spaces)
+- Always include meaningful names and display names for pipelines, stages, jobs, and steps
+- Implement proper error handling and conditional execution
+- Use variables and parameters to make pipelines reusable and maintainable
+- Follow the principle of least privilege for service connections and permissions
+- Include comprehensive logging and diagnostics for troubleshooting
+
+## Pipeline Structure
+
+- Organize complex pipelines using stages for better visualization and control
+- Use jobs to group related steps and enable parallel execution when possible
+- Implement proper dependencies between stages and jobs
+- Use templates for reusable pipeline components
+- Keep pipeline files focused and modular - split large pipelines into multiple files
+
+## Build Best Practices
+
+- Use specific agent pool versions and VM images for consistency
+- Cache dependencies (npm, NuGet, Maven, etc.) to improve build performance
+- Implement proper artifact management with meaningful names and retention policies
+- Use build variables for version numbers and build metadata
+- Include code quality gates (lint checks, testing, security scans)
+- Ensure builds are reproducible and environment-independent
+
+## Testing Integration
+
+- Run unit tests as part of the build process
+- Publish test results in standard formats (JUnit, VSTest, etc.)
+- Include code coverage reporting and quality gates
+- Implement integration and end-to-end tests in appropriate stages
+- Use test impact analysis when available to optimize test execution
+- Fail fast on test failures to provide quick feedback
+
+## Security Considerations
+
+- Use Azure Key Vault for sensitive configuration and secrets
+- Implement proper secret management with variable groups
+- Use service connections with minimal required permissions
+- Enable security scans (dependency vulnerabilities, static analysis)
+- Implement approval gates for production deployments
+- Use managed identities when possible instead of service principals
+
+## Deployment Strategies
+
+- Implement proper environment promotion (dev → staging → production)
+- Use deployment jobs with proper environment targeting
+- Implement blue-green or canary deployment strategies when appropriate
+- Include rollback mechanisms and health checks
+- Use infrastructure as code (ARM, Bicep, Terraform) for consistent deployments
+- Implement proper configuration management per environment
+
+## Variable and Parameter Management
+
+- Use variable groups for shared configuration across pipelines
+- Implement runtime parameters for flexible pipeline execution
+- Use conditional variables based on branches or environments
+- Secure sensitive variables and mark them as secrets
+- Document variable purposes and expected values
+- Use variable templates for complex variable logic
+
+## Performance Optimization
+
+- Use parallel jobs and matrix strategies when appropriate
+- Implement proper caching strategies for dependencies and build outputs
+- Use shallow clone for Git operations when full history isn't needed
+- Optimize Docker image builds with multi-stage builds and layer caching
+- Monitor pipeline performance and optimize bottlenecks
+- Use pipeline resource triggers efficiently
+
+## Monitoring and Observability
+
+- Include comprehensive logging throughout the pipeline
+- Use Azure Monitor and Application Insights for deployment tracking
+- Implement proper notification strategies for failures and successes
+- Include deployment health checks and automated rollback triggers
+- Use pipeline analytics to identify improvement opportunities
+- Document pipeline behavior and troubleshooting steps
+
+## Template and Reusability
+
+- Create pipeline templates for common patterns
+- Use extends templates for complete pipeline inheritance
+- Implement step templates for reusable task sequences
+- Use variable templates for complex variable logic
+- Version templates appropriately for stability
+- Document template parameters and usage examples
+
+## Branch and Trigger Strategy
+
+- Implement appropriate triggers for different branch types
+- Use path filters to trigger builds only when relevant files change
+- Configure proper CI/CD triggers for main/master branches
+- Use pull request triggers for code validation
+- Implement scheduled triggers for maintenance tasks
+- Consider resource triggers for multi-repository scenarios
+
+## Example Structure
+
+```yaml
+# azure-pipelines.yml
+trigger:
+ branches:
+ include:
+ - main
+ - develop
+ paths:
+ exclude:
+ - docs/*
+ - README.md
+
+variables:
+ - group: shared-variables
+ - name: buildConfiguration
+ value: 'Release'
+
+stages:
+ - stage: Build
+ displayName: 'Build and Test'
+ jobs:
+ - job: Build
+ displayName: 'Build Application'
+ pool:
+ vmImage: 'ubuntu-latest'
+ steps:
+ - task: UseDotNet@2
+ displayName: 'Use .NET SDK'
+ inputs:
+ version: '8.x'
+
+ - task: DotNetCoreCLI@2
+ displayName: 'Restore dependencies'
+ inputs:
+ command: 'restore'
+ projects: '**/*.csproj'
+
+ - task: DotNetCoreCLI@2
+ displayName: 'Build application'
+ inputs:
+ command: 'build'
+ projects: '**/*.csproj'
+ arguments: '--configuration $(buildConfiguration) --no-restore'
+
+ - stage: Deploy
+ displayName: 'Deploy to Staging'
+ dependsOn: Build
+ condition: and(succeeded(), eq(variables['Build.SourceBranch'], 'refs/heads/main'))
+ jobs:
+ - deployment: DeployToStaging
+ displayName: 'Deploy to Staging Environment'
+ environment: 'staging'
+ strategy:
+ runOnce:
+ deploy:
+ steps:
+ - download: current
+ displayName: 'Download drop artifact'
+ artifact: drop
+ - task: AzureWebApp@1
+ displayName: 'Deploy to Azure Web App'
+ inputs:
+ azureSubscription: 'staging-service-connection'
+ appType: 'webApp'
+ appName: 'myapp-staging'
+ package: '$(Pipeline.Workspace)/drop/**/*.zip'
+```
+
+## Common Anti-Patterns to Avoid
+
+- Hardcoding sensitive values directly in YAML files
+- Using overly broad triggers that cause unnecessary builds
+- Mixing build and deployment logic in a single stage
+- Not implementing proper error handling and cleanup
+- Using deprecated task versions without upgrade plans
+- Creating monolithic pipelines that are difficult to maintain
+- Not using proper naming conventions for clarity
+- Ignoring pipeline security best practices
+
+## WindowsAppSDK-Samples Specific Patterns
+
+### Feature-Specific CI Pipelines
+
+Each feature in the Samples repo should have its own CI pipeline. Create a new pipeline file named `SamplesCI-.yml` at the repository root:
+
+```yaml
+# SamplesCI-.yml
+name: $(BuildDefinitionName)_$(date:yyMM).$(date:dd)$(rev:rrr)
+stages:
+- template: WindowsAppSDK-SamplesCI.yml
+ parameters:
+ FeatureDirectory: ""
+```
+
+### Adding Features to SamplesCI-All.yml
+
+When onboarding a new feature, add it to the `FeatureAreas` parameter in `SamplesCI-All.yml` to include it in comprehensive builds.
+
+### Pipeline Setup Requirements
+
+1. **Triggers**: Configure pull request validation with path filters for your feature directory
+2. **Branch Filters**: Include `refs/heads/main`
+3. **Path Filters**: Include `Samples/`
+4. **Fork Builds**: Enable "Build pull requests from forks of this repository"
+5. **Comments**: Require team member's comment before building PRs
+
+### Build Configurations
+
+Samples should build for all supported configurations:
+- Platforms: x64, x86, ARM64
+- Configurations: Debug, Release
+- Minimum Windows version: Windows 10 version 1809 (build 17763)
+
+### Status Check Integration
+
+Add your pipeline to branch protection rules at:
+`https://github.com/microsoft/WindowsAppSDK-Samples/settings/branches`
+
+Ensure the full `SamplesCI-` check is added, not individual job configurations.
diff --git a/.github/instructions/csharp.instructions.md b/.github/instructions/csharp.instructions.md
new file mode 100644
index 000000000..a93658bf2
--- /dev/null
+++ b/.github/instructions/csharp.instructions.md
@@ -0,0 +1,79 @@
+---
+description: 'Guidelines for C# Windows App SDK samples'
+applyTo: '**/*.cs'
+---
+
+# C# Windows App SDK Development
+
+Guidelines for writing C# samples that demonstrate Windows App SDK features.
+
+## C# Instructions
+
+- Use C# language features appropriate for the target .NET version in the sample
+- Write clear and concise comments explaining API usage patterns
+- Focus on demonstrating Windows App SDK APIs, not general application architecture
+
+## General Instructions
+
+- Keep samples **complete but simple** – demonstrate correct API usage without excessive abstraction
+- Follow **scenario-based design** – each scenario covers one way of using the API
+- Handle edge cases with clear exception handling
+- Comment on why certain Windows App SDK patterns are used
+
+## Naming Conventions
+
+- Follow PascalCase for component names, method names, and public members
+- Use camelCase for private fields and local variables
+- Prefix interface names with "I" (e.g., IWindowService)
+
+## Formatting
+
+- Apply code-formatting style defined in `.editorconfig` at repo root
+- Prefer file-scoped namespace declarations
+- Insert a newline before the opening curly brace (Allman style)
+- Use pattern matching and switch expressions where they improve clarity
+- Use `nameof` instead of string literals when referring to member names
+
+## Code Analysis
+
+- All code must pass **StyleCop.Analyzers** rules without warnings
+- All code must pass **Microsoft.CodeAnalysis.NetAnalyzers** (CA rules) without warnings
+- Suppress warnings only with justification comments when absolutely necessary
+- Common rules to follow:
+ - [StyleCop.Analyzers rules](https://github.com/DotNetAnalyzers/StyleCopAnalyzers/blob/master/DOCUMENTATION.md)
+ - [Code quality rules (CA)](https://learn.microsoft.com/dotnet/fundamentals/code-analysis/quality-rules/)
+ - [Code style rules (IDE)](https://learn.microsoft.com/dotnet/fundamentals/code-analysis/style-rules/)
+
+## Nullable Reference Types
+
+- Declare variables non-nullable, and check for `null` at entry points
+- Always use `is null` or `is not null` instead of `== null` or `!= null`
+- Trust the C# null annotations and don't add null checks when the type system says a value cannot be null
+
+## Windows App SDK Patterns
+
+### App Lifecycle and Activation
+
+- Demonstrate proper activation handling (file, protocol, launch)
+- Show single-instance patterns using `AppInstance`
+- Handle restart and state persistence scenarios
+
+### WinUI 3 and XAML
+
+- Use x:Bind for data binding where possible
+- Demonstrate proper resource management and theming
+- Show Window and navigation patterns
+
+### Packaging and Deployment
+
+- Support both packaged (MSIX) and unpackaged scenarios where applicable
+- Use `WindowsPackageType` appropriately in project files
+- Demonstrate self-contained deployment patterns when relevant
+
+## Copyright Headers
+
+All C# files must include:
+```csharp
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT License.
+```
diff --git a/.github/instructions/instructions.instructions.md b/.github/instructions/instructions.instructions.md
new file mode 100644
index 000000000..107c1cf2c
--- /dev/null
+++ b/.github/instructions/instructions.instructions.md
@@ -0,0 +1,256 @@
+---
+description: 'Guidelines for creating high-quality custom instruction files for GitHub Copilot'
+applyTo: '**/*.instructions.md'
+---
+
+# Custom Instructions File Guidelines
+
+Instructions for creating effective and maintainable custom instruction files that guide GitHub Copilot in generating domain-specific code and following project conventions.
+
+## Project Context
+
+- Target audience: Developers and GitHub Copilot working with domain-specific code
+- File format: Markdown with YAML frontmatter
+- File naming convention: filename stem in lowercase-with-hyphens plus the `.instructions.md` suffix (e.g., stem `react-best-practices` → `react-best-practices.instructions.md`)
+- Location: `.github/instructions/` directory
+- Purpose: Provide context-aware guidance for code generation, review, and documentation
+
+## Required Frontmatter
+
+Every instruction file must include YAML frontmatter with the following fields:
+
+```yaml
+---
+description: 'Brief description of the instruction purpose and scope'
+applyTo: 'glob pattern for target files (e.g., **/*.ts, **/*.py)'
+---
+```
+
+### Frontmatter Guidelines
+
+- **description**: Single-quoted string, 1-500 characters, clearly stating the purpose
+- **applyTo**: Glob pattern(s) specifying which files these instructions apply to
+ - Single pattern: `'**/*.ts'`
+ - Multiple patterns: `'**/*.ts, **/*.tsx, **/*.js'`
+ - Specific files: `'src/**/*.py'`
+ - All files: `'**'`
+
+## File Structure
+
+A well-structured instruction file should include the following sections:
+
+### 1. Title and Overview
+
+- Clear, descriptive title using `#` heading
+- Brief introduction explaining the purpose and scope
+- Optional: Project context section with key technologies and versions
+
+### 2. Core Sections
+
+Organize content into logical sections based on the domain:
+
+- **General Instructions**: High-level guidelines and principles
+- **Best Practices**: Recommended patterns and approaches
+- **Code Standards**: Naming conventions, formatting, style rules
+- **Architecture/Structure**: Project organization and design patterns
+- **Common Patterns**: Frequently used implementations
+- **Security**: Security considerations (if applicable)
+- **Performance**: Optimization guidelines (if applicable)
+- **Testing**: Testing standards and approaches (if applicable)
+
+### 3. Examples and Code Snippets
+
+Provide concrete examples with clear labels:
+
+```markdown
+### Good Example
+\`\`\`language
+// Recommended approach
+code example here
+\`\`\`
+
+### Bad Example
+\`\`\`language
+// Avoid this pattern
+code example here
+\`\`\`
+```
+
+### 4. Validation and Verification (Optional but Recommended)
+
+- Build commands to verify code
+- Lint checks and formatting tools
+- Testing requirements
+- Verification steps
+
+## Content Guidelines
+
+### Writing Style
+
+- Use clear, concise language
+- Write in imperative mood ("Use", "Implement", "Avoid")
+- Be specific and actionable
+- Avoid ambiguous terms like "should", "might", "possibly"
+- Use bullet points and lists for readability
+- Keep sections focused and scannable
+
+### Best Practices
+
+- **Be Specific**: Provide concrete examples rather than abstract concepts
+- **Show Why**: Explain the reasoning behind recommendations when it adds value
+- **Use Tables**: For comparing options, listing rules, or showing patterns
+- **Include Examples**: Real code snippets are more effective than descriptions
+- **Stay Current**: Reference current versions and best practices
+- **Link Resources**: Include official documentation and authoritative sources
+
+### Common Patterns to Include
+
+1. **Naming Conventions**: How to name variables, functions, classes, files
+2. **Code Organization**: File structure, module organization, import order
+3. **Error Handling**: Preferred error handling patterns
+4. **Dependencies**: How to manage and document dependencies
+5. **Comments and Documentation**: When and how to document code
+6. **Version Information**: Target language/framework versions
+
+## Patterns to Follow
+
+### Bullet Points and Lists
+
+```markdown
+## Security Best Practices
+
+- Always validate user input before processing
+- Use parameterized queries to prevent SQL injection
+- Store secrets in environment variables, never in code
+- Implement proper authentication and authorization
+- Enable HTTPS for all production endpoints
+```
+
+### Tables for Structured Information
+
+```markdown
+## Common Issues
+
+| Issue | Solution | Example |
+| ---------------- | ------------------- | ----------------------------- |
+| Magic numbers | Use named constants | `const MAX_RETRIES = 3` |
+| Deep nesting | Extract functions | Refactor nested if statements |
+| Hardcoded values | Use configuration | Store API URLs in config |
+```
+
+### Code Comparison
+
+```markdown
+### Good Example - Using TypeScript interfaces
+\`\`\`typescript
+interface User {
+ id: string;
+ name: string;
+ email: string;
+}
+
+function getUser(id: string): User {
+ // Implementation
+}
+\`\`\`
+
+### Bad Example - Using any type
+\`\`\`typescript
+function getUser(id: any): any {
+ // Loses type safety
+}
+\`\`\`
+```
+
+### Conditional Guidance
+
+```markdown
+## Framework Selection
+
+- **For small projects**: Use Minimal API approach
+- **For large projects**: Use controller-based architecture with clear separation
+- **For microservices**: Consider domain-driven design patterns
+```
+
+## Patterns to Avoid
+
+- **Overly verbose explanations**: Keep it concise and scannable
+- **Outdated information**: Always reference current versions and practices
+- **Ambiguous guidelines**: Be specific about what to do or avoid
+- **Missing examples**: Abstract rules without concrete code examples
+- **Contradictory advice**: Ensure consistency throughout the file
+- **Copy-paste from documentation**: Add value by distilling and providing context
+
+## Testing Your Instructions
+
+Before finalizing instruction files:
+
+1. **Test with Copilot**: Try the instructions with actual prompts in VS Code
+2. **Verify Examples**: Ensure code examples are correct and run without errors
+3. **Check Glob Patterns**: Confirm `applyTo` patterns match intended files
+
+## Example Structure
+
+Here's a minimal example structure for a new instruction file:
+
+```markdown
+---
+description: 'Brief description of purpose'
+applyTo: '**/*.ext'
+---
+
+# Technology Name Development
+
+Brief introduction and context.
+
+## General Instructions
+
+- High-level guideline 1
+- High-level guideline 2
+
+## Best Practices
+
+- Specific practice 1
+- Specific practice 2
+
+## Code Standards
+
+### Naming Conventions
+- Rule 1
+- Rule 2
+
+### File Organization
+- Structure 1
+- Structure 2
+
+## Common Patterns
+
+### Pattern 1
+Description and example
+
+\`\`\`language
+code example
+\`\`\`
+
+### Pattern 2
+Description and example
+
+## Validation
+
+- Build command: `command to verify`
+- Lint checks: `command to lint`
+- Testing: `command to test`
+```
+
+## Maintenance
+
+- Review instructions when dependencies or frameworks are updated
+- Update examples to reflect current best practices
+- Remove outdated patterns or deprecated features
+- Add new patterns as they emerge in the community
+- Keep glob patterns accurate as project structure evolves
+
+## Additional Resources
+
+- [Custom Instructions Documentation](https://code.visualstudio.com/docs/copilot/customization/custom-instructions)
+- [Awesome Copilot Instructions](https://github.com/github/awesome-copilot/tree/main/instructions)
diff --git a/.github/instructions/powershell.instructions.md b/.github/instructions/powershell.instructions.md
new file mode 100644
index 000000000..97dbfb50a
--- /dev/null
+++ b/.github/instructions/powershell.instructions.md
@@ -0,0 +1,394 @@
+---
+applyTo: '**/*.ps1,**/*.psm1'
+description: 'PowerShell cmdlet and scripting best practices based on Microsoft guidelines'
+---
+
+# PowerShell Cmdlet Development Guidelines
+
+This guide provides PowerShell-specific instructions to help GitHub Copilot generate idiomatic,
+safe, and maintainable scripts. It aligns with Microsoft’s PowerShell cmdlet development guidelines.
+## Strict Mode and Exit Code Requirements
+
+**All scripts must enforce strict mode and proper exit codes:**
+
+```powershell
+Set-StrictMode -Version 2.0
+$ErrorActionPreference = 'Stop'
+
+# Script logic here...
+
+# Exit with appropriate code
+exit 0 # Success
+# exit 1 # Failure
+```
+
+### Strict Mode Rules
+
+- **Always use `Set-StrictMode -Version 2.0`** at the top of every script
+- This catches common errors: uninitialized variables, non-existent properties, function calls like methods
+- Combined with `$ErrorActionPreference = 'Stop'` for fail-fast behavior
+
+### Exit Code Requirements
+
+- **Exit 0** for successful completion
+- **Exit non-zero** (typically 1) for any failure
+- Use `try/catch/finally` with explicit exit codes:
+
+```powershell
+try {
+ # Main script logic
+ exit 0
+} catch {
+ Write-Error "Script failed: $_"
+ exit 1
+}
+```
+
+- For CI/build scripts, ensure the exit code reflects the actual success/failure state
+- Never silently swallow errors that should fail the build
+## Naming Conventions
+
+- **Verb-Noun Format:**
+ - Use approved PowerShell verbs (Get-Verb)
+ - Use singular nouns
+ - PascalCase for both verb and noun
+ - Avoid special characters and spaces
+
+- **Parameter Names:**
+ - Use PascalCase
+ - Choose clear, descriptive names
+ - Use singular form unless always multiple
+ - Follow PowerShell standard names
+
+- **Variable Names:**
+ - Use PascalCase for public variables
+ - Use camelCase for private variables
+ - Avoid abbreviations
+ - Use meaningful names
+
+- **Alias Avoidance:**
+ - Use full cmdlet names
+ - Avoid using aliases in scripts (e.g., use Get-ChildItem instead of gci)
+ - Document any custom aliases
+ - Use full parameter names
+
+### Example
+
+```powershell
+function Get-UserProfile {
+ [CmdletBinding()]
+ param(
+ [Parameter(Mandatory)]
+ [string]$Username,
+
+ [Parameter()]
+ [ValidateSet('Basic', 'Detailed')]
+ [string]$ProfileType = 'Basic'
+ )
+
+ process {
+ # Logic here
+ }
+}
+```
+
+## Parameter Design
+
+- **Standard Parameters:**
+ - Use common parameter names (`Path`, `Name`, `Force`)
+ - Follow built-in cmdlet conventions
+ - Use aliases for specialized terms
+ - Document parameter purpose
+
+- **Parameter Names:**
+ - Use singular form unless always multiple
+ - Choose clear, descriptive names
+ - Follow PowerShell conventions
+ - Use PascalCase formatting
+
+- **Type Selection:**
+ - Use common .NET types
+ - Implement proper validation
+ - Consider ValidateSet for limited options
+ - Enable tab completion where possible
+
+- **Switch Parameters:**
+ - Use [switch] for boolean flags
+ - Avoid $true/$false parameters
+ - Default to $false when omitted
+ - Use clear action names
+
+### Example
+
+```powershell
+function Set-ResourceConfiguration {
+ [CmdletBinding()]
+ param(
+ [Parameter(Mandatory)]
+ [string]$Name,
+
+ [Parameter()]
+ [ValidateSet('Dev', 'Test', 'Prod')]
+ [string]$Environment = 'Dev',
+
+ [Parameter()]
+ [switch]$Force,
+
+ [Parameter()]
+ [ValidateNotNullOrEmpty()]
+ [string[]]$Tags
+ )
+
+ process {
+ # Logic here
+ }
+}
+```
+
+## Pipeline and Output
+
+- **Pipeline Input:**
+ - Use `ValueFromPipeline` for direct object input
+ - Use `ValueFromPipelineByPropertyName` for property mapping
+ - Implement Begin/Process/End blocks for pipeline handling
+ - Document pipeline input requirements
+
+- **Output Objects:**
+ - Return rich objects, not formatted text
+ - Use PSCustomObject for structured data
+ - Avoid Write-Host for data output
+ - Enable downstream cmdlet processing
+
+- **Pipeline Streaming:**
+ - Output one object at a time
+ - Use process block for streaming
+ - Avoid collecting large arrays
+ - Enable immediate processing
+
+- **PassThru Pattern:**
+ - Default to no output for action cmdlets
+ - Implement `-PassThru` switch for object return
+ - Return modified/created object with `-PassThru`
+ - Use verbose/warning for status updates
+
+### Example
+
+```powershell
+function Update-ResourceStatus {
+ [CmdletBinding()]
+ param(
+ [Parameter(Mandatory, ValueFromPipeline, ValueFromPipelineByPropertyName)]
+ [string]$Name,
+
+ [Parameter(Mandatory)]
+ [ValidateSet('Active', 'Inactive', 'Maintenance')]
+ [string]$Status,
+
+ [Parameter()]
+ [switch]$PassThru
+ )
+
+ begin {
+ Write-Verbose 'Starting resource status update process'
+ $timestamp = Get-Date
+ }
+
+ process {
+ # Process each resource individually
+ Write-Verbose "Processing resource: $Name"
+
+ $resource = [PSCustomObject]@{
+ Name = $Name
+ Status = $Status
+ LastUpdated = $timestamp
+ UpdatedBy = $env:USERNAME
+ }
+
+ # Only output if PassThru is specified
+ if ($PassThru.IsPresent) {
+ Write-Output $resource
+ }
+ }
+
+ end {
+ Write-Verbose 'Resource status update process completed'
+ }
+}
+```
+
+## Error Handling and Safety
+
+- **ShouldProcess Implementation:**
+ - Use `[CmdletBinding(SupportsShouldProcess = $true)]`
+ - Set appropriate `ConfirmImpact` level
+ - Call `$PSCmdlet.ShouldProcess()` for system changes
+ - Use `ShouldContinue()` for additional confirmations
+
+- **Message Streams:**
+ - `Write-Verbose` for operational details with `-Verbose`
+ - `Write-Warning` for warning conditions
+ - `Write-Error` for non-terminating errors
+ - `throw` for terminating errors
+ - Avoid `Write-Host` except for user interface text
+
+- **Error Handling Pattern:**
+ - Use try/catch blocks for error management
+ - Set appropriate ErrorAction preferences
+ - Return meaningful error messages
+ - Use ErrorVariable when needed
+ - Include proper terminating vs non-terminating error handling
+ - In advanced functions with `[CmdletBinding()]`, prefer `$PSCmdlet.WriteError()` over `Write-Error`
+ - In advanced functions with `[CmdletBinding()]`, prefer `$PSCmdlet.ThrowTerminatingError()` over `throw`
+ - Construct proper ErrorRecord objects with category, target, and exception details
+
+- **Non-Interactive Design:**
+ - Accept input via parameters
+ - Avoid `Read-Host` in scripts
+ - Support automation scenarios
+ - Document all required inputs
+
+### Example
+
+```powershell
+function Remove-UserAccount {
+ [CmdletBinding(SupportsShouldProcess = $true, ConfirmImpact = 'High')]
+ param(
+ [Parameter(Mandatory, ValueFromPipeline)]
+ [ValidateNotNullOrEmpty()]
+ [string]$Username,
+
+ [Parameter()]
+ [switch]$Force
+ )
+
+ begin {
+ Write-Verbose 'Starting user account removal process'
+ $ErrorActionPreference = 'Stop'
+ }
+
+ process {
+ try {
+ # Validation
+ if (-not (Test-UserExists -Username $Username)) {
+ $errorRecord = [System.Management.Automation.ErrorRecord]::new(
+ [System.Exception]::new("User account '$Username' not found"),
+ 'UserNotFound',
+ [System.Management.Automation.ErrorCategory]::ObjectNotFound,
+ $Username
+ )
+ $PSCmdlet.WriteError($errorRecord)
+ return
+ }
+
+ # Confirmation
+ $shouldProcessMessage = "Remove user account '$Username'"
+ if ($Force -or $PSCmdlet.ShouldProcess($Username, $shouldProcessMessage)) {
+ Write-Verbose "Removing user account: $Username"
+
+ # Main operation
+ Remove-ADUser -Identity $Username -ErrorAction Stop
+ Write-Warning "User account '$Username' has been removed"
+ }
+ } catch [Microsoft.ActiveDirectory.Management.ADException] {
+ $errorRecord = [System.Management.Automation.ErrorRecord]::new(
+ $_.Exception,
+ 'ActiveDirectoryError',
+ [System.Management.Automation.ErrorCategory]::NotSpecified,
+ $Username
+ )
+ $PSCmdlet.ThrowTerminatingError($errorRecord)
+ } catch {
+ $errorRecord = [System.Management.Automation.ErrorRecord]::new(
+ $_.Exception,
+ 'UnexpectedError',
+ [System.Management.Automation.ErrorCategory]::NotSpecified,
+ $Username
+ )
+ $PSCmdlet.ThrowTerminatingError($errorRecord)
+ }
+ }
+
+ end {
+ Write-Verbose 'User account removal process completed'
+ }
+}
+```
+
+## Documentation and Style
+
+- **Comment-Based Help:** Include comment-based help for any public-facing function or cmdlet. Inside the function, add a `<# ... #>` help comment with at least:
+ - `.SYNOPSIS` Brief description
+ - `.DESCRIPTION` Detailed explanation
+ - `.EXAMPLE` sections with practical usage
+ - `.PARAMETER` descriptions
+ - `.OUTPUTS` Type of output returned
+ - `.NOTES` Additional information
+
+- **Consistent Formatting:**
+ - Follow consistent PowerShell style
+ - Use proper indentation (4 spaces recommended)
+ - Opening braces on same line as statement
+ - Closing braces on new line
+ - Use line breaks after pipeline operators
+ - PascalCase for function and parameter names
+ - Avoid unnecessary whitespace
+
+- **Pipeline Support:**
+ - Implement Begin/Process/End blocks for pipeline functions
+ - Use ValueFromPipeline where appropriate
+ - Support pipeline input by property name
+ - Return proper objects, not formatted text
+
+- **Avoid Aliases:** Use full cmdlet names and parameters
+ - Avoid using aliases in scripts (e.g., use Get-ChildItem instead of gci); aliases are acceptable for interactive shell use.
+ - Use `Where-Object` instead of `?` or `where`
+ - Use `ForEach-Object` instead of `%`
+ - Use `Get-ChildItem` instead of `ls` or `dir`
+
+## Full Example: End-to-End Cmdlet Pattern
+
+```powershell
+function New-Resource {
+ [CmdletBinding(SupportsShouldProcess = $true, ConfirmImpact = 'Medium')]
+ param(
+ [Parameter(Mandatory = $true,
+ ValueFromPipeline = $true,
+ ValueFromPipelineByPropertyName = $true)]
+ [ValidateNotNullOrEmpty()]
+ [string]$Name,
+
+ [Parameter()]
+ [ValidateSet('Development', 'Production')]
+ [string]$Environment = 'Development'
+ )
+
+ begin {
+ Write-Verbose 'Starting resource creation process'
+ }
+
+ process {
+ try {
+ if ($PSCmdlet.ShouldProcess($Name, 'Create new resource')) {
+ # Resource creation logic here
+ Write-Output ([PSCustomObject]@{
+ Name = $Name
+ Environment = $Environment
+ Created = Get-Date
+ })
+ }
+ } catch {
+ $errorRecord = [System.Management.Automation.ErrorRecord]::new(
+ $_.Exception,
+ 'ResourceCreationFailed',
+ [System.Management.Automation.ErrorCategory]::NotSpecified,
+ $Name
+ )
+ $PSCmdlet.ThrowTerminatingError($errorRecord)
+ }
+ }
+
+ end {
+ Write-Verbose 'Completed resource creation process'
+ }
+}
+```
diff --git a/.github/instructions/prompt.instructions.md b/.github/instructions/prompt.instructions.md
new file mode 100644
index 000000000..a232edb97
--- /dev/null
+++ b/.github/instructions/prompt.instructions.md
@@ -0,0 +1,88 @@
+---
+description: 'Guidelines for creating high-quality prompt files for GitHub Copilot'
+applyTo: '**/*.prompt.md'
+---
+
+# Copilot Prompt Files Guidelines
+
+Instructions for creating effective and maintainable prompt files that guide GitHub Copilot in delivering consistent, high-quality outcomes across any repository.
+
+## Scope and Principles
+- Target audience: maintainers and contributors authoring reusable prompts for Copilot Chat.
+- Goals: predictable behaviour, clear expectations, minimal permissions, and portability across repositories.
+- Primary references: VS Code documentation on prompt files and organization-specific conventions.
+
+## Frontmatter Requirements
+
+Every prompt file should include YAML frontmatter with the following fields:
+
+### Required/Recommended Fields
+
+| Field | Required | Description |
+|-------|----------|-------------|
+| `description` | Recommended | A short description of the prompt (single sentence, actionable outcome) |
+| `name` | Optional | The name shown after typing `/` in chat. Defaults to filename if not specified |
+| `agent` | Recommended | The agent to use: `ask`, `edit`, `agent`, or a custom agent name. Defaults to current agent |
+| `model` | Optional | The language model to use. Defaults to currently selected model |
+| `tools` | Optional | List of tool/tool set names available for this prompt |
+| `argument-hint` | Optional | Hint text shown in chat input to guide user interaction |
+
+### Guidelines
+
+- Use consistent quoting (single quotes recommended) and keep one field per line for readability and version control clarity
+- If `tools` are specified and current agent is `ask` or `edit`, the default agent becomes `agent`
+- Preserve any additional metadata (`language`, `tags`, `visibility`, etc.) required by your organization
+
+## File Naming and Placement
+- Use kebab-case filenames ending with `.prompt.md` and store them under `.github/prompts/` unless your workspace standard specifies another directory.
+- Provide a short filename that communicates the action (for example, `generate-readme.prompt.md` rather than `prompt1.prompt.md`).
+
+## Body Structure
+- Start with an `#` level heading that matches the prompt intent so it surfaces well in Quick Pick search.
+- Organize content with predictable sections. Recommended baseline: `Mission` or `Primary Directive`, `Scope & Preconditions`, `Inputs`, `Workflow` (step-by-step), `Output Expectations`, and `Quality Assurance`.
+- Adjust section names to fit the domain, but retain the logical flow: why → context → inputs → actions → outputs → validation.
+- Reference related prompts or instruction files using relative links to aid discoverability.
+
+## Input and Context Handling
+- Use `${input:variableName[:placeholder]}` for required values and explain when the user must supply them. Provide defaults or alternatives where possible.
+- Call out contextual variables such as `${selection}`, `${file}`, `${workspaceFolder}` only when they are essential, and describe how Copilot should interpret them.
+- Document how to proceed when mandatory context is missing (for example, “Request the file path and stop if it remains undefined”).
+
+## Tool and Permission Guidance
+- Limit `tools` to the smallest set that enables the task. List them in the preferred execution order when the sequence matters.
+- If the prompt inherits tools from a chat mode, mention that relationship and state any critical tool behaviours or side effects.
+- Warn about destructive operations (file creation, edits, terminal commands) and include guard rails or confirmation steps in the workflow.
+
+## Instruction Tone and Style
+- Write in direct, imperative sentences targeted at Copilot (for example, “Analyze”, “Generate”, “Summarize”).
+- Keep sentences short and unambiguous, following Google Developer Documentation translation best practices to support localization.
+- Avoid idioms, humor, or culturally specific references; favor neutral, inclusive language.
+
+## Output Definition
+- Specify the format, structure, and location of expected results (for example, “Create an architecture decision record file using the template below, such as `docs/architecture-decisions/record-XXXX.md`).
+- Include success criteria and failure triggers so Copilot knows when to halt or retry.
+- Provide validation steps—manual checks, automated commands, or acceptance criteria lists—that reviewers can execute after running the prompt.
+
+## Examples and Reusable Assets
+- Embed Good/Bad examples or scaffolds (Markdown templates, JSON stubs) that the prompt should produce or follow.
+- Maintain reference tables (capabilities, status codes, role descriptions) inline to keep the prompt self-contained. Update these tables when upstream resources change.
+- Link to authoritative documentation instead of duplicating lengthy guidance.
+
+## Quality Assurance Checklist
+- [ ] Frontmatter fields are complete, accurate, and least-privilege.
+- [ ] Inputs include placeholders, default behaviours, and fallbacks.
+- [ ] Workflow covers preparation, execution, and post-processing without gaps.
+- [ ] Output expectations include formatting and storage details.
+- [ ] Validation steps are actionable (commands, diff checks, review prompts).
+- [ ] Security, compliance, and privacy policies referenced by the prompt are current.
+- [ ] Prompt executes successfully in VS Code (`Chat: Run Prompt`) using representative scenarios.
+
+## Maintenance Guidance
+- Version-control prompts alongside the code they affect; update them when dependencies, tooling, or review processes change.
+- Review prompts periodically to ensure tool lists, model requirements, and linked documents remain valid.
+- Coordinate with other repositories: when a prompt proves broadly useful, extract common guidance into instruction files or shared prompt packs.
+
+## Additional Resources
+- [Prompt Files Documentation](https://code.visualstudio.com/docs/copilot/customization/prompt-files#_prompt-file-format)
+- [Awesome Copilot Prompt Files](https://github.com/github/awesome-copilot/tree/main/prompts)
+- [Tool Configuration](https://code.visualstudio.com/docs/copilot/chat/chat-agent-mode#_agent-mode-tools)
diff --git a/.github/prompts/create-commit-title.prompt.md b/.github/prompts/create-commit-title.prompt.md
new file mode 100644
index 000000000..bfdf81ba1
--- /dev/null
+++ b/.github/prompts/create-commit-title.prompt.md
@@ -0,0 +1,50 @@
+---
+agent: 'agent'
+model: 'GPT-5.1-Codex-Max'
+description: 'Generate an 80-character git commit title for the local diff'
+---
+
+# Generate Commit Title
+
+## Purpose
+Provide a single-line, ready-to-paste git commit title (<= 80 characters) that reflects the most important local changes since `HEAD`.
+
+## Input to collect
+- Run exactly one command to view the local diff:
+ ```@terminal
+ git diff HEAD
+ ```
+
+## How to decide the title
+1. From the diff, find the dominant area (e.g., `Samples/AppLifecycle/*`, `docs/**`) and the change type (new sample, bug fix, docs update, config tweak).
+2. Draft an imperative, plain-ASCII title that:
+ - Mentions the primary feature/sample when obvious (e.g., `AppLifecycle:` or `Docs:`)
+ - Stays within 80 characters and has no trailing punctuation
+
+## Final output
+- Reply with only the commit title on a single line—no extra text.
+
+## PR title convention (when asked)
+Use Conventional Commits style:
+
+`(): `
+
+**Allowed types**
+- feat, fix, docs, refactor, perf, test, build, ci, chore, sample
+
+**Scope rules**
+- Use a short, WindowsAppSDK-Samples-focused scope (one word preferred). Common scopes:
+ - Core: `docs`, `build`, `ci`, `templates`, `repo`
+ - Features: `applifecycle`, `activation`, `instancing`, `restart`, `notifications`, `push`, `app-notifications`, `windowing`, `widgets`, `mica`, `textrendering`, `resourcemanagement`, `deployment`, `installer`, `unpackaged`, `islands`, `composition`, `input`, `customcontrols`, `backgroundtask`, `scenegraph`, `photoeditor`, `windowsai`, `windowsml`
+- If unclear, pick the closest feature or sample area; omit only if unavoidable
+
+**Summary rules**
+- Imperative, present tense (“add”, “update”, “remove”, “fix”)
+- Keep it <= 72 characters when possible; be specific, avoid “misc changes”
+
+**Examples**
+- `feat(applifecycle): add activation sample for file type associations`
+- `fix(notifications): correct push notification channel registration`
+- `docs(windowing): document presenter configuration options`
+- `build(ci): add SamplesCI pipeline for new feature`
+- `sample(widgets): add weather widget implementation`
diff --git a/.github/prompts/create-pr-summary.prompt.md b/.github/prompts/create-pr-summary.prompt.md
new file mode 100644
index 000000000..20201c477
--- /dev/null
+++ b/.github/prompts/create-pr-summary.prompt.md
@@ -0,0 +1,25 @@
+---
+agent: 'agent'
+model: 'GPT-5.1-Codex-Max'
+description: 'Generate a WindowsAppSDK-Samples-ready pull request description from the local diff'
+---
+
+# Generate PR Summary
+
+**Goal:** Produce a ready-to-paste PR title and description that follows WindowsAppSDK-Samples conventions by comparing the current branch against a user-selected target branch.
+
+**Repo guardrails:**
+- Treat `docs/pull_request_template.md` as the single source of truth; load it at runtime instead of embedding hardcoded content in this prompt.
+- Preserve section order from the template but only surface checklist lines that are relevant for the detected changes, filling them with `[x]`/`[ ]` as appropriate.
+- Cite touched paths with inline backticks, matching the guidance in `.github/copilot-instructions.md`.
+- Call out build/test validation explicitly: state which platforms (x64, x86, ARM64) and configurations (Debug, Release) were tested, or why testing was not applicable.
+
+**Workflow:**
+1. Determine the target branch from user context; default to `main` when no branch is supplied.
+2. Run `git status --short` once to surface uncommitted files that may influence the summary.
+3. Run `git diff ...HEAD` a single time to review the detailed changes. Only when confidence stays low dig deeper with focused calls such as `git diff ...HEAD -- `.
+4. From the diff, capture impacted areas (features, samples), key file changes, behavioral risks, and noteworthy edge cases.
+5. Confirm validation: list builds and tests executed with results, or state why they were skipped in line with repo guidance.
+6. Load `docs/pull_request_template.md`, mirror its section order, and populate it with the gathered facts. Include only relevant checklist entries, marking them `[x]/[ ]` and noting any intentional omissions as "N/A".
+7. Present the filled template inside a fenced ```markdown code block with no extra commentary so it is ready to paste into a PR, clearly flagging any placeholders that still need user input.
+8. Prepend the PR title above the filled template. Construct the PR title using the same Conventional Commit type/scope rules defined for commit titles in `.github/prompts/create-commit-title.prompt.md` (this repo intentionally applies the commit-title convention to PR titles); pick the dominant component from the diff and keep the title concise and imperative.
diff --git a/.github/prompts/fix-issue.prompt.md b/.github/prompts/fix-issue.prompt.md
new file mode 100644
index 000000000..cd4b154e1
--- /dev/null
+++ b/.github/prompts/fix-issue.prompt.md
@@ -0,0 +1,68 @@
+---
+agent: 'agent'
+model: 'GPT-5.1-Codex-Max'
+description: 'Execute the fix for a GitHub issue using the previously generated implementation plan'
+---
+
+# Fix GitHub Issue
+
+## Dependencies
+Source review prompt (for generating the implementation plan if missing):
+- .github/prompts/review-issue.prompt.md
+
+Required plan file (single source of truth):
+- Generated Files/issueReview/{{issue_number}}/implementation-plan.md
+
+## Dependency Handling
+1) If `implementation-plan.md` exists → proceed.
+2) If missing → run the review prompt:
+ - Invoke: `.github/prompts/review-issue.prompt.md`
+ - Pass: `issue_number={{issue_number}}`
+ - Then re-check for `implementation-plan.md`.
+3) If still missing → stop and generate:
+ - `Generated Files/issueFix/{{issue_number}}/manual-steps.md` containing:
+ “implementation-plan.md not found; please run .github/prompts/review-issue.prompt.md for #{{issue_number}}.”
+
+# GOAL
+For **#{{issue_number}}**:
+- Use implementation-plan.md as the single authority.
+- Apply code and test changes directly in the repository.
+- Produce a PR-ready description.
+
+# OUTPUT FILES
+1) Generated Files/issueFix/{{issue_number}}/pr-description.md
+2) Generated Files/issueFix/{{issue_number}}/manual-steps.md # only if human interaction or external setup is required
+
+# EXECUTION RULES
+1) Read implementation-plan.md and execute:
+ - Layers & Files → edit/create as listed
+ - Pattern Choices → follow repository conventions
+ - Fundamentals (perf, security, compatibility, accessibility)
+ - Logging & Exceptions
+ - Telemetry (only if explicitly included in the plan)
+ - Risks & Mitigations
+ - Tests to Add
+2) Locate affected files via `rg` or `git grep`.
+3) Add/update tests to enforce the fixed behavior.
+4) If any ambiguity exists, add:
+// TODO(Human input needed):
+5) Verify locally: build & tests run successfully.
+
+# PR DESCRIPTION
+Generate the PR description by invoking `.github/prompts/create-pr-summary.prompt.md`.
+Append `Closes #{{issue_number}}` to the generated description.
+Save the result to `Generated Files/issueFix/{{issue_number}}/pr-description.md`.
+
+# manual-steps.md (only if needed)
+- List required human actions: secrets, config, approvals, missing info, or code comments requiring human decisions.
+
+# IMPORTANT
+- Apply code and tests directly; do not produce patch files.
+- Follow implementation-plan.md as the source of truth.
+- Insert comments for human review where a decision or input is required.
+- Use repository conventions and deterministic, minimal changes.
+
+# FINALIZE
+- Write pr-description.md
+- Write manual-steps.md only if needed
+- Print concise success message or note items requiring human interaction
diff --git a/.github/prompts/review-issue.prompt.md b/.github/prompts/review-issue.prompt.md
new file mode 100644
index 000000000..769823fd3
--- /dev/null
+++ b/.github/prompts/review-issue.prompt.md
@@ -0,0 +1,160 @@
+---
+agent: 'agent'
+model: 'GPT-5.1-Codex-Max'
+description: 'Review a GitHub issue, score it (0-100), and generate an implementation plan'
+---
+
+# Review GitHub Issue
+
+## Goal
+For **#{{issue_number}}** produce:
+1) `Generated Files/issueReview/{{issue_number}}/overview.md`
+2) `Generated Files/issueReview/{{issue_number}}/implementation-plan.md`
+
+## Inputs
+Figure out required inputs {{issue_number}} from the invocation context; if anything is missing, ask for the value or note it as a gap.
+
+# CONTEXT (brief)
+Ground evidence using `gh issue view {{issue_number}} --json number,title,body,author,createdAt,updatedAt,state,labels,milestone,reactions,comments,linkedPullRequests`, and download images to better understand the issue context.
+Locate source code in the current workspace; feel free to use `rg`/`git grep`. Link related issues and PRs.
+
+# OVERVIEW.MD
+## Summary
+Issue, state, milestone, labels. **Signals**: 👍/❤️/👎, comment count, last activity, linked PRs.
+
+## At-a-Glance Score Table
+Present all ratings in a compact table for quick scanning:
+
+| Dimension | Score | Assessment | Key Drivers |
+|-----------|-------|------------|-------------|
+| **A) Business Importance** | X/100 | Low/Medium/High | Top 2 factors with scores |
+| **B) Community Excitement** | X/100 | Low/Medium/High | Top 2 factors with scores |
+| **C) Technical Feasibility** | X/100 | Low/Medium/High | Top 2 factors with scores |
+| **D) Requirement Clarity** | X/100 | Low/Medium/High | Top 2 factors with scores |
+| **Overall Priority** | X/100 | Low/Medium/High/Critical | Average or weighted summary |
+| **Effort Estimate** | X days (T-shirt) | XS/S/M/L/XL/XXL/Epic | Type: bug/feature/chore |
+| **Similar Issues Found** | X open, Y closed | — | Quick reference to related work |
+| **Potential Assignees** | @username, @username | — | Top contributors to module |
+
+**Assessment bands**: 0-25 Low, 26-50 Medium, 51-75 High, 76-100 Critical
+
+## Ratings (0–100) — add evidence & short rationale
+### A) Business Importance
+- Labels (priority/security/regression): **≤35**
+- Milestone/roadmap: **≤25**
+- Customer/contract impact: **≤20**
+- Unblocks/platform leverage: **≤20**
+### B) Community Excitement
+- 👍+❤️ normalized: **≤45**
+- Comment volume & unique participants: **≤25**
+- Recent activity (≤30d): **≤15**
+- Duplicates/related issues: **≤15**
+### C) Technical Feasibility
+- Contained surface/clear seams: **≤30**
+- Existing patterns/utilities: **≤25**
+- Risk (perf/sec/compat) manageable: **≤25**
+- Testability & CI support: **≤20**
+### D) Requirement Clarity
+- Behavior/repro/constraints: **≤60**
+- Non-functionals (perf/sec/i18n/a11y): **≤25**
+- Decision owners/acceptance signals: **≤15**
+
+## Effort
+Days + **T-shirt** (XS 0.5–1d, S 1–2, M 2–4, L 4–7, XL 7–14, XXL 14–30, Epic >30).
+Type/level: bug/feature/chore/docs/refactor/test-only; severity/value tier.
+
+## Suggested Actions
+Provide actionable recommendations for issue triage and assignment:
+
+### A) Requirement Clarification (if Clarity score <50)
+**When Requirement Clarity (Dimension D) is Medium or Low:**
+- Identify specific gaps in issue description: missing repro steps, unclear expected behavior, undefined acceptance criteria, missing non-functional requirements
+- Draft 3-5 clarifying questions to post as issue comment
+- Suggest additional information needed: screenshots, logs, environment details, OS version, Windows App SDK version, Visual Studio version, error messages
+- If behavior is ambiguous, propose 2-3 interpretation scenarios and ask reporter to confirm
+- Example questions:
+ - "Can you provide exact steps to reproduce this issue?"
+ - "What is the expected behavior vs. what you're actually seeing?"
+ - "Does this happen on Windows 10, 11, or both?"
+ - "Can you attach a screenshot or screen recording?"
+
+### B) Correct Label Suggestions
+- Analyze issue type, sample area, and severity to suggest missing or incorrect labels
+- Recommend labels from: `bug`, `enhancement`, `documentation`, `question`, `duplicate`, `needs-triage`, `needs-author-feedback`, `sample-`, etc.
+- If Requirement Clarity is low (<50), add `needs-author-feedback` label
+- If current labels are incorrect or incomplete, provide specific label changes with rationale
+
+### C) Find Similar Issues & Past Fixes
+- Search for similar issues using `gh issue list --search "keywords" --state all --json number,title,state,closedAt`
+- Identify patterns: duplicate issues, related bugs, or similar feature requests
+- For closed issues, find linked PRs that fixed them: check `linkedPullRequests` in issue data
+- Provide 3-5 examples of similar issues with format: `# - (closed by PR #)` or `(still open)`
+
+### D) Identify Subject Matter Experts
+- Use git blame/log to find who fixed similar issues in the past
+- Search for PR authors who touched relevant files: `git log --all --format='%aN' -- | sort | uniq -c | sort -rn | head -5`
+- Check issue/PR history for frequent contributors to the affected module
+- Suggest 2-3 potential assignees with context: `@ - ` (e.g., "fixed similar sample issue in #12345", "maintains AppLifecycle samples")
+
+### E) Semantic Search for Related Work
+- Use semantic_search tool to find similar issues, code patterns, or past discussions
+- Search queries should include: issue keywords, module names, error messages, feature descriptions
+- Cross-reference semantic results with GitHub issue search for comprehensive coverage
+
+**Output format for Suggested Actions section in overview.md:**
+```markdown
+## Suggested Actions
+
+### Clarifying Questions (if Clarity <50)
+Post these questions as issue comment to gather missing information:
+1.
+2.
+3.
+
+**Recommended label**: `Needs-Author-Feedback`
+
+### Label Recommendations
+- Add: `