Migrating to 5.0.0 — the plugin split¶

Every skill and command has a new name. There are no aliases: the old names are gone, not deprecated. This guide tells you what yours became.

Why there is no alias period¶

The obvious kindness — ship both names for a release — is not available. Claude Code keys skill identity on the name: field inside SKILL.md, not on the symlink, so a second symlink pointing at the same skill is simply not a second skill. That was measured, not assumed (SPEC-163 W0).

The only mechanism that would work is a redirect directory per skill, which would have made every alias a visible, selectable entry in the skill list — 80 skills becoming roughly double that for the whole deprecation window. That was priced and rejected.

So the rename is a clean break, and this is a MAJOR release because of it.

The rule¶

A skill's prefix now tells you which plugin owns it:

prefix	plugin	what it is	skills
`vt-c-`	`vt-base`	required base — everyone gets it	15
`vt-d-`	`vt-product-dev`	PRD → prototype → spec → build → operate	65
`vt-o-`	`vt-office`	documents, diagrams, presentations	13
`vt-t-`	`vt-toolkit`	toolkit maintenance	12
`vt-p-`	`vt-pm-intake`	PM aggregation and intake	13
`vt-b-`	`vt-brand`	brand and corporate design	2
`vt-v-`	`vms`	compliance	11
`vt-f-`	`finance`	finance	1

vt-c- did not change meaning. If a skill stayed in the base, its name is untouched. Only skills that moved were renamed — so /vt-c-session-journal still works, and /vt-c-2-plan is now /vt-d-2-plan.

Finding your new name¶

The fastest check, once you have updated:

ls ~/.claude/skills | grep <the-part-after-the-prefix>

/vt-c-2-plan → ls ~/.claude/skills | grep 2-plan → vt-d-2-plan. The suffix never changed; only the prefix did.

The full mapping is in specs/163-core-standards-plugin-split/skill-assignment.tsv and command-assignment.tsv.

The one rename that is not just a prefix¶

core-standards is now vt-base — the directory, the plugin name, and every depends_on. If you have scripts pointing at plugins/core-standards/…, they need updating. Nothing else in the repo layout moved.

Upgrading an existing install — read this before you pull¶

Pulling 5.0.0 breaks your install until you re-run the installer. This is not a warning about risk; it is what happens, every time.

Your ~/.claude symlinks are absolute paths into plugins/core-standards/…. The moment you pull, that directory is gone and every one of them dangles. Measured on the maintainer's machine straight after the merge: 217 of 238 links dead — every toolkit skill, command and agent.

So the two steps are one operation, not two things you can space out:

git pull
scripts/setup.sh --update          # from your PRIMARY checkout, never a worktree

--update is the mode that leaves your personal files alone: it re-points every symlink and touches neither your ~/.claude/CLAUDE.md nor your settings.json (verified — the toolkit standards live in a separate @-imported file precisely so this is possible).

Three things it will do that are supposed to happen:

Delete ~12 agent symlinks. They point into the removed core-standards. Your own agents are safe: anything outside the eight toolkit prefixes (vt-b/c/d/f/o/p/t/v-) is never touched.
Change your command names. /vt-c-4-review becomes /vt-d-4-review, and so on. See the table above.
Report differently. setup.sh --verify now fails (exit 1) on a broken link or a missing hook where it used to shrug and exit 0. If --verify starts failing after the upgrade, it is telling you something true.

Then re-install the git hooks, in every repo (BUG-029)¶

--update refreshes ~/.claude/hooks/. It does not touch .git/hooks/ in any repo — that copy is installed per-project by install-hooks.sh, and no setup.sh mode reaches it.

A .git/hooks/pre-commit from before this release looks for the pre-rename scanner path and blocks every commit with an error naming plugins/core-standards/, a directory that no longer exists. Hit live on the maintainer's machine minutes after the deploy.

bash ~/.claude/hooks/install-hooks.sh    # run inside each repo using toolkit hooks

setup.sh --verify now detects this and prints the same command, so you do not have to remember which repos are affected — but it can only check the repo you run it in.

Installing only what you need¶

This is the point of the split. A PM no longer installs the developer flow:

scripts/setup.sh --plugins vt-pm-intake     # + vt-base, pulled in automatically
scripts/setup.sh --plugins vt-product-dev   # the full dev flow
scripts/setup.sh --plugins vt-office

vt-base is required and always installed. Selecting one persona excludes the others — verified against real installs, not inferred (tests/spec-163/test_persona_install.bats).

What was removed¶

Nine deprecated skills were retired in 4.0.0 and are already gone; see migration-4.0.md.

support and ufi were delisted from the plugin registry in this release. They had been advertised as installable since they were added while having no plugin.json, so neither could ever install. Nothing was deleted — their skill directories are still in the repo, and re-listing them means shipping a plugin.json.

Known issues in 5.0.0¶

Fixed since the release notes were first written — all three found by reviewing the release rather than by using it:

BUG-028 — setup.sh registered MCP servers into whatever $HOME it was pointed at, and registering an stdio server starts it. Every test that ran the installer against a throwaway home left a live server behind; one measured at 102.6% CPU. The installer now skips registration unless $HOME is the real one.
BUG-029 — the stale .git/hooks/pre-commit described above. --verify now detects it.
BUG-027 — the structural screen resolved 15 of 132 skills and reported the other 117 as load errors under an "always exit 0" contract. Now covers all eight plugins.

Two test suites remain red, both pre-dating this release and neither caused by the split:

BUG-007 — test-review-gates.sh asserts three outputs that were removed from the product. Deleting the assertions would silently drop a quality gate, so this needs a decision, not a patch.
BUG-008 — the domain dashboard's ID sort and month filter. Its fallback domain heuristic also still matches pre-renumber directory prefixes, so a project without an explicit domain: is classified "Other" for three of four products (recorded in BUG-024).

Both were verified pre-existing rather than assumed — test-review-gates.sh fails identically on the pre-5.0.0 main, and BUG-008's failures reproduce with the dashboard script restored from before this branch. They are recorded as accepted exceptions in .test-gate.md, not waved through.

Still open, and passing for the wrong reason: BUG-025. SPEC-157's T-15 check diffs against origin/main. This repo is not pushed, so origin/main is dozens of commits behind and the check examines far more than the branch actually changed. That suite is green today only because this release taught T-15 to ignore pure renames — which removed the symptom (a plugin relocation reading as a theme change) without touching the cause (the diff base). Do not read its green as evidence the base is correct.