refactor(work-items): rename scan skill to scan-todos - #269
Merged
Conversation
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 marketplace naming grammar (namespace supplies the object; the skill name completes it when the namespace alone misleads). Breaking: /work-items:scan no longer exists; invoke /work-items:scan-todos. No renames-map entry (settling-phase policy); plugin bumped 0.7.0 -> 0.8.0 with a CHANGELOG entry. All repo-wide references updated atomically; historical CHANGELOG entries left verbatim; the track skill's legacy-verb router now points "scan" at /work-items:scan-todos. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01YVApnNGoKxYMJKNQx1QK8C
This was referenced Jul 17, 2026
|
Claude finished @kyle-sexton's task in 1m 59s —— View job PR Review —
|
| Item | Result |
|---|---|
skills/scan-todos/ directory exists |
✓ |
Frontmatter name: scan-todos matches directory |
✓ |
Usage line scan-todos in SKILL.md body |
✓ |
evals.json skill_name + eval prompt updated |
✓ |
| All 4 sibling skill descriptions updated | ✓ (track, triage, work, decompose) |
reference/tracker-seam.md (2 occurrences) |
✓ |
reference/topic-docs.md |
✓ |
README.md (quick-start + skills table) |
✓ |
templates/checklist.md section header |
✓ |
plugin.json version 0.7.0 → 0.8.0 |
✓ |
CHANGELOG [0.8.0] breaking entry |
✓ |
| Historical CHANGELOG rows left verbatim | ✓ (intentional per policy) |
No stray work-items:scan outside CHANGELOG history |
✓ (grep clean) |
No stray skills/scan\b path references |
✓ (grep clean) |
Observations
Legacy-verb router is correct. track/SKILL.md line 74 preserves scan as the bare verb on the left of the routing arrow (the retired monolith sub-action) and routes it to /work-items:scan-todos. This is right — users who still type the old verb get a correct redirect, and the left side names the historical action, not the current skill.
Historical CHANGELOG entries are correctly left verbatim. The 0.7.0 migration table at CHANGELOG.md line 35 (/work-items:scan) and the 0.1.0 initial-release list at line 169 (scan) accurately describe what shipped at those versions. Rewriting them would falsify the historical record.
CHANGELOG [0.8.0] has no date. Keep a Changelog recommends ## [0.8.0] - YYYY-MM-DD, but all existing entries in this file (0.7.0, 0.6.0, 0.5.0, …) also omit dates, so this is consistent with the repo's established pattern. Not a concern.
No issues found. This is a well-executed, fully atomic rename — approved.
kyle-sexton
added a commit
that referenced
this pull request
Jul 17, 2026
## 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>
kyle-sexton
added a commit
that referenced
this pull request
Jul 17, 2026
## 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>
kyle-sexton
added a commit
that referenced
this pull request
Jul 17, 2026
) 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>
kyle-sexton
added a commit
that referenced
this pull request
Jul 17, 2026
## What Renames the `toolchain` plugin's `build` skill to `check` — 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:check` command; frontmatter `name` moved with it) - Repo-wide reference sweep: every living reference to `/toolchain:build` updated — `verification:confirm`'s Stage-1 delegation, `implementation:implement` / `implement-dispatch` build-gate references, `testing:*` SSOT citations, `toolchain:lint` / `toolchain:setup` cross-references, reference YAMLs, READMEs, evals, `docs/conventions/ecosystem-commands`, and the plugin-organization decision record's live seam reference - `toolchain` plugin bumped 0.1.1 → 0.2.0 with a breaking-rename CHANGELOG entry - No `renames`-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:build` no 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 note - `node scripts/validate-plugin-contracts.mjs` → pass (17 setup skills, 1377 plugin files) - `scripts/check-cross-plugin-source-drift.sh --check` → clean - `markdownlint-cli2` over touched markdown → 0 errors - Skill-name mechanics verified against https://code.claude.com/docs/en/skills (plugin skill command name = directory name, namespaced by plugin) Deliberate 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.json` `tags`/`keywords` keep "build" (still functionally descriptive); no vendor/ or `.work/` touched. 🤖 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, #270. --------- Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What
Renames the
work-itemsplugin'sscanskill toscan-todos— directory (plugins/work-items/skills/scan→scan-todosviagit mv), frontmattername, 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-itemsnamespace, barescanread 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 frontmatternamemove together.Breaking change
/work-items:scanno longer exists; invoke/work-items:scan-todos.renames-map entry (settling-phase policy: clean break + version bump).work-itemsplugin bumped 0.7.0 → 0.8.0 with aChanged (breaking)CHANGELOG entry.Changes
skills/scan/→skills/scan-todos/(SKILL.md+evals/evals.json); frontmattername: scan-todos; description sharpened to state the object (source comments, not tracker items); usage line and evalskill_name/prompt updated.track,triage,work,decomposedescriptions;track's scope note and legacy-verb router (scan→/work-items:scan-todos).reference/tracker-seam.md,reference/topic-docs.md,templates/checklist.md, pluginREADME.md.plugin.jsonversion bump; new[0.8.0]CHANGELOG entry.Deliberate skips
track/SKILL.mdlegacy-verb list keeps the old bare verbscanon the left of its routing arrow (it names the retired monolith sub-action).add.md, unrelated plugins) untouched..claude-plugin/marketplace.jsonuntouched — it carries no skill names or per-plugin version, and norenamesentry is added by policy.Verification
git grep "work-items:scan"→ onlyscan-todosforms and the preserved historical CHANGELOG rows.git grep "skills/scan\b"→ no hits.name: scan-todosmatchesskills/scan-todos/(invocation name derives from the directory per the official skills doc).🤖 Generated with Claude Code
https://claude.ai/code/session_01YVApnNGoKxYMJKNQx1QK8C
Related
No linked issue. Contract source: #256. Sibling shadowed-skill rename PRs: #268, #270, #271.