Roslyn-Backed-MCP: Instructions file for GitHub Copilot

Copilot Instructions

Implementation quality and safety rules for this repository. For session bootstrap and workflow, follow AGENTS.md first.

The Standing Engineering Directives govern these rules: choose the smallest complete root-cause fix, rederive prior work, surface observed defects and verify current claims. Repository specs and recorded decisions do not authorize a lesser fix; surface conflicts and propose a superseding decision with evidence.

Code Style (C#)

• Namespaces: file-scoped (namespace Foo;), not block-scoped — enforced as warning in .editorconfig
• var: use var only when type is apparent; use explicit types elsewhere
• Braces: omit only for single-line; use braces when multiline
• Expression bodies: prefer for single-line properties and accessors
• Usings: System namespaces first; no blank line between using groups; remove unused usings before merge
• Nullability: enable nullable reference types; use ?? and null-conditional operators; no unchecked ! except in tests
• Async: all async methods suffixed Async; no async void except event handlers

Layering Rules

• RoslynMcp.Host.Stdio may depend on RoslynMcp.Core and RoslynMcp.Roslyn
• RoslynMcp.Roslyn may depend on RoslynMcp.Core
• RoslynMcp.Core has no intra-project dependencies — DTOs and contracts only
• Do NOT let raw Roslyn types (SyntaxNode, ISymbol, etc.) cross the RoslynMcp.Core boundary
• Do NOT put transport-specific logic in RoslynMcp.Roslyn
• stdout is reserved for MCP protocol traffic — use stderr for all operational logging

Roslyn MCP (AI sessions in this repo)

• Expect the roslyn MCP server from user/session-scoped client configuration (roslynmcp via stdio). Do not add or depend on a repo-local registration; verify liveness with server_heartbeat or server_info before relying on it.
• Read-side tools are the default for every session — including bootstrap self-edit on this repo — and are 5–30× faster than Grep / Bash: dotnet build / Bash: dotnet test. Specifically: prefer compile_check over dotnet build, test_related_files + test_run --filter over dotnet test, find_references / symbol_search over Grep, document_symbols over eyeballing. See ai_docs/bootstrap-read-tool-primer.md for the full pattern→tool table.
• Write-side on peer repos: prefer Roslyn MCP refactoring tools over ad hoc multi-file text edits when a tool covers the operation (rename, extract/move type, code fixes, bulk type replace, etc.) — preview first, then apply.
• Write-side on THIS repo: depends on session shape.
  • Worktree session (default for /backlog-remediate delegated executors; running against the installed global roslynmcp tool): *_apply is safe — use it when a Roslyn MCP refactor tool covers the operation. Load the worktree's own RoslynMcp.slnx; workspace_reload after apply if a downstream call needs fresh state.
  • Main-checkout self-edit (running dotnet run --project src/RoslynMcp.Host.Stdio against the checkout you're editing): *_apply is restricted because the binary servicing the call is the binary being edited; use Edit / Write. *_preview and all read-side tools remain fully supported.
• Canonical three-part policy: ai_docs/runtime.md (Roslyn MCP client policy).