dotnet-pilot: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Repository Context

This repo IS the DotnetPilot plugin source — not a .NET project. There is no dotnet build to run here; artifacts are Markdown (agents/commands/skills) and Node/shell scripts (hooks). When editing this repo, you are authoring plugin behavior that runs inside other .NET projects.

Layout

• .claude-plugin/plugin.json — plugin manifest (name, version, mcpServers pointer)
• .claude-plugin/marketplace.json — marketplace listing for plugin distribution
• .mcp.json — MCP server declarations (roslyn server dnp-roslyn configured)
• agents/dnp-*.md — 15 agents with YAML frontmatter (name, description, tools, model, effort, color, permissionMode). The tools field uses Claude Code's scoped syntax (e.g. Bash(dotnet:*))
• commands/<category>/<name>.md — slash commands invoked as /dotnet-pilot:<category>:<name>. Categories: project, dotnet, quality, utility
• hooks/hooks.json — hook registry wiring matchers to scripts via ${CLAUDE_PLUGIN_ROOT}
• hooks/dnp-*.js — 7 advisory hooks (all exit 0; emit additionalContext for guidance). Read a JSON event from stdin.
• hooks/_lib/config.js — shared module used by every hook. Resolves .planning/config.json: repo-local path first, then user-scoped at ~/.claude/projects/<flattened-cwd>/ (where D:\Projects\Foo → D--Projects-Foo). All hooks default-on when config is absent.
• rules/global-claude-md.md — template block injected into ~/.claude/CLAUDE.md by dnp-sync-global-claude-md.js on version change (versioned markers keep it idempotent)
• skills/<name>/SKILL.md — skill packs loaded on demand (aspnet-api-patterns, ef-core-patterns, testing-dotnet, clean-architecture, blazor-patterns, dotnet-project-init)

Authoring Rules

• Hooks must be advisory by default. Exit 0 even on findings; emit guidance via additionalContext. Only block (non-zero exit) for hard safety violations. All hooks respect .planning/config.json hooks.* toggles and default-on when the file is absent.
• Hook paths use ${CLAUDE_PLUGIN_ROOT}, never relative paths — the CWD at runtime is the consumer project, not this repo.
• All hooks share _lib/config.js. When adding a new hook, import { hookEnabled } from there — don't re-implement config resolution.
• dnp-commit-format skips heredoc commits. Claude Code's default multi-line commit workflow (-m "$(cat <<'EOF'...)") is deliberately excluded — the hook only validates plain -m "..." strings.
• Commands are thin orchestrators. Heavy logic belongs in agents. A command file is the spec that Claude reads when the slash command fires; it should enumerate steps and which agents to spawn, not re-implement their work.
• Agent frontmatter tools: is a whitelist. Adding a tool requires justification; prefer narrower scopes (Bash(dotnet:*)) over broad ones.
• Model tier by agent role. Planning/architecture → opus; implementation/review → sonnet; mechanical checks (DI, NuGet audit, scaffolding) → sonnet at effort: low; deep read-only consults → fable.
• Every agent and command declares effort:. Model tier sets capability, effort: (low|medium|high|xhigh|max) sets reasoning spend within it. Do NOT pair effort: with model: haiku — effort is unsupported on Haiku 4.5 and the field is silently dropped, which is why the mechanical agents run on sonnet at effort: low instead of haiku.
• Agent prompts carry gotchas, not guardrails. Write what is specific to .NET and to this plugin — missing DI registration throwing at runtime, migrations needing their own step, the in-memory EF provider diverging from SQL Server. Do not add anti-rationalization tables, epistemic-gate checklists, "predict before you grep" protocols, or few-shot transcripts of ideal output: they re-encode judgment the model already has, and every added constraint is another chance to contradict a neighbouring one. Domain reference material (test tiers, mock fidelity, boundary coverage) belongs in a skills/ file the agent loads via skills:, not inlined in the prompt.
• State a fact in exactly one place. Tool guidance goes in the tool or agent description; routing goes in this file; conventions go in a skill. A hook that re-injects a roster this file already carries pays for the same tokens on every call.
• shell: is not used here. It only governs !-blocks in command frontmatter, and no dotnet-pilot command uses one — adding it would be dead config. If you introduce a !-block that shells out on Windows, add shell: powershell to that command.