How codewithmukesh/dotnet-claude-kit works
1. What this repository is
- dotnet-claude-kit is not an application; it is a developer-assistance product for Claude Code and compatible AI coding tools.
- Its architecture is centered on instruction assets, workflow orchestration, and a Roslyn-based MCP server that analyzes .NET solutions.
2. Top-level subsystem layout
- The repo is split into four main functional layers:
- Instruction layer: skills, rules, agents, knowledge, templates.
- Automation layer: hooks and workflow scripts.
- Analysis layer: the CWM.RoslynNavigator MCP server.
- Distribution/compatibility layer: plugin manifests, IDE/CLI configs, and GitHub release workflows.
3. Instruction and policy layer
- .claude/rules/ holds always-on conventions such as coding style, architecture, testing, security, performance, and error handling.
- skills/ contains the reusable knowledge and workflows Claude loads for specific tasks; some are reference-only, others are command-driven orchestrators like /scaffold, /tdd, /verify, and /code-review.
- agents/ defines specialist roles that constrain behavior and route work to the right skill/tool combination.
- knowledge/ stores durable guidance and ADRs that justify defaults such as Result-over-exceptions, EF Core as default ORM, HybridCache, and multi-architecture support.
4. Workflow orchestration
- Slash-command workflows are the operational entry points: project setup, spec/plan, scaffolding, testing, verification, build fixing, security scanning, and cleanup.
- These workflows do not execute business logic themselves; they compose skills + agents + MCP tools into a guided sequence.
- The design goal is to move from “generic assistant” to “architecture-aware operator” with bounded task flows.
5. Roslyn MCP server as the analysis engine
- mcp/CWM.RoslynNavigator/ is the only substantial runtime component.
- It is a .NET Roslyn-powered MCP server that inspects solutions and exposes semantic tools such as symbol lookup, references, call graphs, dependency graphs, diagnostics, dead-code detection, public API extraction, and test coverage mapping.
- This is the main boundary between the AI layer and the user’s codebase: Claude queries the MCP server instead of reading whole files when possible.
6. Data flow through the analysis layer
- The MCP server starts from solution/workspace discovery, then initializes a Roslyn workspace, and maintains workspace state.
- Tool handlers in src/Tools/ query that workspace and return compact response models from src/Responses/.
- Higher-level agents use these results to make architecture and refactoring decisions, which is how the repo achieves token-efficient code navigation and codebase-aware advice.
7. Automation and safety hooks
- hooks/ contains Claude Code hooks and supporting scripts that enforce quality gates around edits, builds, and destructive commands.
- Examples include automatic C# formatting after edits, restoring packages after project-file changes, blocking risky shell commands, and analyzing test output.
- These hooks form a guardrail boundary: they do not design code, but they enforce repository conventions and reduce accidental damage.
8. Templates and project bootstrapping
- templates/ provides ready-made CLAUDE.md starting points for common .NET project types: web API, modular monolith, Blazor app, worker service, and class library.
- These templates are the bridge from the toolkit into a target application repository: they encode the repo’s recommended architecture defaults in a copyable form.
- skills/project-setup and skills/scaffold are the dynamic counterpart to these static templates, generating or adapting setup based on the target solution.
9. Compatibility and distribution surfaces
- .claude-plugin/ contains plugin metadata for Claude Code marketplace installation.
- .cursor/, .codex/, .opencode/, opencode.json, and mcp-configs/ provide compatibility with other AI coding environments.
- This means the repo has a clear separation between the core content and the host-specific packaging/configuration used to activate it.
10. Testing and validation architecture
- The MCP server has its own test project under mcp/CWM.RoslynNavigator/tests/.
- Tests cover workspace discovery, MSBuild registration, solution parsing, and every MCP tool surface.
- A sample multi-project solution under tests/TestData/SampleSolution/ acts as the integration fixture for dependency graphs, symbol lookup, and anti-pattern analysis.
11. CI and release pipeline
- .github/workflows/validate.yml and publish-nuget.yml indicate a release process that validates the repo and publishes the MCP server as a NuGet tool/package.
- The repo is therefore both a content distribution package and a .NET tool project, with GitHub Actions acting as the release gate.
12. Important architectural boundary
- The key boundary in this repo is between:
- static guidance assets used by AI tooling, and
- executable analysis tooling in the Roslyn MCP server.
- Most of the repository is declarative knowledge and orchestration; only the MCP server is a conventional .NET codebase that processes source trees, solution graphs, and diagnostics.
13. How to diagram it
- A useful architecture diagram should show Claude Code or another AI host loading:
- rules, skills, agents, and templates from the repo,
- MCP configuration pointing to the Roslyn server,
- hooks intercepting edits/commands,
- the MCP server analyzing a target .NET solution,
- and GitHub Actions publishing/validating the package.
- The target application codebase is external to this repo and should be drawn as the analysis subject, not as part of the toolkit itself.
Main entry points: CWM.RoslynNavigator Roslyn MCP · skills Skills · Tools Tools · tests MCP tests
Components 20
Instruction layer
Static guidance assets loaded by AI hosts.
- Rules · Always-on conventions for coding, architecture, testing, security, performance, hooks, and errors.
.claude/rules - Skills · Reusable task workflows and command-driven orchestrators for planning, scaffolding, TDD, verification, review, and related tasks.
skills - Agents · Role definitions that steer work to the appropriate skill/tool combination.
agents - Knowledge · Durable guidance, decisions, and architecture notes used to justify defaults.
knowledge - Templates · Starter instruction templates for common .NET project types.
templates
Automation layer
Hooks and workflow scripts that enforce repo conventions.
- Hooks · Pre/post action hooks that validate edits, commands, builds, and test output.
hooks - Hook scripts · Concrete automation used by hooks for formatting, restore, validation, and safety checks.
hooks
Analysis layer
Roslyn-based MCP server that inspects .NET solutions.
- Roslyn MCP · Executable analysis service for solution discovery, symbol navigation, dependency analysis, diagnostics, and coverage mapping.
mcp/CWM.RoslynNavigator - Discovery · Finds solutions and initializes the Roslyn workspace.
mcp/CWM.RoslynNavigator/src/SolutionDiscovery.cs - Workspace · Owns workspace initialization and mutable solution state.
mcp/CWM.RoslynNavigator/src/WorkspaceManager.cs - Symbols · Resolves symbols and feeds navigation queries across the codebase.
mcp/CWM.RoslynNavigator/src/SymbolResolver.cs - Tools · Tool handlers that expose symbol, graph, diagnostics, API, and coverage operations.
mcp/CWM.RoslynNavigator/src/Tools - Analyzers · Roslyn detectors for code smells and policy violations.
mcp/CWM.RoslynNavigator/src/Analyzers - Responses · Compact response types returned by tool handlers.
mcp/CWM.RoslynNavigator/src/Responses/ToolResponses.cs - MCP tests · Validation for discovery, registration, workspace behavior, and every tool surface.
mcp/CWM.RoslynNavigator/tests - Sample solution · Integration fixture used to exercise dependency graphs, symbol lookup, and anti-pattern detection.
mcp/CWM.RoslynNavigator/tests/TestData/SampleSolution
Distribution layer
Plugin, host-compatibility, and release surfaces.
- Plugin manifest · Claude Code plugin metadata for marketplace installation.
.claude-plugin - Host configs · Integration surfaces for Claude Code, Cursor, Codex, OpenCode, and MCP host setup.
.mcp.json - CI workflows · Validation and publish workflows for packaging and releasing the toolkit and NuGet tool.
.github/workflows
Other components
- Target solution · The user’s application repository being analyzed and guided; external to this toolkit.
Connections 21
- Rules → Skills: constrains · Rules shape how skills should behave and what conventions they must enforce.
- Skills → Agents: dispatches to · Skills route work to specialist agents when needed.
- Skills → Templates: bootstraps from · Project setup and scaffolding skills reuse template instruction starters.
- Knowledge → Skills: informs · Architecture decisions and durable guidance inform task workflows.
- Agents → Roslyn MCP: use analysis · Specialist agents rely on the Roslyn MCP server for codebase-aware reasoning.
- Templates → Target solution: seed · Templates are copied into or adapted for the target repository.
- Hooks → Hook scripts: executes · Hook definitions invoke the supporting shell scripts.
- Hook scripts → Target solution: guard edits · Scripts validate formatting, restores, tests, and risky operations against the target repo.
- Roslyn MCP → Discovery: starts with · The server locates solutions and creates workspace context.
- Roslyn MCP → Workspace: maintains · Workspace state is managed as the server answers analysis requests.
- Workspace → Symbols: enables · Workspace state supports semantic symbol resolution and navigation.
- Symbols → Tools: feeds · Tool handlers reuse symbol and workspace queries.
- Tools → Responses: returns · Tools emit compact structured response models.
- Tools → Target solution: analyzes · Tools inspect the external solution and return graphs, diagnostics, APIs, and coverage.
- Analyzers → Tools: supports · Anti-pattern detectors are surfaced through analysis tools.
- MCP tests → Roslyn MCP: verifies · Tests validate the server, registration, discovery, and tools.
- MCP tests → Sample solution: uses fixture · The sample solution provides integration coverage for analysis behaviors.
- Plugin manifest → Host configs: packages with · Marketplace metadata and host configuration define installation surfaces.
- Host configs → Roslyn MCP: launches · Host configuration points AI tools at the Roslyn MCP server.
- CI workflows → Plugin manifest: publishes · Release workflows validate and publish the toolkit artifacts.
- CI workflows → Roslyn MCP: builds · CI validates and publishes the executable analysis component.