Add .NET nanoFramework copilot agent mode instructions

.github/agents/nanoframework.agent.md

@@ -0,0 +1,108 @@
+---
+name: .NET nanoFramework Agent
+description: Agent instructions for generating, reviewing, and modifying C# code for .NET nanoFramework samples on constrained embedded devices.
+tools:
+  - search/codebase
+  - search
+  - web/fetch
+  - web/githubRepo
+  - read/readFile
+  - search/fileSearch
+  - search/textSearch
+  - search/listDirectory
+  - edit/createDirectory
+  - edit/createFile
+  - edit/editFiles
+  - execute/runInTerminal
+---
+
+# Copilot Instructions for .NET nanoFramework
+
+This repository targets **.NET nanoFramework**, which runs C# on constrained embedded devices (for example ESP32, STM32, and others).
+
+When generating, reviewing, or modifying code in this repo, follow these rules:
+
+## 1 - Validate API availability first
+
+- Do **not** assume an API exists just because it is available in desktop/main .NET.
+- Always verify availability in the nanoFramework API browser:
+  - https://docs.nanoframework.net/api/index.html
+- If an API is not available, propose a nanoFramework-compatible alternative.
+
+## 2 - Prefer patterns already used in this repository
+
+- Use existing samples in this repo as the primary source for implementation patterns, coding style, and project structure.
+- Before introducing a new approach, check if an equivalent pattern already exists in:
+  - https://github.com/nanoframework/samples
+- Keep solutions simple and aligned with embedded constraints (memory, CPU, storage, networking reliability).
+
+## 3 - Account for nanoFramework differences from main .NET
+
+- Assume APIs are simplified even when naming aligns with main .NET.
+- Avoid desktop-only features, heavy abstractions, reflection-heavy code, or dependencies that are unlikely to run on embedded targets.
+- Prefer deterministic, lightweight implementations suitable for microcontrollers.
+- Always consider the constraints of the target hardware when proposing solutions.
+- Generics, async patterns, and certain language features are not yet supported on nanoFramework.
+
+## 4 - Use device bindings when applicable
+
+- nanoFramework supports many IoT device bindings.
+- For hardware-specific code, check existing bindings and guidance first:
+  - https://docs.nanoframework.net/devicesdetails/README.html
+- Reuse existing bindings and samples rather than creating custom low-level implementations when a supported binding exists.
+
+## 5 - Practical coding expectations
+
+- Keep allocations and background work minimal.
+- Be explicit about timeouts, retries, and error handling for I/O and networking.
+- Favor clear, maintainable code that can run reliably on constrained devices.
+- When in doubt, choose the simpler implementation.
+
+## 6 - If uncertain, state assumptions
+
+- Explicitly mention when a proposal depends on API availability or board-specific capabilities.
+- Add concise notes about what should be verified on target hardware.
+
+## 7 - Build and solution validation workflow
+
+- Always include a build step when changes affect code, project files, or package references.
+- Follow the nanoFramework VS Code extension build model: use `nuget restore` + `msbuild`.
+- Build scope selection:
+  - If a matching `*.sln` exists for the changed sample, build the solution (preferred, same as extension workflow).
+  - If no solution exists, build the target `*.nfproj` directly.
+  - When targeting a project, use the project path and project system path defined/imported by the `.nfproj`.
+- Preferred command sequence (PowerShell):
+  - `nuget restore <path-to-solution-or-project>`
+  - `msbuild <path-to-solution-or-project> /p:platform="Any CPU" /p:Configuration=Release /verbosity:minimal`
+- If `msbuild` is not on `PATH`, resolve it first (for example with `vswhere` on Windows), then run the same restore/build steps.
+- Windows example to resolve `MSBuild.exe` with `vswhere` and build:
+  - `$msbuild = & "${env:ProgramFiles(x86)}\Microsoft Visual Studio\Installer\vswhere.exe" -products * -latest -prerelease -requires Microsoft.Component.MSBuild -find "MSBuild\**\Bin\amd64\MSBuild.exe" | Select-Object -First 1`
+  - `& $msbuild <path-to-solution-or-project> /p:platform="Any CPU" /p:Configuration=Release /verbosity:minimal`
+- If build fails:
+  - Report the exact error output.
+  - Propose a minimal fix.
+  - Re-run the same `nuget restore` + `msbuild` sequence after the fix.
+- In final results, summarize:
+  - Which solution/project was built.
+  - Whether `nuget restore` + `msbuild` succeeded.
+  - Any remaining manual hardware validation steps (deployment/flash/runtime checks).
+
+## 8 - Testing workflow for nanoFramework
+
+- Do not default to `dotnet test` for nanoFramework projects.
+- For unit tests, follow the nanoFramework Test Platform workflow (`nanoFramework.TestFramework`, `nanoFramework.UnitTestLauncher`, `nanoFramework.TestAdapter`).
+- Identify unit test projects by checking `.nfproj` metadata such as:
+  - `<IsTestProject>true</IsTestProject>`
+  - `<TestProjectType>UnitTest</TestProjectType>`
+- Ensure a `.runsettings` file exists (often `nano.runsettings`) and includes nanoFramework adapter settings.
+- Test discovery/execution flow:
+  - Build first (`nuget restore` + `msbuild`) so tests are discovered.
+  - Run tests through Visual Studio / Test Explorer (or equivalent VS test host integration).
+  - For hardware execution, set `<IsRealHardware>True</IsRealHardware>` in `.runsettings`.
+- Pipeline/automation flow:
+  - Use `vstest.Console.exe` with `nanoFramework.TestAdapter.dll`.
+  - Keep test adapter and test framework package versions aligned.
+- When reporting test outcomes, include:
+  - Which test project and runsettings file were used.
+  - Whether tests ran on emulator/simulated mode or real hardware.
+  - Pass/fail/skip summary and any device-specific constraints.

README.md

@@ -14,6 +14,12 @@ Feel free to browse, take what you like and contribute back if you want.
 
 If you are looking for Iot.Device samples, they are all in the [Iot.Device repository](https://github.com/nanoFramework/nanoFramework.IoT.Device).
 
+## AI agent guidance
+
+If you're using GitHub Copilot custom agents in VS Code or Visual Studio, this repository includes a nanoFramework-specific agent definition with guidance for API compatibility checks, build workflow, and testing:
+
+- [nanoFramework custom agent](.github/agents/nanoframework.agent.md)
+
 ## Sample by category
 
 Our samples uses 🌶️ to show how easy or complicated those samples are. The samples with 🌶️ are easy and recommended for beginners. The ones with 🌶️🌶️🌶️ are more advanced and requires some knowledge. This knowledge may not be on .NET nanoFramework but on some other elements like certificates or networking for example.