dotnet-copilot

.NET AI Toolkit

Agentic workflow orchestration for .NET development — works in Claude Code and GitHub Copilot CLI.

Purpose-built for .NET 8/9/10/11 — C#, ASP.NET Core (Web API + Minimal API), Entity Framework Core, Blazor (Server/WASM/Hybrid), .NET MAUI, WPF, and xUnit. Ships 40 skills, 20 specialist agents, 20 hooks, and 34

.NET Iron Laws enforced programmatically.

> Plan → Work → Review → Compound. Filesystem is the state machine.

The same /dotnet:* slash commands work in both tools. Claude Code is the primary target; the Copilot CLI variant is auto-generated from the same source, so features stay in sync.

---

Table of Contents

• What You Get
• Installation
• Claude Code
• GitHub Copilot CLI
• Compatibility
• Command Cheat Sheet
• Quickstart
• Architecture
• The 34 Iron Laws
• Supported .NET Surface
• Quality Gates
• Contributing
• License
• Credits

---

What You Get

• 40 skills — progressive-disclosure reference docs auto-loaded by

file pattern (e.g., editing *Controller.cs loads api-design).

• 20 specialist agents — orchestrators, reviewers, architects, and

analysts, each with a specific model tier (opus / sonnet / haiku).

• 20 hook scripts — auto dotnet format, Iron Law grep, NuGet

vulnerability scan, secret-in-config blocker, PreCompact rule re-injection.

• 34 Iron Laws — C#, EF Core, ASP.NET Core, Blazor, MAUI/WPF,

security, DI, and verification. Injected into every subagent via

SubagentStart hook.

• Eval framework — 8-dimension skill scoring + 5-dimension agent

scoring. Deterministic, runnable with make eval.

• Compound knowledge — every solved bug can be captured to

.claude/solutions/{category}/ for future retrieval.

---

Installation

Claude Code

Requires Claude Code ≥2.1.98 (for /reload-plugins). Pick one:

From the marketplace (recommended once published):

/plugin marketplace add dimsour/dotnet-ai-toolkit
/plugin install dotnet

Local path:

git clone https://github.com/dimsour/dotnet-ai-toolkit ~/plugins/dotnet-ai-toolkit
claude --plugin-dir ~/plugins/dotnet-ai-toolkit/plugins/dotnet

Local marketplace:

git clone https://github.com/dimsour/dotnet-ai-toolkit
cd dotnet-ai-toolkit
# Inside Claude Code:
/plugin marketplace add .
/plugin install dotnet

GitHub Copilot CLI

Requires Copilot CLI ≥1.0.32. The marketplace ships a sibling plugin, dotnet-copilot, auto-generated from the same source so slash commands stay identical.

/plugin marketplace add dimsour/dotnet-ai-toolkit
/plugin install dotnet-copilot@dotnet-ai-toolkit

One-time hook activation — workaround for copilot-cli#2540, where plugin-shipped hooks.json doesn't currently fire:

bash ~/.copilot/installed-plugins/dotnet-ai-toolkit/dotnet-copilot/setup-hooks.sh

Verify

In either tool, run in a .NET repo:

/dotnet:help

You should see the command index. Start the tutorial with /dotnet:intro.

---

Compatibility

| Tool | Plugin | Slash commands | Hooks | Multi-agent | |------|--------|----------------|-------|-------------| | Claude Code ≥2.1.98 | dotnet | /dotnet: | Plugin-shipped, automatic | Parallel (Agent tool) | | Copilot CLI ≥1.0.32 | dotnet-copilot | /dotnet: | Requires one-time setup-hooks.sh | Sequential subagent invocation |

plugins/dotnet/ is the single source of truth. plugins/dotnet-copilot/ is regenerated by make build-copilot (script: scripts/build-copilot-plugin.py) — never hand-edit it.

The transformer:

• Renames agents/.md → agents/.agent.md (Copilot's required extension)
• Drops Claude-only frontmatter keys (disallowedTools, permissionMode, omitClaudeMd, skills, effort, memory, maxTurns)
• Strips the dotnet: prefix from skill name: — also works around Claude bug #22063
• Flattens hook keys Copilot ignores (if, matcher, async, statusMessage)
• Writes the manifest to both .copilot-plugin/plugin.json and .claude-plugin/plugin.json (Copilot checks both paths)

Known limits of the Copilot variant:

• hooks.json needs the one-time setup-hooks.sh step until #2540 ships
• Agent fields effort and memory are silently ignored — no functional impact
• Multi-agent orchestration runs sequentially rather than via Claude's parallel Agent tool

---

Command Cheat Sheet

Workflow (the main cycle)

| Command | Phase | Typical next step | |---------|-------|-------------------| | /dotnet:plan <feature> | Plan | /dotnet:work | | /dotnet:plan --existing <plan> | Enhance | /dotnet:work | | /dotnet:brief <plan> | Understand | /dotnet:work | | /dotnet:work | Execute | /dotnet:review | | /dotnet:review | Quality | /dotnet:triage | | /dotnet:triage | Prioritize | fix + /dotnet:compound | | /dotnet:compound | Capture | (future cycles search it) |

Standalone

| Command | Use when | |---------|----------| | /dotnet:full <feature> | Run plan → work → review → compound autonomously | | /dotnet:quick <small change> | Trivial change (<50 lines) | | /dotnet:brainstorm <topic> | Explore options before planning | | /dotnet:investigate <bug> | Hard/recurring bug, spawns 4 parallel subagents | | /dotnet:verify | Run dotnet build, test, format --verify-no-changes | | /dotnet:research <topic> | External doc lookup via web-researcher | | /dotnet:research --library <pkg> | NuGet package evaluation |

Analysis

| Command | Produces | |---------|----------| | /dotnet:audit | Full health report from 5 specialists | | /dotnet:boundaries | Namespace/project layering violations | | /dotnet:techdebt | Ranked debt backlog | | /dotnet:perf <scenario> | Performance hypothesis report | | /dotnet:n-plus-one-check | EF N+1 scan with fixes | | /dotnet:migration-check | Safety review of pending migrations | | /dotnet:pr-review <#> | Multi-track PR review |

Utility

| Command | Use when | |---------|----------| | /dotnet:init | Initialize .claude/ dirs + seed .editorconfig | | /dotnet:intro | Interactive tutorial | | /dotnet:help | Full command index | | /dotnet:permissions | Configure Claude Code permission allowlists | | /dotnet:challenge | Aggressive senior-engineer review | | /dotnet:learn-from-fix | Extract a CLAUDE.md rule / Iron Law candidate | | /dotnet:document | Generate XML docs / README sections | | /dotnet:examples | Find canonical reference .NET projects |

---

Quickstart

Walk through a realistic flow — add a POST /api/orders endpoint with validation, EF persistence, and tests.

/dotnet:plan add POST /api/orders endpoint with validation, EF persistence, and integration tests

Output lands at .claude/plans/add-post-orders-endpoint/plan.md with:

• Research from nuget-researcher (FluentValidation?), ef-schema-designer, api-architect
• Task list with [ef], [api], [test], [security] annotations
• Iron Law compliance checklist

Next:

/dotnet:work

work reads plan.md, routes each task to the right specialist via annotations, updates checkboxes as it goes, writes progress to

plans/{slug}/progress.md.

Then:

/dotnet:review

Spawns 5 reviewers in parallel (C# idioms, security, tests, Iron Laws, verification). Consolidated summary at

plans/{slug}/reviews/summary.md.

Finally:

/dotnet:compound

If you fixed a surprising bug, captures it to

.claude/solutions/{category}/{slug}.md with YAML frontmatter. Future

/dotnet:investigate searches this folder first.

---

Architecture

┌───────────────────────────────────────────────────┐
│  User                                             │
└───────┬───────────────────────────────────────────┘
        │ /dotnet:plan
        ▼
┌───────────────────────┐     Spawns in parallel
│ planning-orchestrator │────────┐
└──────────┬────────────┘        │
           │                     ▼
   Phase 1: research   ┌─────────────────┐
           │           │ dotnet-patterns │
           │           │ nuget-researcher│
           │           │ web-researcher  │
           │           │ ef-schema-desig │
           │           └────────┬────────┘
           │                    │
           │                    ▼
   Phase 2: compress  ┌──────────────────┐
           │          │ context-supervis │
           │          └────────┬─────────┘
           │                   │
   Phase 3: plan              ▼
   synthesis         .claude/plans/{slug}/plan.md
           │
           ▼
┌───────────────────────┐
│ workflow-orchestrator │   owns the end-to-end cycle
└──────────┬────────────┘
           │
           ▼
    /dotnet:work → /dotnet:review → /dotnet:compound

Three-layer structure

1. Skills — reference docs (progressive disclosure). SKILL.md is short (≤150 lines); detail lives in references/*.md. 2. Agents — executors. They read skills + inject Iron Laws via

SubagentStart hook. 3. Hooks — deterministic safety net. Auto-format, Iron Law grep, CVE scan, PreCompact rule re-injection.

Filesystem-as-state-machine

.claude/
├── plans/{slug}/                 # Everything about one plan
│   ├── plan.md                   # The plan itself
│   ├── progress.md               # What's done
│   ├── scratchpad.md             # Dead-ends, decisions
│   ├── research/                 # Research agent output
│   ├── reviews/                  # Review agent output
│   └── summaries/                # context-supervisor output
├── solutions/{category}/         # Compound knowledge
│   ├── ef-issues/
│   ├── api-issues/
│   ├── blazor-issues/
│   └── ...
├── audit/                        # Audit reports
└── scratchpad/                   # Ad-hoc scratch

No agent ever holds state across sessions — it reads and writes the filesystem.

Context Supervisor Pattern

Any orchestrator that spawns ≥3 sub-agents routes their output through a context-supervisor (haiku) that compresses individual reports into a single consolidated summary. The parent agent reads only the summary — saves context budget, prevents exhaustion.

---

The 34 Iron Laws

Non-negotiable rules. Violations get flagged by the iron-law-judge agent and grepped by iron-law-verifier.sh.

C# Core (5)

1. decimal for money (never float/double) 2. await (never .Result / .Wait()) 3. using for IDisposable (await using for IAsyncDisposable) 4. CancellationToken flows through async 5. Honor nullable annotations (no ! to silence warnings)

EF Core (7)

6. AsNoTracking() for read-only queries 7. Parameterized SQL only (FromSqlInterpolated, never FromSqlRaw($"...{x}")) 8. One SaveChangesAsync per Unit of Work 9. .Include(...) before .Where(...) for eager loading 10. Index all foreign keys 11. No N+1 queries 12. HasPrecision(18, 2) on decimal columns

ASP.NET Core (6)

13. [Authorize] on all non-public endpoints 14. DTOs at API boundary — never entities 15. Validate at the boundary ([ApiController] or FluentValidation) 16. Rate limit auth endpoints 17. Restrict CORS — never AllowAnyOrigin() 18. Return ProblemDetails on errors

Blazor (4)

19. StateHasChanged from non-UI thread needs InvokeAsync 20. Use @key for dynamic lists 21. Never store secrets in Blazor WASM 22. Dispose subscriptions + timers

MAUI/WPF (3)

23. MVVM — no logic in code-behind 24. ObservableCollection<T> for bindable lists 25. Weak event patterns for long-lived publishers

Security (5)

26. Never string.Format/interpolate SQL 27. PasswordHasher<T> / Rfc2898DeriveBytes(100k+) — never MD5/SHA1 28. Secrets via User Secrets / Key Vault / env vars 29. JWT validates issuer + audience + lifetime + signing key 30. Anti-forgery tokens on state-changing forms

DI (3)

31. DbContext = Scoped 32. HttpClient via IHttpClientFactory 33. IOptions<T> over raw IConfiguration in hot paths

Verification (1)

34. Never claim done without dotnet build && dotnet test output

Full rationale for each is in CLAUDE.md.

---

Supported .NET Surface

• .NET 10 LTS (current LTS, supported through Nov 2028)
• .NET 11 (upcoming STS, preview)
• .NET 9 (previous STS, supported through May 2026)
• .NET 8 LTS (previous LTS, supported through Nov 2026)
• ASP.NET Core — Controllers + Minimal APIs, route groups,

auth/authz, rate limiting, OpenAPI, ProblemDetails middleware

• Entity Framework Core 8/9/10/11 — DbContext, migrations, LINQ

provider, AsNoTracking, AsSplitQuery, ExecuteUpdate/Delete,

FromSqlInterpolated

• Blazor — Server + WASM + Hybrid + Blazor United (.NET 8+

mixed render modes)

• .NET MAUI — Pages, Shell, DI via MauiAppBuilder, platform

services (SecureStorage, Connectivity, MediaPicker)

• WPF — Generic Host bootstrap, CommunityToolkit.Mvvm source

generators, compiled bindings, ObservableValidator

• Testing — xUnit (primary), NUnit, MSTest;

NSubstitute/Moq; WebApplicationFactory; Testcontainers; coverlet

• DI — Microsoft.Extensions.DependencyInjection (MEDI)
• Observability — ILogger<T>, LoggerMessage source gen,

OpenTelemetry (traces + metrics + logs), Serilog, Application Insights

---

Quality Gates

make help        # Show all commands
make lint        # Lint markdown
make lint-fix    # Auto-fix lint
make test        # Pytest suite (eval framework)
make eval        # Lint + score changed skills/agents only
make eval-all    # Score every skill + agent
make eval-fix    # Auto-fix lint + show failures + autoresearch hints
make validate    # Validate plugin manifest (claude plugin validate)
make ci          # Full CI pipeline

Eval Framework

Deterministic scoring across 8 skill dimensions and 5 agent dimensions:

Skills: completeness, accuracy, conciseness, triggering, safety, clarity, specificity, behavioral

Agents: completeness, accuracy, conciseness, safety, consistency

Every skill/agent edit should pass make eval. Low scores surface concrete gaps (missing Iron Laws section, too long, weak triggering keywords, missing code examples).

---

Contributing

git clone https://github.com/dimsour/dotnet-ai-toolkit
cd dotnet-ai-toolkit
npm install                      # Husky + markdownlint
pip install -r requirements.txt  # pytest + pyyaml
make eval-all                    # Baseline

• New agent: plugins/dotnet/agents/{name}.md — follow the frontmatter

template in CLAUDE.md. Keep under 300 lines (orchestrators ≤535).

• New skill: plugins/dotnet/skills/{name}/SKILL.md — keep SKILL.md

under 150 lines, push detail to references/*.md. Description ≤250 chars. Add Iron Laws section.

• New hook: plugins/dotnet/hooks/scripts/{name}.sh + entry in

hooks.json. Use exit 2 + stderr for PostToolUse feedback.

• Run make eval after each change. Aim for composite ≥0.85.

See CLAUDE.md for the full plugin development guide including hook patterns, agent conventions, and the Iron Law rubric.

PR Checklist

• [ ] make lint passes
• [ ] make test passes
• [ ] make eval passes for changed skills/agents
• [ ] New Iron Laws (if any) added to CLAUDE.md,

inject-iron-laws.sh, and iron-law-judge.md — all three

• [ ] Description ≤250 chars for skills/agents
• [ ] No unreferenced references/*.md files

---

License

MIT — see LICENSE.

---

Credits

Architecture inspired by Oliver Kriska's claude-elixir-phoenix plugin. This repo adapts that agentic-workflow pattern to the .NET ecosystem. The skill-progressive-disclosure design, filesystem state machine, context-supervisor pattern, and eval framework architecture all trace to that project.

.NET Iron Laws distilled from:

• ASP.NET Core security documentation
• EF Core performance best practices
• OWASP Top 10
• Community wisdom — Andrew Lock, Stephen Toub, David Fowler, Nick

Chapsas, Scott Hanselman