.github/COPILOT_ENVIRONMENT.md

Custom Copilot Environment

This repository uses a custom environment for GitHub Copilot coding agent to ensure all necessary development tools are available when working on C# code.

Overview

The custom environment is configured through the .github/workflows/copilot-setup-steps.yml workflow, which automatically runs before Copilot starts working on the repository.

Installed Tools

Roslyn-Stone MCP Server (Dogfooding)

• Purpose: C# REPL and documentation tools for validating code changes
• Usage: Test C# expressions, validate syntax, look up .NET documentation
• Tools Available:
  • EvaluateCsharp - Execute C# code in a stateful REPL
  • ValidateCsharp - Validate C# syntax without execution
  • GetDocumentation - Look up XML documentation for .NET types
  • GetReplInfo - Get REPL environment information
  • LoadNuGetPackage - Dynamically load NuGet packages
  • SearchNuGetPackages - Search for NuGet packages
• Recommendation: Use these tools to validate C# code changes before committing

.NET 10 SDK

• Version: 10.0.x (latest)
• Purpose: Provides the latest C# features and runtime
• Usage: All C# compilation and runtime operations

CSharpier

• Purpose: Opinionated code formatter for C#
• Usage: Format C# code consistently across the project
• Command: dotnet csharpier <file-or-directory>
• Documentation: https://csharpier.com/

ReSharper Command Line Tools

• Purpose: Code analysis, inspection, and refactoring
• Usage: Run code inspections and analysis
• Command: jb <command>
• Documentation: https://www.jetbrains.com/help/resharper/ReSharper_Command_Line_Tools.html

Cake Build Tool

• Purpose: Cross-platform build automation
• Usage: Execute build scripts written in C#
• Command: dotnet cake <script.cake>
• Documentation: https://cakebuild.net/

dotnet-outdated

• Purpose: Check for outdated NuGet package dependencies
• Usage: Identify packages that can be updated
• Command: dotnet-outdated or dotnet-outdated -u to upgrade
• Documentation: https://github.com/dotnet-outdated/dotnet-outdated

How It Works

1. Automatic Triggers: The workflow runs automatically when:

   • The workflow file itself is modified (push or pull request)
   • Manually triggered via workflow_dispatch

2. Setup Process:

   • Checkout the repository
   • Install .NET 10 SDK
   • Install all development tools globally
   • Cache NuGet packages for faster subsequent runs
   • Verify all tools are properly installed

3. Copilot Integration:

   • Copilot uses this prepared environment when executing code or running builds
   • All tools are available in the PATH for immediate use
   • NuGet packages are cached to speed up dependency resolution

Customization

To add more tools to the environment:

1. Edit .github/workflows/copilot-setup-steps.yml
2. Add installation steps in the steps section
3. Use dotnet tool install --global <tool-name> for .NET tools
4. Use standard apt-get or other package managers for system tools
5. Commit and push the changes - the workflow will run automatically

Example of adding a new .NET tool:

- name: Install <ToolName>
  run: dotnet tool install --global <package-name>

Benefits

• Consistency: Same tools available every time Copilot works on the code
• Performance: Cached dependencies reduce setup time
• Reliability: Known-good versions of tools eliminate version mismatch issues
• Productivity: Copilot can use advanced tools without manual setup

Troubleshooting

If tools are not available in Copilot sessions:

1. Check the workflow run logs in GitHub Actions
2. Verify the workflow completed successfully
3. Ensure the tool installation steps didn't fail
4. Check that the workflow is enabled in the repository settings

References

• GitHub Copilot Custom Environment Documentation
• .NET SDK Documentation
• GitHub Actions Workflow Syntax