Document restore parity guidance

Add reusable instructions for restore bugfixes so future work starts with repro coverage and cross-client parity checks.

Co-authored-by: Copilot <[email protected]>

Author: nkolev92

.github/copilot-instructions.md

@@ -17,6 +17,13 @@
 
 - All files in the repository are nullable by default (project-level nullable enable). No need to add `#nullable enable` directives to individual files.
 
+## Restore Bugfix Guidance
+
+- For restore bugs involving settings, source resolution, or command-line properties, add repro tests before making the implementation change.
+- Preserve restore parity across the main entry points: `nuget.exe`, `dotnet restore`, and `msbuild /t:restore`. If a bug is user-visible in one, check whether the shared restore pipeline affects the others too.
+- When testing explicit source inputs (`-Source`, `--source`, `/p:RestoreSources`), cover both direct paths/URLs and named package sources defined in `NuGet.Config`. A source value may be a configured source name, not just a filesystem path.
+- Prefer a layered test strategy for restore changes: add fast unit coverage around the shared helper or factory logic first, then add at least one integration/functional regression for the relevant client entry points.
+
 ## Nullable Migration Rules
 
 - **Shipped.txt format must be precise** — e.g. `string![]!` not `string![]`, `byte[]?` not `byte?[]`. Always match the format of existing base class entries in the same file.

.github/skills/restore-entrypoint-parity/SKILL.md

@@ -0,0 +1,43 @@
+---
+name: restore-entrypoint-parity
+description: >
+  Guides restore bugfixes that can affect more than one NuGet client entry point.
+  Use when investigating restore settings, source resolution, or command-line property
+  behavior that may need parity across nuget.exe, dotnet restore, and msbuild restore.
+---
+
+# Restore Entrypoint Parity
+
+Use this guidance for NuGet restore issues where the same customer-facing behavior may flow through multiple entry points.
+
+## When to use
+
+Trigger this workflow when the issue mentions any of the following:
+
+- `nuget restore`, `dotnet restore`, or `msbuild /t:restore`
+- `-Source`, `--source`, or `/p:RestoreSources`
+- `NuGet.Config` source precedence or named sources
+- restore settings or property precedence problems
+
+## Workflow
+
+1. Start with failing repro tests before implementation.
+2. Check whether the behavior is shared across:
+   - `nuget.exe`
+   - `dotnet restore`
+   - `msbuild restore`
+3. Add unit tests around the shared source/settings resolution helpers when possible.
+4. Add end-to-end or integration coverage for the user-facing entry points that expose the bug.
+
+## Generic lessons
+
+- Restore bugs that look client-specific are often caused by shared restore infrastructure.
+- Explicit source values can represent either a path/URL or a source name from `NuGet.Config`.
+- Source resolution should prefer enabled configured source names before treating the input as a relative path.
+- Keep existing relative-path behavior covered while fixing named-source scenarios.
+
+## Coverage checklist
+
+- A unit or component test proves the core resolution logic.
+- At least one client-facing regression test proves the scenario from the user perspective.
+- If the behavior is meant to be consistent across tools, add parity coverage for `nuget.exe`, `dotnet restore`, and `msbuild restore`.