Copilot instructions

1---
2description: "Guidance for GitHub Copilot when working on the .NET MAUI repository."
3---
4 
5# GitHub Copilot Development Environment Instructions
6 
7This document provides specific guidance for GitHub Copilot when working on the .NET MAUI repository. It serves as context for understanding the project structure, development workflow, and best practices.
8 
9## Code Review Instructions
10 
11When performing a code review on PRs that change functional code, run the pr-finalize skill to verify that the PR title and description accurately match the actual implementation. This ensures proper documentation and helps maintain high-quality commit messages.
12 
13## Repository Overview
14 
15**.NET MAUI** is a cross-platform framework for creating mobile and desktop applications with C# and XAML. This repository contains the core framework code that enables development for Android, iOS, iPadOS, macOS, and Windows from a single shared codebase.
16 
17### Key Technologies
18 
19- **.NET SDK** - Version is **ALWAYS** defined in `global.json` at repository root
20  - **main branch**: Latest stable .NET version
21  - **Feature branches**: Each `netN.0` branch targets the .NET N SDK. By convention, the highest `netN.0` branch is the current development branch for new features and API changes.
22- **Cake build system** for compilation and packaging (`dotnet cake`)
23- **MSBuild** with custom build tasks (must build `Microsoft.Maui.BuildTasks.slnf` first)
24- **Testing frameworks**:
25  - **xUnit** - Unit tests (`*.UnitTests.csproj`)
26  - **NUnit** - UI tests (`TestCases.Shared.Tests`)
27  - **Appium WebDriver** - UI test automation
28 
29## Development Environment Setup
30 
31This guidance assumes:
32- Repository is already cloned and tools are restored (`dotnet tool restore` completed)
33- Build tasks are compiled (`Microsoft.Maui.BuildTasks.slnf` built successfully)
34- Correct .NET SDK version installed (verify with `dotnet --version` against `global.json`)
35 
36### Platform-Specific Requirements
37 
38- **Android**: OpenJDK 17 + Android SDK (install via `android` command after `dotnet tool restore`)
39- **iOS/macOS**: Xcode (current stable version)
40- **Windows**: Windows SDK
41 
42## Project Structure
43 
44### Important Directories
45- `src/Core/` - Core MAUI framework code
46- `src/Controls/` - UI controls and components
47- `src/Essentials/` - Platform APIs and essentials
48- `src/TestUtils/` - Testing utilities and infrastructure
49- `docs/` - Development documentation
50- `eng/` - Build engineering and tooling
51- `.github/` - GitHub workflows and configuration
52 
53### Platform-Specific Code Organization
54- **Android** specific code is inside folders labeled `Android`
55- **iOS** specific code is inside folders labeled `iOS`
56- **MacCatalyst** specific code is inside folders named `MacCatalyst`
57- **Windows** specific code is inside folders named `Windows`
58 
59### Platform-Specific File Extensions
60 
61Platform-specific files use naming conventions to control compilation:
62 
63**File extension patterns**:
64- `.windows.cs` - Windows TFM only
65- `.android.cs` - Android TFM only
66- `.ios.cs` - iOS and MacCatalyst TFMs (both)
67- `.maccatalyst.cs` - MacCatalyst TFM only (does NOT compile for iOS)
68 
69**Important**: Both `.ios.cs` and `.maccatalyst.cs` files compile for MacCatalyst. There is no precedence mechanism that excludes one when the other exists.
70 
71**Example**: If you have both `CollectionView.ios.cs` and `CollectionView.maccatalyst.cs`, both will compile for MacCatalyst builds. The `.maccatalyst.cs` file won't compile for iOS, but the `.ios.cs` file will compile for both iOS and MacCatalyst.
72 
73### Sample Projects
74 
75- `src/Controls/samples/Maui.Controls.Sample` - Full gallery sample with all controls and features
76- `src/Controls/samples/Maui.Controls.Sample.Sandbox` - Empty project for testing/reproduction
77- `src/Essentials/samples/Essentials.Sample` - Essentials API demonstrations (non-UI MAUI APIs)
78- `src/BlazorWebView/samples/` - BlazorWebView sample applications
79 
80## Development Workflow
81 
82### Testing
83 
84Major test projects:
85- **Core**: `src/Core/tests/UnitTests/Core.UnitTests.csproj`
86- **Essentials**: `src/Essentials/test/UnitTests/Essentials.UnitTests.csproj`
87- **Controls**: `src/Controls/tests/Core.UnitTests/Controls.Core.UnitTests.csproj`
88- **XAML**: `src/Controls/tests/Xaml.UnitTests/Controls.Xaml.UnitTests.csproj`
89 
90Find all tests: `find . -name "*.UnitTests.csproj"`
91 
92### CI Pipelines (Azure DevOps)
93 
94When referencing or triggering CI pipelines, use these current pipeline names:
95 
96| Pipeline | Name | Purpose |
97|----------|------|---------|
98| Overall CI | `maui-pr` | Full PR validation build |
99| Device Tests | `maui-pr-devicetests` | Helix-based device tests |
100| UI Tests | `maui-pr-uitests` | Appium-based UI tests |
101 
102**⚠️ Old pipeline names** (e.g., `MAUI-UITests-public`, `MAUI-public`) are **outdated** and should NOT be used. Always use the names above.
103 
104### Investigating CI Failures
105 
106**🚨 ALWAYS use the `azdo-build-investigator` skill when investigating CI failures or assessing merge readiness.** Its instructions direct you to invoke the `ci-analysis` skill first for the core investigation workflow, then apply MAUI-specific corrections (correct pipeline names, XHarness quirks, binlog guidance).
107 
108Do NOT default to manually querying AzDO APIs or rely solely on `gh pr checks` pass/fail counts.
109 
110**When to use it:**
111- "How does CI look?" / "Is CI green?" / "Can we merge?"
112- "What's failing?" / "Are these known failures?"
113- "Is this PR safe to merge?" / "Any CI concerns?"
114- After any PR push to verify the build
115 
116**Verifying specific tests:** When asked "did test X pass?" or "did the new test run?", query the **actual AzDO test results** — do NOT infer whether a test ran by inspecting code attributes. Class-level traits, base class categories, and assembly-level attributes can all cause a test to run even when the method itself has no visible category. Check the evidence, not the code.
117 
118**Anti-pattern:** Writing ad-hoc scripts to parse AzDO build timelines. The skills handle Helix work item details, known issue cross-referencing, and test result aggregation that manual approaches miss.
119 
120### Gradle / Maven Dependency Failures (CFSClean)
121 
122The official CI build uses CFSClean network isolation which blocks `repo.maven.apache.org`. All Gradle/Maven dependencies resolve through the `dotnet-public-maven` Azure Artifacts feed.
123 
124**If CI fails with Gradle 401 errors** like `"No local versions of package"` or `"Please provide authentication to save package from upstream"`, it means a Maven package hasn't been ingested into the feed yet. **Fix:** run `./eng/ingest-maven-deps.sh` locally to pre-populate the feed. See `src/Core/AndroidNative/settings.gradle` for details.
125 
126**Do NOT upgrade Gradle past 8.x** — the Android SDK's `net.android.init.gradle.kts` is incompatible with Gradle 9.x (`dotnet/android#10738`).
127 
128### Code Formatting
129 
130Always format code before committing:
131 
132```bash
133dotnet format Microsoft.Maui.sln --no-restore --exclude Templates/src --exclude-diagnostics CA1822
134```
135 
136## Contribution Guidelines
137 
138### Handling Existing PRs for Assigned Issues
139 
140**🚨 CRITICAL REQUIREMENT: Always develop your own solution first, then compare with existing PRs.**
141 
1421. **Develop your own solution first** - Analyze the issue independently and design your approach without looking at existing PRs
1432. **Search for existing PRs** - After developing your solution, search for open PRs addressing the same issue
1443. **Compare and evaluate** - Examine existing PR approaches and decide which solution better addresses the issue
1454. **Document your decision** - In your PR description, compare your solution to existing PRs and explain why you chose your approach, including concerns with alternatives
1465. **Improve either solution** - Whether using your solution or an existing one, enhance with better tests, code quality, error handling, or documentation
147 
148### Auto-Generated Files (Never Commit)
149 
150These files are auto-generated and must NOT be committed:
151- `cgmanifest.json` - Generated during CI builds
152- `templatestrings.json` - Auto-generated localization
153 
154**For AI agents:** Always reset changes to these files before committing.
155 
156### PublicAPI.Unshipped.txt File Management
157 
158When working with public API changes:
159- **Never disable analyzers** to bypass PublicAPI.Unshipped.txt issues
160- **Always add correct API entries** to PublicAPI.Unshipped.txt files
161- **Use `dotnet format analyzers`** if having trouble
162- **If files are incorrect**: Revert all changes, then add only the necessary new API entries
163 
164### Branching
165- `main` - For bug fixes without API changes
166- The highest `netN.0` branch (by convention) - For new features and API changes. To find it, run `git fetch origin` then: `git for-each-ref --sort=-version:refname --count=1 --format='%(refname:lstrip=3)' refs/remotes/origin/net*.0`
167 
168### Git Workflow (Copilot CLI Rules)
169 
170**🚨 CRITICAL Git Rules for Copilot CLI:**
171 
1721. **NEVER commit directly to `main`** - Always create a feature branch for your work. Direct commits to `main` are strictly prohibited.
173 
1742. **When amending an existing PR, work on the PR's branch directly** - Do NOT create a separate branch off a PR branch. The PR branch already IS a feature branch. Creating a new branch off it means CI won't run on the original PR, defeating the purpose. Use `gh pr checkout` to switch to the PR branch, make your changes, commit, **then** ask before pushing so the user can review locally first.
175 
1763. **Do NOT rebase, squash, or force-push** unless explicitly requested by the user. These operations rewrite git history and can cause problems for other contributors. Default behavior should be regular commits and pushes.
177 
178**Safe Git Workflow:**
179```bash
180# Create a feature branch (NEVER work directly on main)
181git checkout -b feature/issue-12345
182 
183# Make commits normally
184git add .
185git commit -m "Fix: Description of the change"
186 
187# Push to remote (for new branches)
188git push -u origin feature/issue-12345
189 
190# For subsequent pushes on the same branch
191git push
192```
193 
194**When asked to update an existing PR:**
195```bash
196# Check out the PR branch directly (do NOT create a new branch off it)
197gh pr checkout 12345
198 
199# Make fixes and commit to the PR branch
200git add .
201git commit -m "Fix: Description of the change"
202```
2031. **STOP and ask the user** before pushing: "Changes are committed locally. Would you like me to push these changes to the PR?"
2042. Exception: If the user's instructions explicitly include pushing, proceed without asking.
205 
206### Documentation
207- Update XML documentation for public APIs
208- Follow existing code documentation patterns
209- Update relevant docs in `docs/` folder when needed
210 
211### Opening PRs
212 
213All PRs are required to have this at the top of the description:
214 
215```
216<!-- Please let the below note in for people that find this PR -->
217> [!NOTE]
218> Are you waiting for the changes in this PR to be merged?
219> It would be very helpful if you could [test the resulting artifacts](https://github.com/dotnet/maui/wiki/Testing-PR-Builds) from this PR and let us know in a comment if this change resolves your issue. Thank you!
220```
221 
222Always put that at the top, without the block quotes. Without it, users will NOT be able to try the PR and your work will have been in vain!
223 
224 
225 
226## Custom Agents and Skills
227 
228The repository includes specialized custom agents and reusable skills for specific tasks.
229 
230### Skills vs Agents
231 
232| Aspect | Skills | Agents |
233|--------|--------|--------|
234| **Invoke** | `/skill-name` or direct request | Delegate to agent |
235| **Output** | Analysis, recommendations | Actions, changes applied |
236| **Interaction** | Interactive discussion | Autonomous workflow |
237| **Example** | `/learn-from-pr` → recommendations | learn-from-pr agent → applies changes |
238 
239### Available Custom Agents
240 
2411. **pr** - Sequential 4-phase workflow for reviewing and working on PRs
242   - **Use when**: A PR already exists and needs review or work, OR an issue needs a fix
243   - **Capabilities**: PR review, test verification, fix exploration, alternative comparison
244   - **Trigger phrases**: "review PR #XXXXX", "work on PR #XXXXX", "fix issue #XXXXX", "continue PR #XXXXX"
245   - **Do NOT use for**: Just running tests manually → Use `sandbox-agent`
246 
2472. **write-tests-agent** - Agent for writing tests. Determines test type (UI vs XAML) and invokes the appropriate skill (`write-ui-tests`, `write-xaml-tests`)
248   - **Use when**: Creating new tests for issues or PRs
249   - **Capabilities**: Test type determination (UI and XAML), skill invocation, test verification
250   - **Trigger phrases**: "write tests for #XXXXX", "create tests", "add test coverage"
251 
2523. **sandbox-agent** - Specialized agent for working with the Sandbox app for testing, validation, and experimentation
253   - **Use when**: User wants to manually test PR functionality or reproduce issues
254   - **Capabilities**: Sandbox app setup, Appium-based manual testing, PR functional validation
255   - **Trigger phrases**: "test this PR", "validate PR #XXXXX in Sandbox", "reproduce issue #XXXXX", "try out in Sandbox"
256   - **Do NOT use for**: Code review (use pr agent), writing automated tests (use write-tests-agent)
257 
2584. **learn-from-pr** - Extracts lessons from PRs and applies improvements to the repository
259   - **Use when**: After complex PR, want to improve instruction files/skills based on lessons learned
260   - **Capabilities**: Analyzes PR, identifies failure modes, applies improvements to instruction files, skills, code comments
261   - **Trigger phrases**: "learn from PR #XXXXX and apply improvements", "improve repo based on what we learned", "update skills based on PR"
262   - **Output**: Applied changes to instruction files, skills, architecture docs, code comments
263   - **Do NOT use for**: Analysis only without applying changes → Use `/learn-from-pr` skill instead
264 
2655. **release-readiness-agent** - Assesses ship-readiness for a .NET MAUI release branch — both **SR** (`release/*-srN`) and **Preview** (`release/*-previewN`)
266   - **Use when**: A release (SR or Preview) is approaching ship date and you need a synthesized verdict with WorkIQ/MCP enrichment on top of the deterministic report — **or** for a portfolio question across all active releases ("status on releases", "what needs attention across releases") where the user may not know which releases exist
267   - **Capabilities**: Resolves the branch (SR or Preview) from natural language, picks the right script (`Get-ReleaseReadiness.ps1` for SR, `Get-PreviewReadiness.ps1` for Preview), enriches `rejected-from-sr` candidates with WorkIQ context (SR lane), patches `UNKNOWN` ship-check rows via MCP (`maestro_default_channels`, `maestro_builds`), presents an overall verdict
268   - **Trigger phrases**: "is SR7 ready to ship", "release readiness for release/10.0.1xx-sr7", "survey the SR8 branch", "how does net11 preview6 look", "is preview6 ready to cut", "release readiness for release/11.0.1xx-preview6" — **plus portfolio / cross-release questions with no specific release named**: "give me a status on releases", "release status overview", "what's the status across all releases", "what needs attention across releases", "what's next for MAUI releases"
269   - **Output**: Verdict (Ready / Conditionally Ready / Not Ready) + per-candidate classification (SR) or per-section table (Preview) + actionable next steps
270   - **Do NOT use for**: Programmatic / scripted consumers that just need the raw JSON — use the `release-readiness` skill directly. Reviewing a single PR (use **pr**). Running tests manually (use **sandbox-agent**).
271 
272### Reusable Skills
273 
274Skills are modular capabilities that can be invoked directly or used by agents. Located in `.github/skills/`:
275 
276#### User-Facing Skills
277 
2781. **pr-review** (`.github/skills/pr-review/SKILL.md`)
279   - **Purpose**: End-to-end PR review orchestrator — 3 phases: pr-preflight, try-fix, pr-report. Gate runs separately before this skill via Review-PR.ps1.
280   - **Trigger phrases**: "review PR #XXXXX", "work on PR #XXXXX", "fix issue #XXXXX", "continue PR #XXXXX"
281   - **Capabilities**: Multi-model fix exploration, alternative comparison, PR review recommendation
282   - **Do NOT use for**: Just running tests manually → Use `sandbox-agent`
283   - **Phase instructions** (in `.github/pr-review/`):
284     - `pr-preflight.md` — Context gathering from issue/PR
285     - `pr-report.md` — Final recommendation
286   - **Phase skill**: `try-fix` — Multi-model fix exploration
287   - **Note**: Gate (test verification) runs as a script step in `Review-PR.ps1` before this skill is invoked. Gate result is passed in the prompt.
288 
2892. **issue-triage** (`.github/skills/issue-triage/SKILL.md`)
290   - **Purpose**: Query and triage open issues that need milestones, labels, or investigation
291   - **Trigger phrases**: "find issues to triage", "show me old Android issues", "what issues need attention"
292   - **Scripts**: `init-triage-session.ps1`, `query-issues.ps1`, `record-triage.ps1`
293 
2942. **find-reviewable-pr** (`.github/skills/find-reviewable-pr/SKILL.md`)
295   - **Purpose**: Finds open PRs in dotnet/maui and dotnet/docs-maui that need review
296   - **Trigger phrases**: "find PRs to review", "show milestoned PRs", "find partner PRs"
297   - **Scripts**: `query-reviewable-prs.ps1`
298   - **Categories**: P/0, milestoned, partner, community, recent, docs-maui
299 
3003. **pr-finalize** (`.github/skills/pr-finalize/SKILL.md`)
301   - **Purpose**: Verifies PR title and description match actual implementation, AND performs code review for best practices before merge.
302   - **Trigger phrases**: "finalize PR #XXXXX", "check PR description for #XXXXX", "review commit message"
303   - **Used by**: Before merging any PR, when description may be stale
304   - **Note**: Does NOT require agent involvement or session markdown - works on any PR
305   - **🚨 CRITICAL**: NEVER use `--approve` or `--request-changes` - only post comments. Approval is a human decision.
306 
3074. **code-review** (`.github/skills/code-review/SKILL.md`)
308   - **Purpose**: Reviews PR code changes for correctness, safety, and consistency with MAUI conventions. Walks through a MAUI-specific checklist covering handler lifecycle, platform code, safe area, threading, public API, and test patterns.
309   - **Trigger phrases**: "review code for PR #XXXXX", "code review PR #XXXXX", "review this PR's code"
310   - **Note**: Standalone skill — uses independence-first assessment (reads code before PR description to avoid anchoring bias). Can be used by any agent or invoked directly.
311   - **🚨 CRITICAL**: NEVER use `--approve` or `--request-changes` — only post comments. Approval is a human decision.
312 
3135. **learn-from-pr** (`.github/skills/learn-from-pr/SKILL.md`)
314   - **Purpose**: Analyzes completed PR to identify repository improvements (analysis only, no changes applied)
315   - **Trigger phrases**: "what can we learn from PR #XXXXX?", "how can we improve agents based on PR #XXXXX?"
316   - **Used by**: After complex PRs, when agent struggled to find solution
317   - **Output**: Prioritized recommendations for instruction files, skills, code comments
318   - **Note**: For applying changes automatically, use the learn-from-pr agent instead
319 
3206. **write-ui-tests** (`.github/skills/write-ui-tests/SKILL.md`)
321   - **Purpose**: Creates UI tests for GitHub issues and verifies they reproduce the bug
322   - **Trigger phrases**: "write UI tests for #XXXXX", "create UI test for issue", "add UI test coverage"
323   - **Output**: Test files that fail without fix, pass with fix
324 
3257. **write-xaml-tests** (`.github/skills/write-xaml-tests/SKILL.md`)
326   - **Purpose**: Creates XAML unit tests for XAML parsing, compilation, and source generation
327   - **Trigger phrases**: "write XAML tests for #XXXXX", "test XamlC behavior", "reproduce XAML parsing bug"
328   - **Output**: Test files for Controls.Xaml.UnitTests
329 
3309. **verify-tests-fail-without-fix** (`.github/skills/verify-tests-fail-without-fix/SKILL.md`)
331   - **Purpose**: Verifies tests catch the bug before fix and pass with fix. Auto-detects test type (UI, device, unit, XAML) and dispatches to the appropriate runner.
332   - **Two modes**: Verify failure only (test creation) or full verification (test + fix)
333   - **Used by**: After creating tests, before considering PR complete
334 
33510. **run-integration-tests** (`.github/skills/run-integration-tests/SKILL.md`)
336   - **Purpose**: Build, pack, and run .NET MAUI integration tests locally
337   - **Trigger phrases**: "run integration tests", "test templates locally", "run macOSTemplates tests", "run RunOniOS tests"
338   - **Categories**: Build, WindowsTemplates, macOSTemplates, Blazor, MultiProject, Samples, AOT, RunOnAndroid, RunOniOS
339   - **Note**: **ALWAYS use this skill** instead of manual `dotnet test` commands for integration tests
340 
34111. **dependency-flow** (`.github/skills/dependency-flow/SKILL.md`)
342    - **Purpose**: MAUI-specific dependency flow rules, channel conventions, and feed lookup workflows
343    - **Trigger phrases**: "feeds for .NET MAUI X.Y.Z", "where is MAUI build", "promote build to public feed", "what channels is MAUI on", "subscription health for MAUI"
344    - **Wraps**: `maestro-cli` skill (from `dotnet-dnceng@dotnet-arcade-skills` plugin) and maestro MCP tools
345    - **Note**: Provides MAUI-specific guardrails on top of core Maestro/darc operations — channel naming, safety deny-list, input validation, and prompt injection defense
346 
34712. **release-readiness** (`.github/skills/release-readiness/SKILL.md`)
348    - **Purpose**: Deterministic ship-readiness engine for .NET MAUI release branches — both **SR** (`release/*-srN`) and **Preview** (`release/*-previewN`). Surveys CI, computes what's actually shipping, classifies open regressions, identifies port candidates and rejected backports
349    - **Trigger phrases**: "release readiness for SRN", "is SR7 ready to ship", "survey the SR branch", "release readiness for preview6", "how does preview6 look (deterministic)", "status across all releases" (reads the live `[Release Readiness]` tracker issues by body marker — no survey re-run needed)
350    - **Scripts**: `Get-ReleaseReadiness.ps1` (SR lane), `Get-PreviewReadiness.ps1` (Preview lane), `Find-ReleaseReadinessTrackers.ps1` (tracker discovery)
351    - **Output**: JSON + Markdown report, list of source PRs, classification of regression issues (in-sr-active, rejected-from-sr, no-fix-yet, etc.)
352    - **Note**: Deterministic and reproducible — no MCP, no LLM judgment. Use **this skill directly** when you need raw output for a script, dashboard, cron job, or programmatic consumer. For natural-language verdict synthesis with WorkIQ enrichment, use the **`release-readiness-agent`** instead.
353 
354#### Internal Skills (Used by Agents)
355 
35613. **try-fix** (`.github/skills/try-fix/SKILL.md`)
357   - **Purpose**: Proposes ONE independent fix approach, applies it, tests, records result with failure analysis, then reverts
358   - **Used by**: pr agent Phase 3 (Fix phase) - rarely invoked directly by users
359   - **Behavior**: Reads prior attempts to learn from failures. Max 5 attempts per session.
360   - **Output**: Updates session markdown with attempt results and failure analysis
361 
362### Using Custom Agents
363 
364**Delegation Policy**: When user request matches agent trigger phrases, **ALWAYS delegate to the appropriate agent immediately**. Do not ask for permission or explain alternatives unless the request is ambiguous.
365 
366**Examples of correct delegation**:
367- User: "Review PR #12345" → Immediately invoke **pr** agent
368- User: "Test this PR" → Immediately invoke **sandbox-agent**
369- User: "Fix issue #67890" (no PR exists) → Suggest using `/delegate` command
370- User: "Write tests for issue #12345" → Immediately invoke **write-tests-agent**
371- User: "Is SR7 ready to ship?" → Immediately invoke **release-readiness-agent**
372- User: "How does net11 preview6 look?" → Immediately invoke **release-readiness-agent**
373- User: "Give me a status on releases / what needs attention across releases?" → Immediately invoke **release-readiness-agent** (portfolio mode — it enumerates active releases by reading the `[Release Readiness]` tracker issues; don't ask "which release?")
374- User: "Give me the raw release-readiness JSON for SR8" → Use the **release-readiness** skill directly (no enrichment needed)
375 
376**When NOT to delegate**:
377- User asks "What does PR #12345 do?" → Informational query, handle yourself
378- User asks "How do I test PRs?" → Documentation query, handle yourself
379- User has follow-up questions after agent completes → Continue the conversation yourself