Add MAUI-specific C# Expert agent with comprehensive instruction file integration

[Copilot]

Note

Are you waiting for the changes in this PR to be merged?
It would be very helpful if you could test the resulting artifacts from this PR and let us know in a comment if this change resolves your issue. Thank you!

Description of Change

Analyzed how generic C# Expert agent instructions apply to MAUI's architecture and created a specialized agent that handles MAUI's unique patterns correctly. Additionally conducted comprehensive review of all existing instruction files to ensure proper integration without conflicts or duplication.

Analysis Documents

MAUI-Specific Analysis (.github/agents/csharp-expert-maui-analysis.md)

Identified 8 areas where generic C# guidance conflicts with or misses MAUI patterns:

• Testing frameworks: Generic guidance treats xUnit/NUnit as interchangeable; MAUI uses xUnit for unit tests, NUnit for UI tests with Appium
• Interface usage: Generic "avoid interfaces" conflicts with MAUI's interface-based architecture (IButton, ILabel, handlers)
• Platform-specific code: File extensions (.Android.cs, .iOS.cs) and conditional compilation patterns not covered
• Handler pattern: Core MAUI abstraction bridging controls to native views
• Two-project UI tests: HostApp page + test class requirement unique to MAUI
• Build prerequisites: Must build tasks first or face cryptic errors
• Mobile performance: Layout passes, memory pressure, startup optimization
• Platform threading: Main thread requirements for iOS/MacCatalyst

Cross-File Analysis (.github/agents/instruction-files-analysis.md)

Comprehensive 21KB analysis of all instruction and agent files including:

• Content overlap matrix across 10+ files covering 13 content areas
• Conflict identification and resolution (2 conflicts resolved)
• Gap analysis with actionable recommendations
• Integration quality assessment

Key Finding: No major conflicts. All content is complementary - agents provide domain expertise while instruction files provide context-specific procedures.

MAUI C# Expert Agent (.github/agents/maui-csharp-expert.agent.md)

Extends generic C# Expert with MAUI-specific guidance:

// Platform-specific implementation via file extensions
// Button.Android.cs
public partial class ButtonHandler : ViewHandler<IButton, PlatformView>
{
    protected override PlatformView CreatePlatformView() => 
        new Google.Android.Material.Button.MaterialButton(Context);
}

// Two-project UI test pattern
// TestCases.HostApp/Issues/Issue12345.xaml
<Button AutomationId="TestButton" Text="Click" />

// TestCases.Shared.Tests/Tests/Issues/Issue12345.cs
public class Issue12345 : _IssuesUITest
{
    [Test]
    [Category(UITestCategories.Button)]
    public void ButtonClick() => App.Tap("TestButton");
}

Includes cross-references to specialized instruction files for instrumentation, SafeArea testing, and template development.

Enhanced Existing Files

.github/copilot-instructions.md

• Added testing framework selection guidance clarifying xUnit vs NUnit usage by test type
• Links to detailed instruction files for comprehensive procedures

AGENTS.md

• Added mobile development considerations section covering:
  • Performance patterns (layout, memory, startup optimization)
  • Platform threading requirements (MainThread usage patterns)
  • Testing framework selection by test type
• Cross-references to MAUI C# Expert agent for detailed patterns

Navigation and Documentation

Directory README (.github/agents/README.md)

• Decision tree for agent selection
• Integration with existing instruction files
• Precedence order and usage guidelines

Implementation Summary (.github/agents/SUMMARY.md)

• Complete documentation of work completed
• File relationships and integration quality metrics
• Future maintenance guidelines

Agent vs Instructions Architecture

Agents provide domain expertise that can be explicitly invoked:

• Encapsulate patterns and best practices for a specific domain (MAUI development)
• Can be reused across different contexts and tools
• Provide prescriptive guidance with clear inheritance (MAUI extends generic C# Expert)

Instructions provide contextual procedures that auto-apply:

• Focus on workflows and repository-specific setup
• Applied based on file paths or tool context
• Handle troubleshooting and procedural steps

Both approaches are complementary - agents offer explicit domain invocation ("use MAUI C# Expert for handlers") while instructions provide always-active contextual guidance.

---

Enables AI assistants to provide accurate MAUI-appropriate guidance instead of generic .NET patterns that don't apply. All files work together to provide comprehensive guidance without duplication or conflict.

Issues Fixed

N/A - Enhancement to AI assistant guidance infrastructure

---

💡 You can make Copilot smarter by setting up custom instructions, customizing its development environment and configuring Model Context Protocol (MCP) servers. Learn more Copilot coding agent tips in the docs.

[PureWeen]

@copilot we already have copilot instructions

Can you review all of our instruction files as well and see where those fit in here?
do those instructions have conflicting data? or is that info already covered there?

[Copilot]

@copilot we already have copilot instructions

Can you review all of our instruction files as well and see where those fit in here?
...

I've completed a comprehensive review of all instruction files. Here's the analysis:

Created Analysis Document (commit 412e862):

.github/agents/instruction-files-analysis.md - 20KB comprehensive analysis covering:

• Content overlap matrix across all 10+ instruction/agent files
• Detailed comparison of 13 content areas
• Conflict identification and resolution status
• Gap analysis with recommendations

Key Findings:

✅ No Major Conflicts - The only potential conflict (interface usage) is explicitly resolved in the MAUI agent

✅ Intentional Overlap - Files serve different purposes:

• Agent files: Domain expertise (C# general, MAUI-specific)
• Instruction files: Context/path-specific procedures
• Both needed: Complementary, not duplicative

⚠️ 2 Clarifications Added:

1. Testing Framework Selection - Added to copilot-instructions.md:

   • xUnit for unit tests (*.UnitTests)
   • NUnit for UI tests (TestCases.Shared.Tests)
   • Not interchangeable - determined by test type

2. Mobile Development - Added to AGENTS.md:

   • Performance patterns (layout, memory, startup)
   • Platform threading requirements (MainThread usage)
   • References to MAUI agent for details

Cross-References Added:

All files now reference each other appropriately:

• MAUI agent → specialized instruction files
• AGENTS.md → MAUI agent for detailed patterns
• copilot-instructions.md → Already had good references

Bottom Line:

Existing instruction files are well-organized and don't conflict with new agents. They're complementary:

• uitests.instructions.md - Remains the authoritative UI test guide (path-specific)
• instrumentation.instructions.md - Debugging patterns (specialized)
• safearea-testing.instructions.md - SafeArea testing (specialized)
• templates.instructions.md - Template semantics (path-specific)
• MAUI agent provides general development patterns and references these when appropriate

[PureWeen]

@copilot

Why would I use this at a customer agent vs just mix this into our instructions?

[Copilot]

@copilot

Why would I use this at a customer agent vs just mix this into our instructions?

Custom Agent vs Instructions - Key Differences:

Agents (domain expertise):

• Invoked explicitly when you need specialized knowledge
• Encapsulate patterns and best practices for a specific domain (MAUI development)
• Can be reused across different contexts and tools
• Provide prescriptive guidance ("do this")

Instructions (contextual procedures):

• Auto-applied based on file paths or tool context
• Focus on workflows and procedures ("how to do this")
• Repository-specific setup and troubleshooting

Why Custom Agent Makes Sense:

1. Explicit invocation - You can ask "use MAUI C# Expert" when writing handlers or platform code, but stick with generic C# Expert for utilities
2. Portability - Agent patterns can help in other MAUI-related repos or projects
3. Separation of concerns - Keep procedural (instructions) separate from expertise (agents)
4. Composability - Generic C# Expert + MAUI specialization = clear inheritance model

When Instructions Would Be Better:

If this was purely procedural (build steps, file locations) or path-specific (only applies to certain directories), then yes, instructions would be better.

Recommendation:

You could merge these into instructions if:

• You primarily use GitHub Copilot (instructions are always active)
• You don't need explicit domain invocation
• You prefer single-source documentation

Keep as agent if:

• You want explicit "MAUI expert" vs "generic C#" distinction
• Multiple AI tools will use this (agents are tool-agnostic)
• You value the domain expertise separation

Both approaches are valid - this is an architectural preference question.