groove-admin-update

Outcome

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

1. Fetch latest release tag from https://api.github.com/repos/andreadellacorte/groove/releases/latest (tag_name, strip leading v). This is the target version. If the API call fails, skip the version check and continue without a target.
2. Install with retry: Run npx skills add andreadellacorte/groove --yes (no @tag — the CLI does not support tag syntax). After it completes, read version: from skills/groove/SKILL.md and compare to the target. If the installed version is still older than the target, wait 10 seconds and retry npx skills add andreadellacorte/groove --yes. Repeat up to 3 times total. If all attempts fail to install the target version, report: "Installed v<installed> but latest release is v<target> — npx skills add may be caching an older version. Try again later." and exit.
   • After a successful install, 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
3. Read groove-version: from .groove/index.md — if key absent, assume 0.1.0 and write it
4. Read installed version from version: in skills/groove/SKILL.md (already confirmed to match target in step 2)
5. If local and installed versions match: report "groove is up to date (v<version>)" and exit
6. Read skills/groove/migrations/index.md — parse the migration table
7. Filter rows where To > local version AND To <= installed version, in table order — the From field is informational only and does not gate execution
8. 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<version>"
9. For each pending migration: a. Report "Applying <from> → <to>: <description>" b. Read and execute the migration file c. Update groove-version: in .groove/index.md to the To version d. Report "✓ <from> → <to> applied"
10. Report summary: N migrations applied, now at v<version>
11. 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: for skill in .agents/skills/groove*; do name=$(basename "$skill"); ln -sfn "../../.agents/skills/$name" ".claude/skills/$name"; done
    • Use ln -sfn (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 cache older versions. Step 1-2 fetches the latest release tag and retries installation up to 3 times to ensure the correct version is installed.
• 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
• Each migration file is idempotent — if re-run after partial failure, it should be safe