Imported from chrs-myrs/livespec (skills/upgrade/SKILL.md). Install upstream with npx skills add chrs-myrs/livespec --skill upgrade. Copyright stays with the author.

LiveSpec Upgrade

Migrate legacy LiveSpec installations to v5 plugin architecture.

IMPORTANT: Do NOT Install Plugin

If this skill is running, the plugin is already installed. Never attempt to:

• git clone LiveSpec
• Create .claude-plugin/ directories
• Run any plugin installation commands

The upgrade script only removes legacy artifacts and migrates specs.

Step 1: Detect Current State

Run the detection script from the project root (the script ships in the plugin):

bash ${CLAUDE_PLUGIN_ROOT}/scripts/upgrade-to-v5.sh --detect-only

Route on the reported status:

A current project still has upgrade work to do. Conventions may never have been vendored and the validation hook may never have been installed, because both postdate most existing v5 projects. Stopping at this step would make those steps unreachable for exactly the projects that need them.

If /livespec:upgrade check was invoked, report detection results and stop.

Step 2: Show Migration Plan

Run the dry-run to show what will change:

bash ${CLAUDE_PLUGIN_ROOT}/scripts/upgrade-to-v5.sh --dry-run

Present the plan to the user and ask for confirmation using AskUserQuestion:

• "Proceed with migration" (recommended)
• "Cancel"

If cancelled, stop.

Step 3: Execute Migration

Run the migration:

bash ${CLAUDE_PLUGIN_ROOT}/scripts/upgrade-to-v5.sh

Report the output to the user. If verification fails, show the failures and stop.

Step 3a: Vendor or Refresh Conventions

Reached for both a migrated project and one that was already current.

bash ${CLAUDE_PLUGIN_ROOT}/scripts/vendor-conventions.sh --check

Report the state of each convention: unchanged, upstream update available, locally edited, or diverged. Then apply the safe updates:

bash ${CLAUDE_PLUGIN_ROOT}/scripts/vendor-conventions.sh

Only absent and upstream-changed-but-unedited files are written. Locally edited and diverged files are reported and left alone; tell the user which need a deliberate decision rather than resolving them automatically.

Step 3b: Install Validation Hook

Legacy installs predate hook installation, so install it now:

bash ${CLAUDE_PLUGIN_ROOT}/scripts/setup-hooks.sh --check
bash ${CLAUDE_PLUGIN_ROOT}/scripts/setup-hooks.sh

Run --check first and report the state. An existing foreign hook is preserved as pre-commit.local and chained, never discarded.

Step 3c: Remediate What the Upgrade Surfaced

Installing validation into a project with historical drift will block its commits until that drift is fixed. The upgrade that installs the validation must also offer the repair, so run it here rather than leaving the user stuck.

bash ${CLAUDE_PLUGIN_ROOT}/scripts/remediate-references.sh --check

Present what it would rewrite: retired command names mapped to current ones, and convention references repointed at the copies just vendored in Step 3a. Then apply:

bash ${CLAUDE_PLUGIN_ROOT}/scripts/remediate-references.sh

Migration guides and historical documents are skipped: their "old reference" columns are correct as written.

Then run the validators and report what remains:

bash ${CLAUDE_PLUGIN_ROOT}/scripts/validate-constraints.sh
bash ${CLAUDE_PLUGIN_ROOT}/scripts/validate-crossrefs.sh

Anything still failing is project-specific and needs a decision: a retired name with no equivalent, a script the project never built, or a spec reference that has to be repointed by hand. List these for the user rather than guessing. Do not leave the step without saying plainly whether the project can now commit.

Step 4: Commit

Stage and commit all changes:

git add -A
git commit -m "$(cat <<'EOF'
Migrate to LiveSpec v5 plugin architecture

- Remove legacy installation artifacts
- Migrate specs/ to semantic folder structure
- Update cross-references

Co-Authored-By: Claude <noreply@anthropic.com>
EOF
)"

Report completion. Suggest next steps:

• /livespec:audit context - Regenerate AGENTS.md
• /livespec:audit health - Check spec health

Troubleshooting

For detailed migration guide, cross-reference mappings, and edge cases: references/guides/upgrade-to-v5.md