Migrating to v4.0¶
v4.0 is a MAJOR release. It removes nine skills that previously deployed as working commands. Everything else in this release is additive.
The constitution requires that deprecation warnings precede removal by at least one MINOR
release, and requires a migration guide for breaking changes. All nine carried a
[DEPRECATED] or [SUPERSEDED] marker in their description naming the replacement, through
several MINOR releases. This guide is that record — every replacement below is the one the
skill itself named.
What broke¶
Nine commands no longer exist. If you invoke one, nothing resolves — there is no alias.
Backward-compatible aliases were evaluated and withdrawn: Claude Code keys skill identity on
the SKILL.md name: field, not on the deployed directory name, so a second symlink to a
skill directory does not create a working alias. The only alternative was one real directory
per alias, which would have made every alias a fully visible, selectable skill for the whole
deprecation window — inflating exactly the surface this work exists to shrink.
Replacements¶
The knowledge-work phase commands were absorbed into the unified deliverable workflow. That
workflow dispatches on deliverable_types, so the same phases now serve code, documents,
presentations, research and project plans through one path.
| Removed | Use instead |
|---|---|
/vt-c-kw-0-start |
/vt-c-activate |
/vt-c-kw-1-plan |
/vt-c-2-plan |
/vt-c-kw-2-execute |
/vt-c-3-build |
/vt-c-kw-3-review |
/vt-c-4-review |
/vt-c-kw-4-publish |
/vt-c-5-finalize |
/vt-c-kw-specs |
/vt-c-specs-from-prd |
/vt-c-writing-plans |
/vt-c-2-plan (code-type TDD task template) |
/vt-c-ralph-wiggum-loop |
/vt-c-3-build Step 6.5a — the convergence logic moved there |
/vt-c-file-todos |
Beads (bd) — see beads-integration.md |
If you had deliverable_types set on a spec, no change is needed: the unified phases read it
and select the right task template automatically.
What did NOT change¶
Three kw-* skills were kept, despite an earlier plan to retire twelve:
/vt-c-kw-prd/vt-c-kw-prototype/vt-c-kw-user-test
They carry no deprecation marker and are not stubs — they are substantial skills that evolved
separately from their pd-* counterparts (the pd-* version is the same job plus
product-design-workflow wiring). Removing them would have deleted live capability with no
warning window. They continue to work exactly as before.
Note that /vt-c-kw-prd and /vt-c-pd-2-prd, and /vt-c-kw-prototype and
/vt-c-pd-3-prototype, currently carry identical descriptions, so which one gets selected for
a given request is not predictable. Prefer the pd-* form if you want the design-workflow
integration; prefer the kw-* form for the standalone flow.
Skill count¶
128 → 119. The manifest (skill-symlinks.manifest) remains the single source of truth;
every count surface is derived from it.
Also in 4.0 (additive)¶
Five plugin scaffolds are registered and installable, each empty for now and each declaring
depends_on: core-standards: vt-brand, vt-office, vt-toolkit, vt-pm-intake,
vt-product-dev. Installing one deploys no skills yet. They exist so the later split can move
skills into them one reviewable step at a time.
Selecting plugins with --plugins also works again on bash 3.2 (BUG-013); it was silently
dead, which blocked per-plugin installation entirely.
Upgrading¶
Run it from your primary checkout, not a worktree — setup.sh bakes an absolute path into
every deployed symlink, so deploying from a worktree dead-links your whole ~/.claude when
that worktree is removed. The installer now refuses this by default; --allow-worktree
overrides it for isolated-$HOME test runs.