All pending migrations are applied to the user's local groove state in version order. .groove/index.md reflects the current installed groove version.
Acceptance Criteria
groove-version: in .groove/index.md matches version: in skills/groove/SKILL.md after update
Each pending migration was applied in order
groove-version: updated after each successful migration (partial progress is recoverable)
If already up to date, reports clearly and exits
Source-of-truth check : "up to date" is only reported when the installed skill version equals the latest GitHub release; if the add step left an older version on disk (e.g. cached or default branch), the user is warned and told how to fix it
Steps
Run npx skills add andreadellacorte/groove --yes — pulls latest groove skill files and refreshes the lock entry (more reliable than npx skills update which requires a pre-populated folder hash). Note: the CLI may install a cached or default-branch copy rather than the latest release tag; step 4 verifies against GitHub.
After this step, re-read this SKILL.md (skills/groove-admin-update/SKILL.md) from disk before continuing — the skill refresh may have updated the update command itself, and the remainder of these steps must reflect the latest version
Read groove-version: from .groove/index.md — if key absent, assume 0.1.0 and write it
Read installed version from version: in skills/groove/SKILL.md
Verify against latest release : Fetch https://api.github.com/repos/andreadellacorte/groove/releases/latest (tag_name, strip leading v). If the request succeeds, compare installed with latest using semver. If installed is less than latest: do not report "up to date" even if local and installed match; instead report: "Installed skill is v but latest release is v. The add step may have used a cached or default-branch copy. Run: npx skills add andreadellacorte/groove@v<latest> --yes then run /groove-admin-update again." and exit. If the API call fails (network, rate limit), continue without this check.
If local and installed versions match: report "groove is up to date (v)" and exit
Read skills/groove/migrations/index.md — parse the migration table
Filter rows where To > local version AND To <= installed version, in table order — the From field is informational only and does not gate execution
If no migrations found but versions differ: update groove-version: in .groove/index.md directly to the installed version and report "no state migrations needed — version bumped to v"
For each pending migration: a. Report "Applying → : " b. Read and execute the migration file c. Update groove-version: in .groove/index.md to the To version d. Report "✓ → applied"
Report summary: N migrations applied, now at v
Re-sync platform symlinks after update:
* For each directory in .agents/skills/ that starts with groove:
Ensure .claude/skills/<name> is a symlink → ../../.agents/skills/<name> (create or update if stale)
Ensure .cursor/skills/<name> is a symlink → ../../.agents/skills/<name> if .cursor/skills/ exists
* Remove any .claude/skills/groove-* or .cursor/skills/groove-* entries that no longer exist in .agents/skills/ (stale symlinks from removed skills)
* Run:
* Use (no-dereference) to avoid creating nested symlinks inside existing directory symlinks
* Report: "✓ platform symlinks refreshed"
Constraints
Source of truth for "latest" is GitHub releases — npx skills add can leave an older version on disk (cached clone, default branch). Comparing only .groove/index.md with installed SKILL.md can falsely report "up to date". Step 4 must verify installed vs releases/latest and warn when they differ.
Never skip a migration — apply every matching migration in table order even if From does not match local version exactly
Update groove-version: after each individual migration, not only at the end
If a migration fails: stop, report the failure and current version, do not continue
Do not modify skill files — npx skills update handles that; this command only migrates local state
Local state includes: .groove/index.md config keys, memory directory structure, AGENTS.md sections
