fix(toolchain): frame dotnet.md dotnet-msbuild build-diagnostics refs as .NET forward references (#412)

[kyle-sexton]

Summary

plugins/toolchain/skills/check/context/dotnet.md lists dotnet-msbuild:* build-diagnostics plugin skills (build-perf-diagnostics, binlog-failure-analysis, msbuild-antipatterns, and others) under a ## Marketplace plugin skills for build diagnostics (invoke only when installed) presence gate. No dotnet-* plugin ships in this marketplace today — but per the ratified #412 disposition (maintainer answer 2026-07-19, control-tower relay 2026-07-20) these are optional FORWARD references to the maintainer's planned dotnet-* plugin family (.NET is the primary application stack), not stale references to remove.

Fix

Add a lead-in to the presence-gated list that frames it as .NET-ecosystem skills — applicable when the stack is .NET — and as forward references to the planned dotnet-* family: invoke each only when its plugin is installed, otherwise fall back to the section's own prose remediation and binlog gotcha (the generic path stays first-class).

Framing only — the ratified disposition is keep tool names + stack framing, presence-gate forward references, no reference removal:

• Every dotnet-msbuild:* skill name is kept verbatim.
• Nothing is removed, renamed, or genericized.
• No command string is altered (dotnet build /bl:{} unchanged).

This matches the presence-gated forward-reference convention the merged siblings #491 (testing) and #526 (verification, issue #422) adopted — each added a ".NET-ecosystem plugin skills — applicable when your stack is .NET" framing line over the same dotnet-*/dotnet-diag:* lists.

Bumps toolchain 0.4.2 → 0.4.3 (patch) with a matching ### Changed CHANGELOG entry.

Rework note

An earlier revision of this branch took the OPPOSITE approach — it genericized the dotnet-msbuild:* names into ecosystem-neutral capability descriptions, reading #412's original "replace with capability descriptions" fix-direction literally. The control-tower ruling relayed on this PR (2026-07-20) identified that as the inverse of the ratified disposition and required rework to the #491/#526 keep-tool-names pattern. This revision implements that rework. Sibling PR #580 (issue #405, implementation) is governed by the same ruling.

Verification

Cumulative branch diff vs main is exactly: the framing lead-in sentence, the version bump, and the CHANGELOG entry — no other change to dotnet.md.

Validators run on the merged tree (branch rebased current via a main merge), all clean, nothing suppressed:

markdownlint-cli2 (dotnet.md, CHANGELOG.md)        0 error(s)
typos (3 touched files)                            exit 0
editorconfig-checker (3 touched files)             exit 0
check-skill-portability.sh origin/main             No unexcused coupling tokens in 1 skill file(s)
validate-plugins.sh                                All plugin manifests and the catalog validated
validate-plugin-contracts.mjs                      33 setup skills and 1758 plugin files checked

Closes #412

Related

• Closes toolchain: dotnet.md references dotnet-msbuild:* plugin skills that do not exist in this marketplace #412 (source issue — dotnet-msbuild:* forward references in toolchain's dotnet.md).
• implementation: .NET-only marketplace-skill references in every mode context (origin coupling, low severity) #405 (implementation) / PR feat(implementation): make implement mode-context optional-collaborator refs ecosystem-neutral #580 — sibling finding, same pattern, same ruling, fixed in parallel.
• fix(testing): guard unguarded dotnet cross-plugin ref, frame .NET enrichment lists as stack-specific #491 (testing) and fix(verification): presence-gate dotnet/cloudflare cross-plugin refs in measure contexts #526 (verification, issue verification: bare unguarded cross-plugin references to dotnet-*/cloudflare plugins in measure contexts #422) — merged siblings whose keep-tool-names + stack-framing pattern this PR now conforms to.

🤖 Generated with Claude Code

[claude]

Claude finished @kyle-sexton's task in 1m 21s —— View job

---

PR Review #583 — fix(toolchain): replace stale dotnet-msbuild plugin-skill refs

Tasks

• Gather context and understand the request
• Read changed files and diff
• Review for correctness, security, and CLAUDE.md alignment
• Post findings

---

Summary

The fix is correct and the premise is verified. No dotnet-* plugin exists in this marketplace — grep confirms the dotnet-msbuild:* strings appear only in prose context files across the repo, never in an installable plugin manifest. The three-file change achieves its stated goal cleanly.

---

plugins/toolchain/skills/check/context/dotnet.md

Heading reword (line 72) — "invoke only when installed" → "invoke when an installed plugin provides them" is clearer about the condition (the skill must exist in what's installed, not just that something is installed).

Intro paragraph (line 74) — "fall back to the prose remediation and the binlog gotcha above" cross-references the ## Gotchas bullet at line 50. The phrase works top-to-bottom but "the binlog gotcha above" is informal and could be ambiguous to a reader skimming to this section. Minor, not blocking.

Binlog command (line 77) — Old text used dotnet build /bl:{} (the {} placeholder was awkward prose); the new dotnet build -bl matches the Gotchas section at line 50 exactly. This is a quiet correctness improvement.

Actionability trade-off — Genericizing to capability descriptions removes the plugin:skill hook a consumer could call directly. This is the right call here (the named plugin doesn't exist), but it means a consumer who does have a compatible plugin has to guess the skill name. That's unavoidable given the absence of a published dotnet-msbuild plugin; the gate text mitigates it by describing what to look for.

---

plugins/toolchain/.claude-plugin/plugin.json

Version bump 0.4.2 → 0.4.3 is appropriate: patch level for a content-only fix in a context markdown file. No structural change to the manifest.

---

plugins/toolchain/CHANGELOG.md

Entry follows Keep a Changelog format correctly (### Fixed, present-tense description, issue reference). The explanation is thorough and accurately describes both what was removed and what replaced it. One cosmetic note: the entry is unusually long for a changelog bullet (about 10 lines of wrapped prose). That's a style choice, not an error — the existing 0.4.2 entries follow the same verbose pattern.

---

Convention inconsistency (flagged by author, no action needed here)

The PR description correctly notes that siblings #491 (testing) and #526 (verification, issue #422) merged with the opposite approach — keeping dotnet-msbuild:* / dotnet-diag:* skill names with a stack-framing line. My grep confirms those files still carry named references:

• plugins/testing/skills/diagnose/context/investigate.md — dotnet-msbuild:binlog-failure-analysis, dotnet-diag:analyzing-dotnet-performance
• plugins/verification/skills/measure/context/performance.md — dotnet-msbuild:build-perf-baseline, dotnet-msbuild:build-perf-diagnostics, dotnet-diag:*
• plugins/implementation/skills/implement/context/bugfix.md and refactor.md — multiple dotnet-msbuild:* and dotnet-diag:* refs (open issue implementation: .NET-only marketplace-skill references in every mode context (origin coupling, low severity) #405)

The author is right to flag this for maintainer reconciliation. The two conventions are genuinely incompatible: either named skills are valid references (keep them, add framing) or they're broken references (genericize). This PR correctly applies the genericize path to the one file that's its scope.

---

Verdict

No blocking issues. The fix is correct, the version bump is appropriate, and all three files are internally consistent. The convention inconsistency across the broader plugin set is real and documented — it's a maintainer-level reconciliation item (#412's linked siblings), not a defect in this PR.

[kyle-sexton]

Control-tower ruling relay (2026-07-20) — REWORK REQUIRED before ready-flip. This draft implements the genericized style, which is the OPPOSITE of the ratified #412 disposition (maintainer + relay, 7/19): KEEP tool names + stack framing, presence-gate forward references per the #491/#526 conforming pattern, no reference removal. Rework the diff to that pattern, then proceed with the normal post-green flow. Same ruling governs sibling PR #580 (#405).

[claude]

Claude finished @kyle-sexton's task in 3m 4s —— View job

---

PR #583 — Rework complete: conforming pattern applied

Tasks

• Gather context and understand the rework request
• Read conforming sibling files (fix(testing): guard unguarded dotnet cross-plugin ref, frame .NET enrichment lists as stack-specific #491 testing, fix(verification): presence-gate dotnet/cloudflare cross-plugin refs in measure contexts #526 verification) to extract the pattern
• Read current state of dotnet.md and other changed files
• Rework dotnet.md to keep dotnet-msbuild:* tool names + add stack-framing line
• Update CHANGELOG.md entry to reflect the revised approach
• Verify the full diff matches the conforming convention

---

The rework was completed in commit 67571b3 and the branch is in the correct state. No further changes are needed.

What was done

plugins/toolchain/skills/check/context/dotnet.md — The genericized approach was reversed. Section now reads:

## Marketplace plugin skills for build diagnostics (invoke only when installed)

These are .NET-ecosystem plugin skills — applicable when your stack is .NET — and forward references
to the planned `dotnet-*` plugin family: invoke each only when its plugin is installed, otherwise fall
back to the prose remediation and the binlog gotcha above.

- **Slow builds** — `dotnet-msbuild:build-perf-diagnostics` for bottleneck analysis via binary logs,
  `dotnet-msbuild:build-perf-baseline` for before/after measurement
- **Build failures** — `dotnet-msbuild:binlog-failure-analysis` to diagnose opaque MSBuild errors,
  `dotnet-msbuild:binlog-generation` for binary log capture (`dotnet build /bl:{}`)
- **Build config issues** — `dotnet-msbuild:msbuild-antipatterns` for AP-01 through AP-21,
  `dotnet-msbuild:check-bin-obj-clash` for OutputPath conflicts

All dotnet-msbuild:* skill names are kept. Framing only — no reference removed, renamed, or genericized. This matches the testing (#491) and verification (#526) conforming siblings exactly.

plugins/toolchain/CHANGELOG.md — Entry changed from ### Fixed + "stale cross-plugin coupling removed" to ### Changed + "Presence-gated dotnet-msbuild:* build-diagnostics references reframed as .NET-ecosystem forward references." Framing-only change, no removal.

plugins/toolchain/.claude-plugin/plugin.json — Version remains 0.4.3 (patch bump is appropriate for the content-only context file change).

Pattern conformance check

Convention	#491 sibling	#526 sibling	This PR
invoke only when installed header	✓	✓	✓
.NET-ecosystem stack framing	✓	✓	✓
dotnet-msbuild:* names kept	✓	✓	✓
Fallback-to-prose instruction	✓	✓	✓
No reference removed	✓	✓	✓

The PR is aligned with the ratified #412 disposition and ready for the normal post-green flow.

[kyle-sexton]

Rework complete — now conforms to the ratified #412 disposition. (Kept DRAFT for the owning lane's post-green ready-flip.)

What changed vs the flagged revision. The prior diff genericized the dotnet-msbuild:* names into ecosystem-neutral capability descriptions — the OPPOSITE of the ruling. This revision reverses that and applies the #491/#526 pattern instead.

Compliance with the ruling (keep tool names + stack framing, presence-gate forward references, no reference removal):

• ✅ Tool names kept — all six dotnet-msbuild:* skill names (build-perf-diagnostics, build-perf-baseline, binlog-failure-analysis, binlog-generation, msbuild-antipatterns, check-bin-obj-clash) restored verbatim.
• ✅ Stack framing added — lead-in frames the list as ".NET-ecosystem plugin skills — applicable when your stack is .NET — and forward references to the planned dotnet-* plugin family", matching the merged testing (fix(testing): guard unguarded dotnet cross-plugin ref, frame .NET enrichment lists as stack-specific #491) / verification (fix(verification): presence-gate dotnet/cloudflare cross-plugin refs in measure contexts #526) framing convention.
• ✅ Presence-gate preserved — the (invoke only when installed) heading is restored; the lead-in keeps the generic prose/binlog fallback first-class.
• ✅ No reference removed, renamed, or genericized; no command string altered (dotnet build /bl:{} unchanged).

Diff shape. Cumulative vs main = framing lead-in sentence + 0.4.2 → 0.4.3 bump + ### Changed CHANGELOG entry. Nothing else in dotnet.md moved.

Base + CI. Branch merged up to current origin/main (append-only, clean — the main-ahead commits don't touch toolchain), so the base is current. Local validators all green: markdownlint, typos, editorconfig, check-skill-portability.sh, validate-plugins.sh, validate-plugin-contracts.mjs. CI running.

Commits. 67571b3 (rework) + ffe16d7 (merge main), on top of the branch's original b7b8a9f. Squash-merge repo, so history collapses to the PR title on merge. No review threads were open to resolve.

Sibling PR #580 (#405, implementation) is governed by the same ruling.

[claude]

Claude finished @kyle-sexton's task in 1m 31s —— View job

---

PR Review #583 — fix(toolchain): frame dotnet.md dotnet-msbuild build-diagnostics refs as .NET forward references

Tasks

• Gather context and understand the request
• Read changed files and diff
• Review for correctness, pattern conformance, and CLAUDE.md alignment
• Post findings

---

Summary

The fix is correct and properly implements the ratified #412 disposition (keep tool names + stack framing + forward reference language, no removal). Three-file change: 2 lines added to dotnet.md, version bump, and CHANGELOG entry.

---

plugins/toolchain/skills/check/context/dotnet.md

Heading (line 72) — ## Marketplace plugin skills for build diagnostics (invoke only when installed) is appropriate: the "for build diagnostics" qualifier is specific to this section's scope, and the (invoke only when installed) presence gate is preserved verbatim. This diverges slightly from the sibling heading style (## Marketplace plugin skills (invoke only when installed)) but the narrower qualifier is accurate here.

Lead-in sentence (line 74) — The wording is longer than sibling framing lines but carries additional information the siblings don't need: the "forward references to the planned dotnet-* plugin family" qualifier is specific to this file's situation (no dotnet-msbuild:* plugin ships in this marketplace today) and correctly contextualizes the skill names as forward references, not stale coupling. The "otherwise fall back to the prose remediation and the binlog gotcha above" fallback is a useful consumer instruction and cross-references the Gotchas section at line 50.

All 6 dotnet-msbuild:* names preserved — build-perf-diagnostics, build-perf-baseline, binlog-failure-analysis, binlog-generation, msbuild-antipatterns, check-bin-obj-clash (lines 76–78). Nothing removed, renamed, or genericized. ✓

dotnet build /bl:{} (line 77) — unchanged from original, consistent with the PR's "no command string altered" guarantee. Note: the Gotchas section at line 50 uses the shorter -bl flag while this bullet uses /bl:{} (a path-argument form with a placeholder). These are distinct but both valid MSBuild invocations — the /bl:{} form conveys that binlog-generation can target a specific output path. Pre-existing inconsistency, not introduced by this PR.

---

Pattern conformance vs. sibling files

Grepping the merged siblings confirms the framing convention is present:

File	Heading	Lead-in
testing/…/investigate.md	(invoke only when installed)	"These are .NET-ecosystem plugin skills — applicable when your stack is .NET:"
verification/…/performance.md	(invoke only when installed)	"These enrichment skills are stack-specific — the dotnet-* skills apply when your stack is .NET…"
verification/…/metrics.md	(invoke only when installed)	"These are .NET-ecosystem plugin skills — invoke each only when your stack is .NET and its plugin is installed…"
This PR toolchain/…/dotnet.md	for build diagnostics (invoke only when installed)	"These are .NET-ecosystem plugin skills — applicable when your stack is .NET — and forward references…"

The lead-in here is the longest and adds the "forward references to the planned dotnet-* plugin family" phrase. Given that this file's skill names have no backing plugin yet (confirmed: no dotnet-msbuild or dotnet-* manifest exists in the repo), the explicit forward-reference framing is the right call and distinguishes this from the siblings where the skills may be installable.

---

plugins/toolchain/.claude-plugin/plugin.json

Version 0.4.2 → 0.4.3 is correct: patch bump for a content-only context file change. No structural manifest change. ✓

---

plugins/toolchain/CHANGELOG.md

Entry at [0.4.3] ### Changed (lines 6–19) follows Keep a Changelog format. ### Changed is the correct category (framing addition, not a defect fix). The description accurately conveys "framing only — no skill reference removed, renamed, or genericized." The entry is verbose but matches the existing style of prior entries in this file.

---

CLAUDE.md alignment

Criterion	Status
Repo-agnostic — no hardcoded paths or repo names	✓
Plugin-form-safe — no ../ reach-outs or state outside ${CLAUDE_PLUGIN_ROOT}	✓
Versioned — explicit semver bump present	✓
PR title follows Conventional Commits	✓
Squash-merge safe — history collapses cleanly	✓

---

Verdict

No blocking issues. The diff is minimal and correct: 2 lines added to dotnet.md, a version bump, and a CHANGELOG entry. The forward-reference framing accurately describes the situation and conforms to the ratified disposition. Ready for the normal post-green flow.