refactor(toolchain): rename build skill to check#271
Conversation
BREAKING CHANGE: /toolchain:build is now /toolchain:check. The skill runs build + test + lint as a deterministic pass/fail gate, and per the marketplace naming grammar (docs/topics/shadowed-skill-renames/PLAN.md) `check` = gate; "build" is also a null phase for several covered ecosystems (Python, Markdown). Skill directory, frontmatter name, and all repo-wide references move together; description keeps the "build" / "does it compile" / "run tests" triggers. No renames-map entry (clean breaking change); toolchain plugin bumped 0.1.1 -> 0.2.0 with a CHANGELOG entry. Historical CHANGELOG entries in other plugins intentionally keep the old name. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01YVApnNGoKxYMJKNQx1QK8C
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: e9ac67a4cb
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
## What Renames the `debugging` plugin's sole skill: `/debugging:diagnose` → `/debugging:debug`. One atomic rename PR per the shadowed-skill-renames contract (#256): directory (`git mv`) and frontmatter `name` move together, and all repo-wide references update in the same PR. - `plugins/debugging/skills/diagnose/` → `plugins/debugging/skills/debug/` (all bundled files) - Frontmatter `name: debug`; description unchanged — already third-person what+when, and keeps "diagnose this" as a trigger phrase - Internal `${CLAUDE_PLUGIN_ROOT}/skills/diagnose/...` paths, self-references, checklist/reference headers, and evals updated - `plugins/debugging/README.md` invocation line updated - `plugins/verification/skills/confirm/evals/evals.json` boundary notes updated - `docs/MIGRATION-PLAYBOOK.md` non-router-skill example updated - `plugins/debugging` bumped 0.3.0 → **0.4.0** (0.x breaking-by-minor precedent); new `CHANGELOG.md` with the breaking entry ## Why The skill runs the full repro → hypothesize → fix → regression-test loop; "diagnose" promised only the first half, and twinned confusingly with the unrelated `/testing:diagnose` (a read-only test-failure investigator that keeps its name). Pre-migration shadow-compromise naming is no longer needed now that plugin namespacing exists. ## Breaking change - `/debugging:diagnose` no longer resolves; invoke `/debugging:debug`. Clean break — no `renames`-map entry per the contract (marketplace `renames` map unchanged; its existing `"diagnose": "debugging"` entry is the historical plugin-level rename). - No collision with Claude Code's built-in bundled `/debug` skill: plugin skills have no bare command form, so the plugin skill is only reachable as the namespaced `/debugging:debug`. ## Deliberate skips - `plugins/testing/**` — `/testing:diagnose` is a different skill and keeps its name. - `docs/topics/plugin-organization/PLAN.md` — historical record of the earlier plugin reorganization (its D3/D13 rows describe decisions as made at the time). - `.claude-plugin/marketplace.json` — `renames` map untouched (contract constraint); the `diagnose` tag stays as a discovery keyword, mirroring the retained trigger word. - `plugin.json` `keywords` keeps `diagnose` as a discovery keyword. ## Verification - `git grep -n "debugging:diagnose"` → 0 hits - `git grep -n "skills/diagnose"` → 0 hits - `git grep -nE "(^|[^a-z:])/diagnose\b"` → 0 hits - Remaining `diagnose` hits in `plugins/debugging` are the deliberate trigger word in the skill description and the plugin keyword - Edited JSON files parse cleanly 🤖 Generated with [Claude Code](https://claude.com/claude-code) https://claude.ai/code/session_01YVApnNGoKxYMJKNQx1QK8C ## Related No linked issue. Contract source: #256. Sibling shadowed-skill rename PRs: #269, #270, #271. Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
## What Renames the `work-items` plugin's `scan` skill to `scan-todos` — directory (`plugins/work-items/skills/scan` → `scan-todos` via `git mv`), frontmatter `name`, and every live repo-wide reference, atomically in one PR. One of the sequenced shadowed-skill-rename PRs (contract: `docs/topics/shadowed-skill-renames/PLAN.md`, PR #256). ## Why Under the `work-items` namespace, bare `scan` read as scanning tracker items. The skill sweeps the codebase's **source comments** for TODO/FIXME/HACK/XXX markers (and can resolve or file each) — the name now states its object. Per the fetched skills doc (https://code.claude.com/docs/en/skills), the invocation name comes from the skill directory name, so the directory and frontmatter `name` move together. ## Breaking change - `/work-items:scan` no longer exists; invoke `/work-items:scan-todos`. - No `renames`-map entry (settling-phase policy: clean break + version bump). - `work-items` plugin bumped **0.7.0 → 0.8.0** with a `Changed (breaking)` CHANGELOG entry. ## Changes - `skills/scan/` → `skills/scan-todos/` (`SKILL.md` + `evals/evals.json`); frontmatter `name: scan-todos`; description sharpened to state the object (source comments, not tracker items); usage line and eval `skill_name`/prompt updated. - Sibling-skill cross-references updated: `track`, `triage`, `work`, `decompose` descriptions; `track`'s scope note and legacy-verb router (`scan` → `/work-items:scan-todos`). - Shared docs: `reference/tracker-seam.md`, `reference/topic-docs.md`, `templates/checklist.md`, plugin `README.md`. - `plugin.json` version bump; new `[0.8.0]` CHANGELOG entry. ## Deliberate skips - Historical CHANGELOG entries (0.7.0 migration table and older) left verbatim. - `track/SKILL.md` legacy-verb list keeps the old bare verb `scan` on the left of its routing arrow (it names the retired monolith sub-action). - English-verb "scan"/"scanning" prose (plugin description, `add.md`, unrelated plugins) untouched. - `.claude-plugin/marketplace.json` untouched — it carries no skill names or per-plugin version, and no `renames` entry is added by policy. ## Verification - `git grep "work-items:scan"` → only `scan-todos` forms and the preserved historical CHANGELOG rows. - `git grep "skills/scan\b"` → no hits. - Skill-name/directory agreement: `name: scan-todos` matches `skills/scan-todos/` (invocation name derives from the directory per the official skills doc). 🤖 Generated with [Claude Code](https://claude.com/claude-code) https://claude.ai/code/session_01YVApnNGoKxYMJKNQx1QK8C ## Related No linked issue. Contract source: #256. Sibling shadowed-skill rename PRs: #268, #270, #271. Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
|
Claude finished @kyle-sexton's task in 2m 54s —— View job PR Review: refactor(toolchain): rename build skill to check
SummaryMechanically clean PR — the rename is complete, all active cross-references are updated, evals are consistent, and the breaking version bump with CHANGELOG is correct. One issue to resolve before merge: companion plugins that reference ✅ What's correctRename completeness. Toolchain version bump. 0.1.1 → 0.2.0 is the right call for a breaking rename. The CHANGELOG entry is clear, accurate, and explains the migration path ( Evals.
No security concerns. The PR is a rename + reference sweep with no new command execution surfaces, egress, or trust delegation.
|
| Plugin | Current version | Files changed |
|---|---|---|
implementation |
0.6.0 | implement/SKILL.md, implement-dispatch/SKILL.md, evals |
testing |
0.1.0 | diagnose/SKILL.md, e2e/context/non-ui.md, plan/SKILL.md, write/SKILL.md, README |
verification |
0.1.0 | confirm/SKILL.md, confirm/evals, measure/SKILL.md, README |
source-control |
0.5.0 | pull-request/reference/prep.md |
Why this matters. Claude Code's version management skips re-downloading a plugin whose installed version matches the available version (plugin version management). A consumer who updates toolchain to 0.2.0 (where /toolchain:build no longer exists) while their implementation, testing, verification, or source-control caches remain at the unchanged version number will pull the cached copy — which still calls /toolchain:build — breaking implement's Step 2 build gate, verify/confirm's Stage 1 prerequisite, and testing:write's run-tests pointer. The version number is the signal the tooling uses to detect "there is something new to fetch here."
Each of these is a patch-level content change (no interface contract change — just an internal cross-reference update), so the bump level is .patch:
implementation: 0.6.0 → 0.6.1testing: 0.1.0 → 0.1.1verification: 0.1.0 → 0.1.1source-control: 0.5.0 → 0.5.1
Each bumped plugin should also add a CHANGELOG entry — e.g.:
## [0.6.1]
### Changed
- Updated `/toolchain:build` cross-reference to `/toolchain:check` following the `toolchain` 0.2.0 breaking rename.Minor observations (non-blocking)
plugins/implementation/README.md "previous skill names" section. The PR correctly leaves the old /toolchain:build name in the historical migration list as an intentional record. Worth a comment in the PR description confirming this is deliberate (it is, per the PR body, but a code comment near the list or a README note makes the intent durable for future maintainers).
plugins/toolchain/CHANGELOG.md 0.1.0 entry. The 0.1.0 note still says "/toolchain:build ... /toolchain:lint ... /toolchain:setup" — that's historical and should stay as-is (documents what the original release shipped). The 0.2.0 entry correctly describes the rename. No change needed, just confirming the intentional preservation.
Verdict: Approve after resolving the companion plugin version bumps. The rename itself is correct and complete.
implementation, testing, verification, and source-control carry rewritten prompts referencing /toolchain:check; without a version bump existing installs would keep stale copies calling the removed /toolchain:build. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01YVApnNGoKxYMJKNQx1QK8C
## What Renames the `machine-health` plugin's `check` skill to `audit` — directory (`skills/check/` → `skills/audit/`) and frontmatter `name` move together — with all repo-wide references updated atomically. Part of the shadowed-skill-renames program (contract: `docs/topics/shadowed-skill-renames/PLAN.md`, PR #256). ## Why The skill emits a findings report (dated markdown, CRIT/WARN/UNKNOWN sections, trend deltas), not a deterministic pass/fail gate. The marketplace naming grammar reserves `check` for deterministic gates and `audit` for read-only reports. "check" / "health check" remain as description trigger phrases so discovery is unaffected. ## Breaking change - `/machine-health:check` → `/machine-health:audit`. The plugin ID (`machine-health`) is unchanged. - Plugin version bumped `0.4.0` → `0.5.0` (0.x breaking-by-minor precedent) with a CHANGELOG breaking-rename entry. - No `renames`-map entry, per the program constraint (clean break while the marketplace settles). ## Follow-up noted (not fixed here) The audit contract requires bare invocation to be read-only, with mutation only behind an explicit user override. Today, remediations default to **not approved** (`approvals.json` empty; first run forces dry-run), so a bare invocation on a fresh install never mutates. However, once a user seeds approvals via `/machine-health:setup`, subsequent bare `weekly`/`on-demand` invocations execute those pre-approved remediations without a per-invocation flag (`DryRun` defaults to `$false`). Whether persistent approval satisfies the "explicit user override (flag/argument)" clause, or the default should flip to dry-run absent a flag, is left as a follow-up decision — behavior is intentionally unchanged in this PR. ## Deliberate skips - `plugins/machine-health/CHANGELOG.md` `[0.4.0]` entry still says `/machine-health:check` — historical record, not rewritten. - Schema `$id` URNs `urn:claude-code-plugin:machine-health:check-result` / `...:checks` — these name the check-result/catalog schemas (individual *checks* remain the domain vocabulary), not the skill. - `docs/topics/plugin-organization/PLAN.md` D17 (`machine-health` → `check`) — historical decision record. - `check-catalog.md` reference filenames and all `Test-*`/`*Check*` script names — domain vocabulary for individual checks, unchanged. ## Verification - `git grep -n "machine-health:check"` → only the historical 0.4.0 CHANGELOG entry, the new 0.5.0 migration note, and the schema URNs above. - `git grep -nE 'skills[/\]check\b'` → clean (forward- and backslash path forms swept, including PowerShell examples in the skill README and testing reference). - Frontmatter `name: audit` matches the directory name (agentskills.io constraint). - marketplace.json `renames` map untouched. 🤖 Generated with [Claude Code](https://claude.com/claude-code) https://claude.ai/code/session_01YVApnNGoKxYMJKNQx1QK8C ## Related No linked issue. Contract source: #256. Sibling shadowed-skill rename PRs: #268, #269, #271. Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
|
Claude finished @kyle-sexton's task in 1m 18s —— View job PR Review: refactor(toolchain): rename build skill to check
Fix verified — ready to mergeThe follow-up commit (
Each has a clear, consistent CHANGELOG entry (
Zero live No security concerns. No structural issues. This is a clean, complete rename with all the right SemVer signals in place for the version management system to pick up. |
|
Claude finished @kyle-sexton's task in 1m 33s —— View job PR Review: refactor(toolchain): rename build skill to check
Post-merge check: cleanThe
The prior blocking finding (missing companion plugin version bumps) was resolved in No issues. This PR is ready to merge. |
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 06c660b90d
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
|
Claude finished @kyle-sexton's task in 2m 32s —— View job PR Review: refactor(toolchain): rename build skill to check
Codex P2 analysis: non-blockingThe latest Codex review raises a concern about mixed-version installs where The existing "when installed" guard is partial, not complete. All companion skills already guard gracefully for toolchain-absent: "invoke The plugin system does support version constraints (plugin-dependencies) — the fix would be adding Why the mixed-version scenario is low-risk in practice:
Conclusion: The Codex P2 is a valid observation but not a blocker. The right follow-up, if the team wants to close the gap, is a standalone PR that adds Overall verdict: ready to mergeAll prior findings are resolved, the rename is complete and consistent, the companion version bumps are correct, and zero live |
) Codifies the marketplace naming convention in PLUGIN-PHILOSOPHY: - Imperative-verb grammar; namespace supplies the object. Documented deviation from the official gerund preference (sanctioned alternative + collection-consistency requirement), chosen for sentence-composability. - Fixed verb meanings: `audit`/`scan` read-only (mutation only behind explicit override), `check` = pass/fail gate, `clean`/`tidy`/`fix` mutate, `setup`, `update`. - Sanctioned exceptions: knowledge/lifecycle-object noun routers, vendor-wrapper stutter, `-deep` isolation tier. - Cross-plugin reference rule: declared `dependencies` (auto-install) or "if installed" guard — bare references are defects. - Adds the `shadowed-skill-renames` topic contract (interview output) that drives the follow-up rename PRs. Sources fetched this session, linked in Authoritative references (verified 2026-07-17). No external content copied. 🤖 Generated with [Claude Code](https://claude.com/claude-code) https://claude.ai/code/session_01YVApnNGoKxYMJKNQx1QK8C ## Related No linked issue. Companion doctrine PR: #257. Drives the follow-up shadowed-skill rename PRs: #268, #269, #270, #271. --------- Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
What
Renames the
toolchainplugin'sbuildskill tocheck— one atomic rename PR from the shadowed-skill-renames plan (docs/topics/shadowed-skill-renames/PLAN.md, PR #256):git mv plugins/toolchain/skills/build plugins/toolchain/skills/check(directory name is what sets the/toolchain:checkcommand; frontmatternamemoved with it)/toolchain:buildupdated —verification:confirm's Stage-1 delegation,implementation:implement/implement-dispatchbuild-gate references,testing:*SSOT citations,toolchain:lint/toolchain:setupcross-references, reference YAMLs, READMEs, evals,docs/conventions/ecosystem-commands, and the plugin-organization decision record's live seam referencetoolchainplugin bumped 0.1.1 → 0.2.0 with a breaking-rename CHANGELOG entryrenames-map entry, per the plan's constraint (clean breaking change while the marketplace settles)Why
The skill runs build + test + lint as a deterministic pass/fail gate; per the marketplace naming grammar
check= deterministic gate. "build" is also a null phase for several covered ecosystems (Python, Markdown), so the old name under-described what the skill does. Description keeps the "build", "does it compile", "run tests" trigger phrases so auto-invocation behavior is unchanged.Breaking
/toolchain:buildno longer exists — invoke/toolchain:check. Arguments, behavior, and the resolution ladder are unchanged. Consumers get the rename via the 0.2.0 plugin bump; there is no automatic renames-map migration.Verification
git grep toolchain:build→ hits only in historical CHANGELOG entries (implementation, testing, verification, source-control, toolchain 0.1.0) and the new 0.2.0 breaking-rename notenode scripts/validate-plugin-contracts.mjs→ pass (17 setup skills, 1377 plugin files)scripts/check-cross-plugin-source-drift.sh --check→ cleanmarkdownlint-cli2over touched markdown → 0 errorsDeliberate skips: historical CHANGELOG entries and the pre-split skill-name list in
plugins/implementation/README.md's migration section keep the old name as historical record;marketplace.jsontags/keywordskeep "build" (still functionally descriptive); no vendor/ or.work/touched.🤖 Generated with Claude Code
https://claude.ai/code/session_01YVApnNGoKxYMJKNQx1QK8C
Related
No linked issue. Contract source: #256. Sibling shadowed-skill rename PRs: #268, #269, #270.