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
• Fetch latest release from GitHub (heyitsnoah/claudesidian)
• Create timestamped backup in .backup/upgrade-YYYY-MM-DD-HHMMSS/
• Fetch upstream changes: git fetch upstream --tags

2. Create Upgrade Checklist

• Get list of SYSTEM files that need checking (NOT user content):

  # Only check claudesidian system files, not user notes
  git diff HEAD upstream/main --name-only | grep -E '^(\.claude/|\.scripts/|package\.json|CHANGELOG\.md|README\.md|\.gitignore)'
  

• 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

For EACH file in the checklist:

1. Show the diff: git diff HEAD upstream/main -- [file]
2. Determine update strategy:
   • Direct replace: Commands, agents, scripts with no user changes
   • Skip: User's CLAUDE.md, vault-config.json, .mcp.json
   • Merge needed: Files with both upstream and user changes
3. Apply the update
4. Mark complete in checklist: [x]
5. 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

• Save progress after each file in .upgrade-checklist.md
• 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. Final Steps

• Update version in package.json
• Verify all commands work
• Clean up checklist file (or keep for reference)
• 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

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 ...]

🎉 Upgrade complete!
📈 claudesidian 0.8.2 → 0.8.3

✅ Updated: 14 files
⏭️ Skipped: 1 file (CLAUDE.md - user customization)

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

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