# codewithmukesh/dotnet-claude-kit architecture

> Architecture diagram of the GitHub repository codewithmukesh/dotnet-claude-kit, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-07-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/codewithmukesh/dotnet-claude-kit
- Repository: https://github.com/codewithmukesh/dotnet-claude-kit

## Overview

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: [`mcp/CWM.RoslynNavigator`](https://github.com/codewithmukesh/dotnet-claude-kit/blob/main/mcp/CWM.RoslynNavigator) (Roslyn MCP), [`skills`](https://github.com/codewithmukesh/dotnet-claude-kit/tree/main/skills) (Skills), [`mcp/CWM.RoslynNavigator/src/Tools`](https://github.com/codewithmukesh/dotnet-claude-kit/blob/main/mcp/CWM.RoslynNavigator/src/Tools) (Tools), [`mcp/CWM.RoslynNavigator/tests`](https://github.com/codewithmukesh/dotnet-claude-kit/blob/main/mcp/CWM.RoslynNavigator/tests) (MCP tests)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_instruction["Instruction layer"]
  node_claude_rules["Rules<br/>policy pack<br/>[rules]"]
  node_skills["Skills"]
  node_agents["Agents<br/>specialist roles"]
  node_knowledge["Knowledge<br/>guidance docs"]
  node_templates["Templates<br/>bootstrap CLAUDE.md"]
end

subgraph group_automation["Automation layer"]
  node_hooks["Hooks<br/>guardrail scripts"]
  node_hook_scripts["Hook scripts<br/>shell scripts"]
end

subgraph group_analysis["Analysis layer"]
  node_mcp_server["Roslyn MCP<br/>.NET MCP server"]
  node_solution_discovery["Discovery<br/>workspace bootstrap"]
  node_workspace["Workspace<br/>state management"]
  node_symbol_resolution["Symbols<br/>semantic lookup<br/>[SymbolResolver.cs]"]
  node_tools["Tools<br/>[Tools]"]
  node_analyzers["Analyzers<br/>anti-pattern detectors<br/>[Analyzers]"]
  node_responses["Responses<br/>result models<br/>[ToolResponses.cs]"]
  node_mcp_tests["MCP tests<br/>test suite<br/>[tests]"]
  node_sample_solution[("Sample solution<br/>fixture solution<br/>[SampleSolution]")]
end

subgraph group_distribution["Distribution layer"]
  node_plugin_manifest["Plugin manifest<br/>marketplace metadata<br/>[.claude-plugin]"]
  node_host_configs["Host configs<br/>compatibility config<br/>[.mcp.json]"]
  node_ci_workflows["CI workflows<br/>release pipeline<br/>[workflows]"]
end

node_target_codebase[("Target solution<br/>external .NET repo")]

node_claude_rules -->|"constrains"| node_skills
node_skills -->|"dispatches to"| node_agents
node_skills -->|"bootstraps from"| node_templates
node_knowledge -->|"informs"| node_skills
node_agents -->|"use analysis"| node_mcp_server
node_templates -->|"seed"| node_target_codebase
node_hooks -->|"executes"| node_hook_scripts
node_hook_scripts -->|"guard edits"| node_target_codebase
node_mcp_server -->|"starts with"| node_solution_discovery
node_mcp_server -->|"maintains"| node_workspace
node_workspace -->|"enables"| node_symbol_resolution
node_symbol_resolution -->|"feeds"| node_tools
node_tools -->|"returns"| node_responses
node_tools -->|"analyzes"| node_target_codebase
node_analyzers -->|"supports"| node_tools
node_mcp_tests -->|"verifies"| node_mcp_server
node_mcp_tests -->|"uses fixture"| node_sample_solution
node_plugin_manifest -->|"packages with"| node_host_configs
node_host_configs -->|"launches"| node_mcp_server
node_ci_workflows -->|"publishes"| node_plugin_manifest
node_ci_workflows -->|"builds"| node_mcp_server

click node_claude_rules "https://github.com/codewithmukesh/dotnet-claude-kit/blob/main/.claude/rules"
click node_skills "https://github.com/codewithmukesh/dotnet-claude-kit/tree/main/skills"
click node_agents "https://github.com/codewithmukesh/dotnet-claude-kit/tree/main/agents"
click node_knowledge "https://github.com/codewithmukesh/dotnet-claude-kit/tree/main/knowledge"
click node_templates "https://github.com/codewithmukesh/dotnet-claude-kit/tree/main/templates"
click node_hooks "https://github.com/codewithmukesh/dotnet-claude-kit/tree/main/hooks"
click node_hook_scripts "https://github.com/codewithmukesh/dotnet-claude-kit/tree/main/hooks"
click node_mcp_server "https://github.com/codewithmukesh/dotnet-claude-kit/blob/main/mcp/CWM.RoslynNavigator"
click node_solution_discovery "https://github.com/codewithmukesh/dotnet-claude-kit/blob/main/mcp/CWM.RoslynNavigator/src/SolutionDiscovery.cs"
click node_workspace "https://github.com/codewithmukesh/dotnet-claude-kit/blob/main/mcp/CWM.RoslynNavigator/src/WorkspaceManager.cs"
click node_symbol_resolution "https://github.com/codewithmukesh/dotnet-claude-kit/blob/main/mcp/CWM.RoslynNavigator/src/SymbolResolver.cs"
click node_tools "https://github.com/codewithmukesh/dotnet-claude-kit/blob/main/mcp/CWM.RoslynNavigator/src/Tools"
click node_analyzers "https://github.com/codewithmukesh/dotnet-claude-kit/blob/main/mcp/CWM.RoslynNavigator/src/Analyzers"
click node_responses "https://github.com/codewithmukesh/dotnet-claude-kit/blob/main/mcp/CWM.RoslynNavigator/src/Responses/ToolResponses.cs"
click node_mcp_tests "https://github.com/codewithmukesh/dotnet-claude-kit/blob/main/mcp/CWM.RoslynNavigator/tests"
click node_sample_solution "https://github.com/codewithmukesh/dotnet-claude-kit/blob/main/mcp/CWM.RoslynNavigator/tests/TestData/SampleSolution"
click node_plugin_manifest "https://github.com/codewithmukesh/dotnet-claude-kit/blob/main/.claude-plugin"
click node_host_configs "https://github.com/codewithmukesh/dotnet-claude-kit/blob/main/.mcp.json"
click node_ci_workflows "https://github.com/codewithmukesh/dotnet-claude-kit/blob/main/.github/workflows"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_claude_rules,node_skills,node_agents,node_knowledge,node_templates toneBlue
class node_hooks,node_hook_scripts toneAmber
class node_mcp_server,node_solution_discovery,node_workspace,node_symbol_resolution,node_tools,node_analyzers,node_responses,node_mcp_tests,node_sample_solution toneMint
class node_plugin_manifest,node_host_configs,node_ci_workflows toneRose
class node_target_codebase toneNeutral
```

## Components

### Instruction layer

Static guidance assets loaded by AI hosts.

- [Rules](https://github.com/codewithmukesh/dotnet-claude-kit/blob/main/.claude/rules): policy pack · Always-on conventions for coding, architecture, testing, security, performance, hooks, and errors. · `.claude/rules`
- [Skills](https://github.com/codewithmukesh/dotnet-claude-kit/tree/main/skills): workflow skills · Reusable task workflows and command-driven orchestrators for planning, scaffolding, TDD, verification, review, and related tasks. · `skills`
- [Agents](https://github.com/codewithmukesh/dotnet-claude-kit/tree/main/agents): specialist roles · Role definitions that steer work to the appropriate skill/tool combination. · `agents`
- [Knowledge](https://github.com/codewithmukesh/dotnet-claude-kit/tree/main/knowledge): guidance docs · Durable guidance, decisions, and architecture notes used to justify defaults. · `knowledge`
- [Templates](https://github.com/codewithmukesh/dotnet-claude-kit/tree/main/templates): bootstrap CLAUDE.md · Starter instruction templates for common .NET project types. · `templates`

### Automation layer

Hooks and workflow scripts that enforce repo conventions.

- [Hooks](https://github.com/codewithmukesh/dotnet-claude-kit/tree/main/hooks): guardrail scripts · Pre/post action hooks that validate edits, commands, builds, and test output. · `hooks`
- [Hook scripts](https://github.com/codewithmukesh/dotnet-claude-kit/tree/main/hooks): shell 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](https://github.com/codewithmukesh/dotnet-claude-kit/blob/main/mcp/CWM.RoslynNavigator): .NET MCP server · Executable analysis service for solution discovery, symbol navigation, dependency analysis, diagnostics, and coverage mapping. · `mcp/CWM.RoslynNavigator`
- [Discovery](https://github.com/codewithmukesh/dotnet-claude-kit/blob/main/mcp/CWM.RoslynNavigator/src/SolutionDiscovery.cs): workspace bootstrap · Finds solutions and initializes the Roslyn workspace. · `mcp/CWM.RoslynNavigator/src/SolutionDiscovery.cs`
- [Workspace](https://github.com/codewithmukesh/dotnet-claude-kit/blob/main/mcp/CWM.RoslynNavigator/src/WorkspaceManager.cs): state management · Owns workspace initialization and mutable solution state. · `mcp/CWM.RoslynNavigator/src/WorkspaceManager.cs`
- [Symbols](https://github.com/codewithmukesh/dotnet-claude-kit/blob/main/mcp/CWM.RoslynNavigator/src/SymbolResolver.cs): semantic lookup · Resolves symbols and feeds navigation queries across the codebase. · `mcp/CWM.RoslynNavigator/src/SymbolResolver.cs`
- [Tools](https://github.com/codewithmukesh/dotnet-claude-kit/blob/main/mcp/CWM.RoslynNavigator/src/Tools): MCP tools · Tool handlers that expose symbol, graph, diagnostics, API, and coverage operations. · `mcp/CWM.RoslynNavigator/src/Tools`
- [Analyzers](https://github.com/codewithmukesh/dotnet-claude-kit/blob/main/mcp/CWM.RoslynNavigator/src/Analyzers): anti-pattern detectors · Roslyn detectors for code smells and policy violations. · `mcp/CWM.RoslynNavigator/src/Analyzers`
- [Responses](https://github.com/codewithmukesh/dotnet-claude-kit/blob/main/mcp/CWM.RoslynNavigator/src/Responses/ToolResponses.cs): result models · Compact response types returned by tool handlers. · `mcp/CWM.RoslynNavigator/src/Responses/ToolResponses.cs`
- [MCP tests](https://github.com/codewithmukesh/dotnet-claude-kit/blob/main/mcp/CWM.RoslynNavigator/tests): test suite · Validation for discovery, registration, workspace behavior, and every tool surface. · `mcp/CWM.RoslynNavigator/tests`
- [Sample solution](https://github.com/codewithmukesh/dotnet-claude-kit/blob/main/mcp/CWM.RoslynNavigator/tests/TestData/SampleSolution): fixture 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](https://github.com/codewithmukesh/dotnet-claude-kit/blob/main/.claude-plugin): marketplace metadata · Claude Code plugin metadata for marketplace installation. · `.claude-plugin`
- [Host configs](https://github.com/codewithmukesh/dotnet-claude-kit/blob/main/.mcp.json): compatibility config · Integration surfaces for Claude Code, Cursor, Codex, OpenCode, and MCP host setup. · `.mcp.json`
- [CI workflows](https://github.com/codewithmukesh/dotnet-claude-kit/blob/main/.github/workflows): release pipeline · Validation and publish workflows for packaging and releasing the toolkit and NuGet tool. · `.github/workflows`

### Other components

- **Target solution**: external .NET repo · The user’s application repository being analyzed and guided; external to this toolkit.

## Connections

- 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.
