my-vault/.claude/commands/upgrade.md

name, description, allowed-tools, argument-hint

name	description	allowed-tools	argument-hint
upgrade	Intelligently upgrade claudesidian with new features while preserving user customizations using AI-powered semantic analysis	Read Write Edit MultiEdit Bash WebFetch Grep Glob	(optional) 'check' to preview changes, 'force' to skip confirmations

Smart Upgrade Command

Intelligently upgrades your claudesidian installation by fetching the latest release from GitHub and using AI-powered semantic analysis to merge new features with your existing customizations. Preserves user intent while adding new capabilities.

Task

1. Check GitHub for the latest claudesidian release
2. Download and analyze what has changed since your version
3. Use Claude's semantic understanding to identify user customizations
4. Intelligently merge new features with existing customizations
5. Safely apply updates while preserving user data and preferences
6. Create backups and provide rollback options

Process

1. Version Check & Setup

• Get current version from package.json
• Create timestamped backup in .backup/upgrade-YYYY-MM-DD-HHMMSS/
• Clone latest claudesidian to temp directory (doesn't affect user's repo):

  # Get fresh copy in .tmp dir (hidden from Obsidian) - user's repo stays disconnected
  git clone --depth=1 --branch=main https://github.com/heyitsnoah/claudesidian.git .tmp/claudesidian-upgrade
  

• Now we have latest version to compare against

2. Create Upgrade Checklist

• Compare system files between current directory and .tmp/claudesidian-upgrade/:

  # Find all system files that differ
  diff -qr . .tmp/claudesidian-upgrade/ --include="*.md" --include="*.sh" --include="*.json" |
  grep -E '(\.claude/|\.scripts/|package\.json|CHANGELOG\.md|README\.md)' |
  grep -v '(00_|01_|02_|03_|04_|05_|06_|\.obsidian|CLAUDE\.md)'
  

• Create checklist of files that need review

• Explicitly EXCLUDE:

  • User content folders (00_Inbox, 01_Projects, etc.)
  • User's CLAUDE.md (their personalized version)
  • vault-config.json (user's vault configuration)
  • .obsidian/ (user's Obsidian settings)
  • Any .md files in the root except README and CHANGELOG

• Create .upgrade-checklist.md with only system files that differ

• Mark each file with status: [ ] pending, [x] updated, [-] skipped

• Group files by type for easier review:

  ## Commands (12 files)
  
  [ ] .claude/commands/init-bootstrap.md [ ] .claude/commands/release.md [ ]
  .claude/commands/thinking-partner.md ...
  
  ## Settings (2 files)
  
  [ ] .claude/settings.json [ ] .claude/settings.local.json
  
  ## Core Files (3 files)
  
  [ ] package.json [ ] CHANGELOG.md [ ] README.md
  

3. File-by-File Review

⚠️ CRITICAL IMPLEMENTATION REQUIREMENT:

• NEVER blindly overwrite files without showing diffs first
• ALWAYS show diffs to the user first
• ALWAYS ask for confirmation before replacing files
• Skipping these steps can lose user customizations!
• NEVER use cp or cp -f (both can cause prompts on protected files)
• ALWAYS USE cat source > dest for guaranteed non-interactive replacement
• WAIT for actual user input - don't automatically choose option 1

For EACH file in the checklist:

1. Read current checklist status from .upgrade-checklist.md

2. MANDATORY: Show the diff between local and upstream:

   # ALWAYS show this to the user!
   diff -u current/file .tmp/claudesidian-upgrade/file
   

3. Determine update strategy:

   • No local changes: Direct replace from upstream

   • Never update: User's CLAUDE.md, vault-config.json, .mcp.json

   • Local changes detected: Ask user:

     File: .claude/commands/thinking-partner.md has local modifications
     
     Options:
     1. Keep your version (skip update)
     2. Take upstream version (lose your changes)
     3. View diff and decide
     4. Try to merge both (AI-assisted)
     
     Choice (1/2/3/4): [WAIT FOR USER TO TYPE NUMBER AND PRESS ENTER]
     

     IMPORTANT: Actually WAIT for the user to type their choice! Do NOT automatically select any option. The user must manually type 1, 2, 3, or 4 and press Enter.

4. Apply the chosen strategy:

   • For option 1 (Apply update/Take upstream):

     # IMPORTANT: Use cat with redirection to avoid ALL prompts
     # Do NOT use cp or cp -f as they may still prompt on some systems
     cat .tmp/claudesidian-upgrade/path/to/file > path/to/file && echo "✅ Updated"
     # Alternative if needed: rm -f path/to/file && cat .tmp/claudesidian-upgrade/path/to/file > path/to/file
     

   • For option 2 (Keep your version):

     echo "✅ Kept your version"
     

   • For option 4 (AI merge): Read both files and create merged version

5. CRITICAL: Update the checklist file immediately:

   [ ] .claude/commands/init-bootstrap.md → becomes → [x]
   .claude/commands/init-bootstrap.md
   

6. Save .upgrade-checklist.md after EVERY file update

7. Move to next file

4. Update Types

• Safe to replace: .claude/commands/*.md, .claude/agents/*.md, .scripts/*
• Needs review: package.json (preserve user's custom scripts)
• Never touch: User content folders, CLAUDE.md, API configs

5. Progress Tracking

• Use TodoWrite tool to track progress alongside the checklist
• Save progress after each file in .upgrade-checklist.md
• MUST mark items in checklist:
  • [x] = completed
  • [-] = skipped (user customization)
  • [ ] = still pending
• If interrupted, can resume from where you left off
• Show progress: "Updating file 5 of 23..."
• Clear indication of what's been done and what's remaining

6. Verification Check

• Re-check all system files against the checklist
• Compare with checklist to identify:
  • Files marked [ ] pending = likely missed (problem)
  • Files marked [-] skipped = intentionally kept different (fine)
  • Files marked [x] updated but still in diff = merge issues or user edits (review)
• Show verification results:

  ✅ All required files updated successfully
  ℹ️ 2 files intentionally kept with user customizations:
  - .claude/commands/thinking-partner.md (user's concise style)
  - package.json (user's custom scripts preserved)
  - or -
  ⚠️ Warning: 2 files appear to be missed (still marked pending):
  - .claude/commands/release.md
  - .scripts/vault-stats.sh
  

• Only flag as problem if files are still marked [ ] pending in checklist

7. Final Steps

• Update version in package.json
• Verify all commands work
• Clean up temp directory: rm -rf .tmp/claudesidian-upgrade
• Save final checklist for reference (shows what was updated vs skipped)
• Show summary of what was updated

Update Categories

🤖 AI-Powered Intelligent Merge

Commands (.claude/commands/*.md):

• Analyze user's prompt style, output preferences, workflow modifications
• Merge new features with existing customizations
• Preserve user's tone, structure, and specific requirements

Agents (.claude/agents/*.md):

• Understand user's interaction preferences
• Combine new capabilities with existing personality
• Maintain user's established workflows

Templates (06_Metadata/Templates/*.md):

• Preserve custom fields and structure
• Add new template features
• Maintain user's formatting preferences

⚡ Automatic Safe Updates

• New commands/agents: Purely additive, no conflicts
• Scripts (.scripts/*): Utility functions, safe to replace
• Dependencies (package.json): Security and feature updates
• Documentation: README, CONTRIBUTING updates

🛡️ Never Modified

• User content: All 00_* through 06_* folders (except templates)
• Personal config: User's CLAUDE.md
• API keys: .mcp.json, environment variables
• Git history: User's commits and branches

Smart Conflict Resolution

When Claude detects conflicts:

Example Scenarios:

Scenario 1: Command Enhancement

📝 thinking-partner command has updates:

YOUR VERSION: Custom concise output format, specific industry focus
NEW VERSION: Added video analysis capability, improved questioning flow

🤖 SMART MERGE PROPOSAL:
✅ Keep your concise output style
✅ Keep your industry-specific prompts
✅ Add new video analysis features
✅ Integrate improved questioning (adapted to your style)

Options:
1. 🎯 Apply smart merge (recommended)
2. 👀 Show detailed diff first
3. 🚫 Skip this update
4. 💾 Replace with new version (backup yours)

Scenario 2: Template Updates

📋 Project Template has changes:

YOUR VERSION: Added custom fields for client info, budget tracking
NEW VERSION: Enhanced metadata structure, new automation hooks

🤖 SMART MERGE PROPOSAL:
✅ Preserve your custom client/budget fields
✅ Add new metadata enhancements
✅ Integrate automation hooks
✅ Maintain your field ordering

Apply merge? (y/n/preview)

Command Usage

Preview Mode (Recommended First Run)

/upgrade check

• Shows what would be updated
• Displays intelligent merge previews
• No changes made to files
• Safe to run anytime

Interactive Upgrade

/upgrade

• Step-by-step confirmation for each change
• Shows before/after for modified files
• Allows selective application of updates
• Creates automatic backups

Batch Upgrade (Advanced)

/upgrade force

• Applies all safe updates automatically
• Still prompts for complex merges
• Faster for users comfortable with the process
• Full backup created before starting

Safety Features

Automatic Backups

• Complete backup before any changes: .backup/upgrade-[timestamp]/
• Individual file backups for each modification
• Backup includes current git state and uncommitted changes

Rollback Support

# If upgrade causes issues:
/rollback-upgrade [timestamp]
# Restores from specific backup

Verification Steps

• Post-upgrade functionality testing
• Command validation (runs test commands)
• MCP server connectivity check
• Git repository integrity verification

Incremental Application

• Updates applied one file at a time
• Validation after each critical change
• Stops on first error with clear diagnostics
• Easy to identify which change caused issues

Common Pitfalls to Avoid

⚠️ Selective Updates Problem

Never cherry-pick files based only on release notes! This leads to:

• Missing critical command updates
• Incomplete feature implementations
• Broken dependencies between files
• Users not getting all improvements

Always use git diff HEAD upstream/main --name-only to get the complete list of changed files, then update ALL relevant files systematically.

Error Handling

Common Scenarios

• No internet connection: Graceful failure with offline options
• GitHub API rate limits: Intelligent retry with backoff
• Merge conflicts: Clear explanation and manual resolution options
• Permission issues: Helpful guidance on fixing file permissions

Recovery Options

• Partial failure: Continue from last successful step
• Complete failure: Full rollback to pre-upgrade state
• Git conflicts: Merge upstream changes with local commits
• Dependency issues: Fallback to previous working versions

Advanced Features

Custom Merge Rules

Users can create .upgrade-rules.json to specify:

• Files to always skip
• Custom merge preferences
• Automatic approval for specific change types
• Backup retention policies

Integration with Git

• Commits each major change separately
• Meaningful commit messages describing updates
• Preserves user's branch structure
• Handles git conflicts intelligently

Selective Updates

/upgrade commands-only    # Update just commands
/upgrade agents-only      # Update just agents
/upgrade scripts-only     # Update just scripts
/upgrade deps-only        # Update just dependencies

CORRECT Implementation Example

THIS is how the upgrade should work:

📄 File 1/3: .claude/commands/release.md

# Step 1: ALWAYS show the diff first
Checking for differences...

--- .claude/commands/release.md
+++ .tmp/claudesidian-upgrade/.claude/commands/release.md
@@ -58,6 +58,11 @@

 ### Semantic Versioning (MAJOR.MINOR.PATCH)

+**Quick Decision Guide:**
+- Can users do something they couldn't do before? → **MINOR**
+- Did something that worked break? → **MAJOR** (if breaking) or **PATCH** (if fixing)
+- Did something that worked get better? → **PATCH**
+
 **MAJOR** (1.0.0 → 2.0.0):

# Step 2: Ask user what to do
This file has updates available. What would you like to do?

1. Apply update (take upstream version)
2. Keep your version (skip this update)
3. View full diff again
4. Try to merge changes (AI-assisted)

Your choice (1-4): 1

Applying update...
[x] Updated .claude/commands/release.md

WRONG Implementation (what happened in the test):

📄 File 1/3: .claude/commands/release.md

# NO DIFF SHOWN - WRONG!
# Just blindly overwrites:
Bash(cat .tmp/claudesidian-upgrade/.claude/commands/release.md > .claude/commands/release.md)

# No user confirmation - WRONG!
# Could lose customizations!

Example Session

> /upgrade

🔍 Checking for updates...
📦 Current version: 0.8.2
🆕 Latest version: 0.8.3

💾 Creating backup to .backup/upgrade-2025-09-13-142030/

📋 Creating upgrade checklist...
Checking system files only (not your personal notes)...
Found 15 system files with updates available

Created .upgrade-checklist.md to track updates:

## Commands (8 files)
[ ] .claude/commands/init-bootstrap.md
[ ] .claude/commands/release.md
[ ] .claude/commands/thinking-partner.md
[ ] .claude/commands/upgrade.md
[ ] .claude/commands/daily-review.md
[ ] .claude/commands/inbox-processor.md
[ ] .claude/commands/research-assistant.md
[ ] .claude/commands/weekly-synthesis.md

## Settings (1 file)
[ ] .claude/settings.json

## Core Files (3 files)
[ ] package.json
[ ] CHANGELOG.md
[ ] README.md

## Scripts (3 files)
[ ] .scripts/vault-stats.sh
[ ] .scripts/firecrawl-scrape.sh
[ ] .scripts/setup-mcp.sh

Starting file-by-file review...

📄 File 1/15: .claude/commands/init-bootstrap.md
   Status: No local changes detected
   Action: Direct update from upstream
   [x] Updated

📄 File 2/15: .claude/commands/release.md
   Status: No local changes detected
   Action: Direct update from upstream
   [x] Updated

📄 File 3/15: .claude/settings.json
   Status: Has local changes (your custom hooks)
   Showing diff...
   Action: Merge needed - preserving your hooks, adding new features
   [x] Merged

[... continues through all files ...]

🔍 **Verification Check**
Re-checking for any missed system files...

✅ All system files successfully updated!
No claudesidian system files remain out of sync with upstream.

🎉 Upgrade complete!
📈 claudesidian 0.8.2 → 0.8.3

✅ Updated: 14 files
⏭️ Skipped: 1 file (CLAUDE.md - user customization)
✅ Verified: All system files match upstream

Summary of changes:
- Fixed init-bootstrap vault selection
- Improved SessionStart hooks
- Enhanced user identification prompts
- Updated all commands to latest versions

Example: Verification Catches Missed Files

🔍 **Verification Check**
Re-checking for any missed system files...

⚠️ Warning: 2 files appear to be missed (still marked pending in checklist):
- .claude/commands/thinking-partner.md [ ]
- .scripts/vault-stats.sh [ ]

These files haven't been processed yet.

Would you like to complete the upgrade for these files? (y/n) > y

📄 Completing upgrade for missed files...

📄 File: .claude/commands/thinking-partner.md
   Status: Reviewing diff...
   Action: Direct update from upstream
   [x] Updated

📄 File: .scripts/vault-stats.sh
   Status: Reviewing diff...
   Action: Direct update from upstream
   [x] Updated

✅ Verification complete - all system files now match upstream!

Example: Verification with User Customizations

🔍 **Verification Check**
Re-checking for any missed system files...

Files still differing from upstream:
- .claude/commands/thinking-partner.md [x] ← Updated but user customized
- package.json [x] ← Merged, kept user's custom scripts
- .claude/commands/daily-review.md [ ] ← Not processed yet!

✅ 2 files intentionally preserve user customizations
⚠️ 1 file appears to be missed (still pending)

Would you like to:
1. Review the missed file (.claude/commands/daily-review.md)
2. Skip verification (keep current state)
3. See details about customized files

Choice (1/2/3) > 1

📄 File: .claude/commands/daily-review.md
   Status: Reviewing diff...
   Action: Direct update from upstream
   [x] Updated

✅ Verification complete!
- All required updates applied
- User customizations preserved where intended

This intelligent upgrade system leverages Claude's semantic understanding to provide the smoothest possible upgrade experience while ensuring no user customizations are lost.