framework-upgrade

framework-upgrade

Upgrades the Exosuit framework to a newer version while preserving all project-specific customizations (skills, rules, hooks, settings).

Phase 0: Validate & Discover

1. Fetch new framework version:

   • Default (no argument or --branch <branch>): Clone the framework repo from GitHub into a temp directory. Use main branch unless --branch specifies otherwise.

     FRAMEWORK_REPO="https://github.com/joris887/exosuit.git"
     TEMP_DIR=$(mktemp -d)
     git clone --depth 1 [--branch <branch>] "$FRAMEWORK_REPO" "$TEMP_DIR"
     

   • Local path override: If $ARGUMENTS is a directory path, use it directly (for testing local changes before pushing).
   • Validate: The source (cloned or local) must contain .claude/skills/, .claude/hooks/, CLAUDE.md.

2. Current version — Read SKILLS_INVENTORY.md, extract Framework Version: line. Record as CURRENT_VERSION.

3. New version — Read <source>/CHANGELOG.md or <source>/.claude/skills/SKILLS_INVENTORY.md for version. Record as NEW_VERSION.

4. Git safety — Verify working tree is clean (git status --porcelain). If dirty, HALT: "Commit or stash changes before upgrading."

5. Report: "Upgrading framework: v{CURRENT} → v{NEW}. Source: {GitHub main | GitHub branch | local path}. Branch: {branch}."

6. Parse Version Log:

   Read CHANGELOG.md from the new framework version. Find all version entries between CURRENT_VERSION and NEW_VERSION.

   For each version entry, collect:

   • CORE_REPLACE files — will be replaced automatically
   • CORE_MERGE files — will be merged (preserve project-specific sections)
   • PROJECT_UPDATE_INSTRUCTIONS — manual steps for project-specific files

   Also read core/MANIFEST.md from the new framework version for file classification reference.

   Present a targeted upgrade plan based on the changelog:

   ## Targeted Upgrade: v{CURRENT} → v{NEW}
   
   ### Automatic (CORE files to replace/add)
   - [file]: [new/changed] (from version X.Y.Z)
   
   ### Merge Required (CORE files with project sections)
   - [file]: [what to merge] (from version X.Y.Z)
   
   ### Manual Steps (project-specific updates)
   - [instruction from PROJECT_UPDATE_INSTRUCTIONS] (from version X.Y.Z)