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 — 9 agents with YAML frontmatter (name, description, tools, skills, model, effort, color). tools: lists exact tool names (Bash, Read, mcp__roslyn__*); plugin subagents ignore scoped tool forms, permission-mode keys, and the user-question tool, so none of those appear
• commands/<category>/<name>.md — 16 slash commands invoked as /dotnet-pilot:<category>:<name>. Categories: project, dotnet, quality, utility. Commands with side effects carry disable-model-invocation: true
• hooks/hooks.json — hook registry wiring matchers to scripts via ${CLAUDE_PLUGIN_ROOT}
• hooks/dnp-*.js — the hooks listed under Hook Behaviors below (advisory unless stated: 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). hookEnabled(cwd, key) keys default on when config is absent; hookFlag(cwd, key) keys are opt-in and default off
• hooks/hooks.json also declares "modules": ["./mods/register.ts"]: a Claude Code mod (no Node, no DOM; everything through $). hooks/mods/ holds register.ts (one module per plugin), build-status.ts (toasts at the 3rd/5th consecutive failure, streak in $.state), routing.ts (the module's single prompt.compose hook — the engine allows one per module and never follows $ across an import, so the routing and pressure sections are both built there), pressure.ts (a 0–100 pressure score from red runs / re-edits / corrections in $.ui.status, a toast or opt-in deny on test edits that loosen a test after a red run, a prompt.compose section only while the score is ≥ 60, and the /dnp-pressure command) and build-classify.ts, and pixel-city.tsx (the opt-in pixel_city band above the terminal prompt; its session.start is matched on { surface: 'terminal' } because pressure holds the module's one unmatched session.start, and /city is registered even with the option off so it can say how to enable it) with its painter — pixel-canvas.ts (canvas, noise, sprites, sun path), city-scene.ts (backdrop, city foreground, weather, cell encoding) and scene-beach.ts / scene-dino.ts / scene-sunset.ts; types/index.d.ts is the $.state contract, *.test.ts run with claude plugin test .. Mods are additive to the Node hooks and read only userConfig (build_status, routing, pressure, pressure_test_guard_block, pixel_city, pixel_city_scene), never .planning/config.json. The pressure mod is a behavioural proxy — it scores what the session shows (failures, retries, test edits), never the model's internal state; keep its wording to "pressure", not emotions
• hooks/_lib/routing.md — the routing text shared by dnp-dotnet-priority and the routing mod
• hooks/_lib/build-state.js — reader/writer for the build-fail state file shared by dnp-build-verify, dnp-stop-verify and the statusline (contract under Quality Gates)
• hooks/_lib/version.js — semver compare shared by the two sync hooks; hooks/_lib/json-file.js — BOM-preserving JSON read ({exists, ok, value, bom}) and atomic write for ~/.claude/settings.json, so an unparseable file is never overwritten
• hooks/__tests__/run.js, hooks/__tests__/check-consistency.js — hook harness and repo consistency gate (see Validating Plugin Changes); .github/workflows/hooks.yml runs both in CI
• workflows/dnp-review.js — the review Workflow, auto-discovered as /dotnet-pilot:dnp-review; started only by quality:review (see Review Workflow)
• scripts/dnp-review-preflight.js — Node preflight that shards a diff and writes the manifest the review Workflow consumes
• rules/global-claude-md.md — template block injected into ~/.claude/CLAUDE.md by dnp-sync-global-claude-md.js when the plugin version is newer than the installed block (versioned markers keep it idempotent)
• skills/<name>/SKILL.md — 15 skill packs loaded on demand via an agent's skills: list. Every SKILL.md carries when_to_use:; authentication, caching, ddd, error-handling, and resilience keep their detail in references/*.md
• CHANGELOG.md — Keep-a-Changelog history; the only place that names removed commands and agents