T-QL5F-skill-prose-codemod
Status: closed/done · Impact: high · Complexity: large
Flip every caller to the CLI. Twenty-three SKILL.md files still invoke
${CLAUDE_PLUGIN_ROOT}scripts/… or validators/… paths; per-skill
invariants.yaml files pin literal script names; two eval suites spawn
scripts by relative path and carry literal “script exists” tests. Until
this lands, the shims cannot be deleted and the ports serve no caller.
| Location | Role today |
|---|---|
plugin/skills/*/SKILL.md | 23 files invoke raw script/validator paths |
plugin/skills/orchestrate/invariants.yaml | pins count_inflight_tasks.ts literally (one of ~7 skills with path pins) |
plugin/skills/entities-audit/tests/run_evals.test.ts | spawns scripts/audit_entities.ts; literal “script exists” test |
plugin/skills/import-planning/tests/run_evals.test.ts | spawns scripts/scan_planning_candidates.ts; same pattern |
plugin/skills/standard-new/SKILL.md | shim refs handled earlier by T-JWP9-s0001-stragglers |
Proposed
Section titled “Proposed”Every invocation reads bun run "$CLAUDE_PLUGIN_ROOT"cli/sdlc.ts <path…>
(or bare sdlc where the skill already assumes PATH). Five codemod
classes, all blocking: (a) shim invocations → CLI verbs (new_task →
task create ×5 skills, new_milestone → milestone create ×4,
new_backlog → backlog create, audit_entities → entities audit ×4,
validate_frontmatter → entities validate ×14, validate_base →
entities validate --flavor base, migrate_entities → entities migrate); (b) renamed-op call sites (count_inflight_tasks → task inflight, run_quality_checks → quality run, status_dashboard →
dashboard *, find_todos → project scan todos,
scan_planning_candidates → project scan candidates,
lease_heartbeat_loop → lease heartbeat-loop, sdlc_lease.ts →
sdlc lease …); (c) invariants.yaml pins updated in the SAME commit as
that skill’s prose so the prose gate stays green per-commit; (d) both
eval suites spawn the CLI and drop the “script exists” tests; (e) the
verb map is taken from D-H7FS-op-substrate-surface verbatim.
Approach
Section titled “Approach”- Build the old-path → new-verb map from D-H7FS; verify every target verb dispatches
(
sdlc <path> --help). - Codemod per skill: SKILL.md + its invariants.yaml together, one commit per skill batch; run that skill’s evals + the prose lint per batch.
- Re-point the two run_evals suites to spawn
cli/sdlc.ts; rewrite their “script exists” assertions as “verb dispatches” assertions. - Sweep: grep proves zero scripts/validators references in live skill prose.
Files to touch
Section titled “Files to touch”| Location | Kind | Change |
|---|---|---|
plugin/skills/*/SKILL.md | modify | invocation lines → sdlc verbs (23 files) |
plugin/skills/orchestrate/invariants.yaml | modify | tool pins → sdlc verbs |
plugin/skills/import-planning/invariants.yaml | modify | same |
plugin/skills/entities-audit/tests/run_evals.test.ts | modify | spawn CLI; drop script-exists test |
plugin/skills/import-planning/tests/run_evals.test.ts | modify | same |
Acceptance criteria
Section titled “Acceptance criteria”- AC-1:
grep -rEn '\$\{?CLAUDE_PLUGIN_ROOT\}?/?(scripts|validators)/' plugin/skills/**/SKILL.mdreturns zero hits. - AC-2: every invariants.yaml
tool:/phrase:pin referencing an old script name is updated; skill-prose lint green on every commit of this task. - AC-3: both eval suites green spawning
cli/sdlc.ts; no test asserts aplugin/scripts/file exists. - AC-4: every renamed verb has at least one live caller (task inflight, quality run, dashboard, project scan {todos,candidates}, entities validate).
Out of scope
Section titled “Out of scope”- Deleting the shims (T-YBKU-shim-deletion-guard — gated on this task).
- docs/ and site/ prose (T-YXM5-site-docs-long-tail).
- Behavior changes in any skill flow.
Dependencies
Section titled “Dependencies”- All port tasks: T-JWP9-s0001-stragglers T-Y1L0-entities-validate-absorb T-FNUT-quality-noun-ports T-IDW6-task-inflight-project-scans T-6FBO-project-plugin-ports T-WC1T-lefthook-gate-ports T-ZSSE-task-sort-registry-move T-NFSM-project-cleanup-port T-2W56-lease-noun-migration T-OSEH-long-running-services T-VK8L-pr-classify-port — every verb must exist before its caller flips.
Discovery context
Section titled “Discovery context”- D-0007 §Migration step 5 (codemod the callers); refutation re-baselined the count from 17 files/65 sites to 23 files and surfaced the invariants-pin and eval-spawn classes.
Depends on
Section titled “Depends on”T-JWP9-s0001-stragglers, T-Y1L0-entities-validate-absorb, T-FNUT-quality-noun-ports, T-IDW6-task-inflight-project-scans, T-6FBO-project-plugin-ports, T-WC1T-lefthook-gate-ports, T-ZSSE-task-sort-registry-move, T-NFSM-project-cleanup-port, T-2W56-lease-noun-migration, T-OSEH-long-running-services, T-VK8L-pr-classify-port