Copilot instructions

1# Roslyn (.NET Compiler Platform) — Copilot Instructions
2 
3> This is the **canonical** repo-wide agent entry point. `AGENTS.md` at the repo root points here. Path-scoped rules in `.github/instructions/{Compiler,IDE,Razor}.instructions.md` apply automatically by area and supplement this file. This file establishes the memory-first orientation protocol and doc-maintenance obligation.
4 
5## Project Overview
6 
7Roslyn is the open-source C# and Visual Basic compilers plus the language services and IDE features built on their APIs. Built around **immutable** syntax trees, semantic models, symbols, and workspace snapshots. Major components:
8- **Compilers** (`src/Compilers/`) — C#/VB compilers (syntax, semantics, emit).
9- **Workspaces** (`src/Workspaces/`) — Solution/Project/Document model + MEF host.
10- **Features / EditorFeatures** (`src/Features/`, `src/EditorFeatures/`) — IDE features.
11- **Analyzers / CodeStyle** (`src/Analyzers/`, `src/CodeStyle/`) — IDE0xxx diagnostics & fixes.
12- **LanguageServer** (`src/LanguageServer/`) — LSP server.
13- **VisualStudio** (`src/VisualStudio/`) — VS integration.
14- **Razor** (`src/Razor/src/`) — Razor compiler & tooling (merged sub-tree).
15 
16## Project Structure
17 
18```
19src/
20  Compilers/      # C#/VB compilers (Core, CSharp, VisualBasic, Server)
21  Workspaces/     # Solution model, MSBuild loading, Remote (OOP)
22  Features/       # Language-agnostic IDE feature logic
23  EditorFeatures/ # Editor/text-buffer integration
24  Analyzers/      # IDE0xxx code-style analyzers & fixes
25  LanguageServer/ # LSP server
26  VisualStudio/   # VS language services & UI
27  Razor/src/      # Razor compiler + tooling (own layout)
28  ExpressionEvaluator/  Scripting/  Interactive/  RoslynAnalyzers/
29eng/              # Arcade build engineering (eng/common is DARC-synced)
30docs/             # Contributor & design docs
31```
32 
33## Build & Test
34 
35### Build specific projects during development (preferred)
36```bash
37dotnet build Compilers.slnf      # compilers only
38dotnet build Ide.slnf            # IDE only
39dotnet build Razor.slnf          # Razor compiler & tooling only
40dotnet build <path/to/Project.csproj>
41```
42 
43### Run tests for modified code
44```bash
45dotnet test <path/to/Specific.UnitTests.csproj>
46dotnet test <proj> --filter "FullyQualifiedName~MyTestClass"
47```
48 
49Tests can take a while to build and run — monitor output and wait for completion unless you're confident a run is hung.
50 
51### Full build/test (final validation only)
52```bash
53./build.sh   # Build.cmd on Windows
54./test.sh    # Test.cmd on Windows
55```
56 
57Other entry points: `dotnet run --file eng/generate-compiler-code.cs` (regenerate Syntax/BoundNodes code), `dotnet msbuild <proj> /t:UpdateXlf` (refresh `.xlf` after `.resx` edits).
58 
59## Code Style
60 
61- 4-space indent for code; 2-space for project/XML/JSON. Never tabs. UTF-8-BOM, final newline for `*.cs`/`*.vb`.
62- **Blank lines must be completely empty** (no spaces/tabs); no trailing whitespace — both are hard lint failures.
63- Private fields `_camelCase`; namespaces `Microsoft.CodeAnalysis.[Language].[Area]`.
64- Always thread `CancellationToken` through async operations. (Null-checking style is layer-specific — see the area's instruction file: `Contract.ThrowIfNull` in IDE, `Debug.Assert` in the compiler.)
65- Language services are exported **per-language** (`[ExportLanguageService(..., LanguageNames.CSharp), Shared]`), never shared across C#/VB.
66- No `TODO`/`TODO2` comments — track follow-ups as linked GitHub issues in code; existing `TODO2`s are only a frozen enforcement baseline. No `PROTOTYPE` comments in PRs to `main`.
67- Update `PublicAPI.Unshipped.txt` for public API changes. Never hand-edit generated code or `eng/common`.
68 
69Full conventions: `.github/memory/CONVENTIONS.md` and `.github/instructions/{Compiler,IDE,Razor}.instructions.md`.
70 
71## Agent Orientation
72 
73When starting any task or answering any question about this repo:
741. **Read `.github/memory/INDEX.md` first** — it's the loading map for the knowledge base. Use it to find authoritative answers before searching the file system.
752. **For any non-trivial task, also read `.github/memory/ARCHITECTURE.md` and `.github/memory/CONVENTIONS.md`** as your baseline.
763. **Read the path-scoped instruction file for the area you're editing** — `.github/instructions/Compiler.instructions.md`, `IDE.instructions.md`, or `Razor.instructions.md` (these auto-apply to `.cs`/`.vb` under their glob and carry the layer's directory detail, conventions, and key files/APIs). For that layer's **known issues** and **test conventions**, load `.github/memory/known-issues/<area>.md` and `.github/memory/testing/<area>.md` on demand (see the INDEX loading map).
774. After completing work, run the `update-agent-docs` skill.
78 
79### Memory
80 
81`.github/memory/` is your persistent knowledge base. You may freely create new focused files, update existing ones when you find corrections, and reorganize when structure no longer fits. Use descriptive filenames.
82 
83**Memory freshness is your responsibility.** Files can drift from the code:
84- **Always cross-check memory claims against actual code** before relying on them.
85- **If a memory file is stale, fix it immediately.** If you learn something worth keeping, write it to `.github/memory/` immediately.
86 
87### Doc Update Obligation
88 
89Every task that changes code must end with a doc pass:
90- Added or moved files? → Update `.github/memory/FILE_MAP.md` (top-level) and the matching `.github/instructions/<area>.instructions.md` (directory detail).
91- Changed a public interface, diagnostic ID, or API? → Update the relevant `.github/instructions/<area>.instructions.md` and `PublicAPI.Unshipped.txt`.
92- Hit something surprising or undocumented? → Repo-wide → `.github/memory/KNOWN_ISSUES.md`; layer-specific → `.github/memory/known-issues/<area>.md`.
93- Established a new pattern? → Repo-wide → `.github/memory/CONVENTIONS.md`; layer-specific → the matching `.github/instructions/<area>.instructions.md`.
94- Changed test base classes or conventions? → Repo-wide layout → `.github/memory/TESTING_STRATEGY.md`; layer-specific → `.github/memory/testing/<area>.md`.
95- Added/removed/renamed a memory file? → Update `.github/memory/INDEX.md`.
96 
97### Skills
98 
99Skills live in `.github/skills/<skill-name>/SKILL.md` and are auto-discovered by their YAML `description`. Useful ones here include `code-review`, `ci-analysis`, `analyzer-codefix`, `merge-into-branch`, `snap`, and `update-agent-docs`.
100 
101## Working Loop (plan first)
102 
103For any **non-trivial** change, start with a short plan **before** writing the implementing diff — and surface it so it can be reviewed before a large diff appears. "Non-trivial" means anything that is cross-file or cross-area, touches a public API / diagnostic ID / analyzer, changes behavior (not just a typo/comment/formatting fix), or where the approach isn't obvious. When in doubt, write the plan — it's cheap.
104 
105Write the plan to `plan.md` in your session folder (see the session context) and keep it updated at milestones. A plan is a working artifact, not a deliverable: keep it lean.
106 
107**Plan template** (drop unneeded fields):
108 
109```markdown
110## Plan: <short title>
111 
112- **Scope:** what this change will do.
113- **Non-goals:** what this change explicitly will NOT do.
114- **Affected areas:** projects/files/layers touched (e.g. `src/Compilers/CSharp`, matching `.instructions.md`).
115- **Approach:** the intended implementation, and any alternatives considered/rejected.
116- **Acceptance:** observable done-state — the behavior/tests that prove it works.
117- **Validation:** exact build + targeted test commands you'll run (see Build & Test).
118```
119 
120**Post the plan and wait for approval before writing the implementing diff** — the plan is meant to be reviewed now, not after a large diff already exists.
121 
122Then implement, keeping the diff **scoped and reviewable** — prefer the smallest change that fully addresses the task over a broad refactor. If the plan changes materially while implementing, update it rather than silently diverging. Only after the plan's **Acceptance** and **Validation** are satisfied (and the Validation Checklist below passes) is the work "done."
123 
124Trivial changes don't need a written plan — go straight to the Validation Checklist.
125 
126## Validation Checklist
127 
128When making changes:
1291. **Read `.github/memory/INDEX.md` first.**
1302. For non-trivial tasks, read `ARCHITECTURE.md` and `CONVENTIONS.md`, and the `.github/instructions/<area>.instructions.md` for the area you're editing.
1313. **Build the specific project(s) modified** (`Compilers.slnf` / `Ide.slnf` / `Razor.slnf` / the project).
1324. **Run targeted tests** for affected test project(s).
1335. If you edited a `.resx`, run `/t:UpdateXlf`; if you edited Syntax/BoundNodes XML, regenerate code. Update `PublicAPI.Unshipped.txt` for public API changes.
1346. Follow existing patterns in similar files.
1357. **Doc pass** (mandatory) — run the `update-agent-docs` skill and apply the Doc Update Obligation above.
136