{"owner":"dotnet","repo":"roslyn","hasSkills":true,"hasMcp":false,"mcpConfig":null,"found":[".github/copilot-instructions.md","AGENTS.md"],"files":{".github/copilot-instructions.md":"# Roslyn (.NET Compiler Platform) — Copilot Instructions\n\n> 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.\n\n## Project Overview\n\nRoslyn 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:\n- **Compilers** (`src/Compilers/`) — C#/VB compilers (syntax, semantics, emit).\n- **Workspaces** (`src/Workspaces/`) — Solution/Project/Document model + MEF host.\n- **Features / EditorFeatures** (`src/Features/`, `src/EditorFeatures/`) — IDE features.\n- **Analyzers / CodeStyle** (`src/Analyzers/`, `src/CodeStyle/`) — IDE0xxx diagnostics & fixes.\n- **LanguageServer** (`src/LanguageServer/`) — LSP server.\n- **VisualStudio** (`src/VisualStudio/`) — VS integration.\n- **Razor** (`src/Razor/src/`) — Razor compiler & tooling (merged sub-tree).\n\n## Project Structure\n\n```\nsrc/\n  Compilers/      # C#/VB compilers (Core, CSharp, VisualBasic, Server)\n  Workspaces/     # Solution model, MSBuild loading, Remote (OOP)\n  Features/       # Language-agnostic IDE feature logic\n  EditorFeatures/ # Editor/text-buffer integration\n  Analyzers/      # IDE0xxx code-style analyzers & fixes\n  LanguageServer/ # LSP server\n  VisualStudio/   # VS language services & UI\n  Razor/src/      # Razor compiler + tooling (own layout)\n  ExpressionEvaluator/  Scripting/  Interactive/  RoslynAnalyzers/\neng/              # Arcade build engineering (eng/common is DARC-synced)\ndocs/             # Contributor & design docs\n```\n\n## Build & Test\n\n### Build specific projects during development (preferred)\n```bash\ndotnet build Compilers.slnf      # compilers only\ndotnet build Ide.slnf            # IDE only\ndotnet build Razor.slnf          # Razor compiler & tooling only\ndotnet build <path/to/Project.csproj>\n```\n\n### Run tests for modified code\n```bash\ndotnet test <path/to/Specific.UnitTests.csproj>\ndotnet test <proj> --filter \"FullyQualifiedName~MyTestClass\"\n```\n\nTests can take a while to build and run — monitor output and wait for completion unless you're confident a run is hung.\n\n### Full build/test (final validation only)\n```bash\n./build.sh   # Build.cmd on Windows\n./test.sh    # Test.cmd on Windows\n```\n\nOther entry points: `dotnet run --file eng/generate-compiler-code.cs` (regenerate Syntax/BoundNodes code), `dotnet msbuild <proj> /t:UpdateXlf` (refresh `.xlf` after `.resx` edits).\n\n## Code Style\n\n- 4-space indent for code; 2-space for project/XML/JSON. Never tabs. UTF-8-BOM, final newline for `*.cs`/`*.vb`.\n- **Blank lines must be completely empty** (no spaces/tabs); no trailing whitespace — both are hard lint failures.\n- Private fields `_camelCase`; namespaces `Microsoft.CodeAnalysis.[Language].[Area]`.\n- 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.)\n- Language services are exported **per-language** (`[ExportLanguageService(..., LanguageNames.CSharp), Shared]`), never shared across C#/VB.\n- 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`.\n- Update `PublicAPI.Unshipped.txt` for public API changes. Never hand-edit generated code or `eng/common`.\n- It is acceptable to have async methods with no awaits. CS1998 is not active for this repository.\n\nFull conventions: `.github/memory/CONVENTIONS.md` and `.github/instructions/{Compiler,IDE,Razor}.instructions.md`.\n\n## Agent Orientation\n\nWhen starting any task or answering any question about this repo:\n1. **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.\n2. **For any non-trivial task, also read `.github/memory/ARCHITECTURE.md` and `.github/memory/CONVENTIONS.md`** as your baseline.\n3. **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).\n4. After completing work, run the `update-agent-docs` skill.\n\n### Memory\n\n`.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.\n\n**Memory freshness is your responsibility.** Files can drift from the code:\n- **Always cross-check memory claims against actual code** before relying on them.\n- **If a memory file is stale, fix it immediately.** If you learn something worth keeping, write it to `.github/memory/` immediately.\n\n### Doc Update Obligation\n\nEvery task that changes code must end with a doc pass:\n- Added or moved files? → Update `.github/memory/FILE_MAP.md` (top-level) and the matching `.github/instructions/<area>.instructions.md` (directory detail).\n- Changed a public interface, diagnostic ID, or API? → Update the relevant `.github/instructions/<area>.instructions.md` and `PublicAPI.Unshipped.txt`.\n- Hit something surprising or undocumented? → Repo-wide → `.github/memory/KNOWN_ISSUES.md`; layer-specific → `.github/memory/known-issues/<area>.md`.\n- Established a new pattern? → Repo-wide → `.github/memory/CONVENTIONS.md`; layer-specific → the matching `.github/instructions/<area>.instructions.md`.\n- Changed test base classes or conventions? → Repo-wide layout → `.github/memory/TESTING_STRATEGY.md`; layer-specific → `.github/memory/testing/<area>.md`.\n- Added/removed/renamed a memory file? → Update `.github/memory/INDEX.md`.\n\n### Skills\n\nSkills 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`.\n\n## Working Loop (plan first)\n\nFor 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.\n\nWrite 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.\n\n**Plan template** (drop unneeded fields):\n\n```markdown\n## Plan: <short title>\n\n- **Scope:** what this change will do.\n- **Non-goals:** what this change explicitly will NOT do.\n- **Affected areas:** projects/files/layers touched (e.g. `src/Compilers/CSharp`, matching `.instructions.md`).\n- **Approach:** the intended implementation, and any alternatives considered/rejected.\n- **Acceptance:** observable done-state — the behavior/tests that prove it works.\n- **Validation:** exact build + targeted test commands you'll run (see Build & Test).\n```\n\n**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.\n\nThen 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 Definition of Done below passes) is the work \"done.\"\n\nTrivial changes don't need a written plan — go straight to the Definition of Done.\n\n### Keep changes reviewable\n\n- Keep each change focused on one coherent concern. Do not mix behavior changes with unrelated cleanup, broad renames, or opportunistic refactoring.\n- Split work when parts can be reviewed, validated, merged, or reverted independently; when they affect unrelated areas or owners; or when a preparatory refactoring can land before the behavior change.\n- Checkpoint after each independently valid slice rather than accumulating one large unreviewed diff. Each checkpoint must build on the previous one and leave the branch in a coherent state.\n- Do not optimize for an arbitrary line-count limit: generated files and mechanical updates can be large. Optimize for reviewer cognitive load, clear intent, and independent validation.\n- If a change cannot be split without making it less correct or harder to validate, explain that constraint in the plan and keep the commits logically separated.\n\n## Definition of Done\n\nWork is done only when every applicable step below is complete:\n\n1. **Format:** Run the repository's existing formatter for changed files when applicable.\n2. **Lint/analyzers:** Run the smallest existing lint or analyzer command that covers the changed files when applicable.\n3. **Build:** Build the specific affected project or solution filter (`Compilers.slnf`, `Ide.slnf`, `Razor.slnf`, or the project). Documentation-only changes do not require a product build.\n4. **Targeted tests:** Run the affected test project or focused test filter. Add or update tests when behavior changes; explain when no relevant automated test exists.\n5. **Generated/resource/API updates:** Regenerate Syntax/BoundNodes outputs when their XML changes, run `/t:UpdateXlf` after `.resx` edits, and update `PublicAPI.Unshipped.txt` for public API changes.\n6. **Diff review:** Review the final diff and confirm it matches the approved plan, contains no unrelated edits, and follows nearby patterns.\n7. **Docs:** Run the `update-agent-docs` skill and apply the Doc Update Obligation above.\n8. **Final evidence:** Inspect repository status and the final diff, then report the exact validation performed. Do not claim completion while required validation is failing or was silently skipped.\n","AGENTS.md":"# Roslyn (.NET Compiler Platform) — AI Agent Instructions\n\nThis file is intentionally thin. The canonical, repo-wide agent guidance lives in\n**[`.github/copilot-instructions.md`](.github/copilot-instructions.md)** — read it first.\nIt covers the project overview, build/test entry points, global code style, the\nmemory-first orientation protocol, and the doc-update obligation.\n\n## Where to find things\n\n- **Repo-wide rules & orientation:** [`.github/copilot-instructions.md`](.github/copilot-instructions.md)\n- **Knowledge base (load on demand):** [`.github/memory/INDEX.md`](.github/memory/INDEX.md) — the loading map; start here for architecture, conventions, file map, APIs, known issues, and testing.\n- **Area-specific rules (auto-applied by path):** [`.github/instructions/`](.github/instructions/)\n  - [`Compiler.instructions.md`](.github/instructions/Compiler.instructions.md) — `src/{Compilers,Dependencies,ExpressionEvaluator,Tools}`\n  - [`IDE.instructions.md`](.github/instructions/IDE.instructions.md) — `src/{Analyzers,CodeStyle,Features,Workspaces,EditorFeatures,VisualStudio,LanguageServer}`\n  - [`Razor.instructions.md`](.github/instructions/Razor.instructions.md) — `src/Razor`\n- **Task-specific skills:** [`.github/skills/`](.github/skills/) (auto-discovered; e.g. `code-review`, `ci-analysis`, `update-agent-docs`).\n\n## Orientation protocol\n\n1. Read [`.github/copilot-instructions.md`](.github/copilot-instructions.md).\n2. Read [`.github/memory/INDEX.md`](.github/memory/INDEX.md) and load only the memory files relevant to your task.\n3. The path-scoped instruction file for the area you're editing applies automatically — follow it.\n4. After changing code, run the `update-agent-docs` skill to keep `.github/memory/` fresh.\n"}}