update-framework

When to Use

Prerequisites

• • Current project has CLAUDE.md installed
• • Git repository (for backup/diff capabilities)
• • Internet access to clone latest version
• • No uncommitted changes (clean working directory recommended)

Process Overview

1. Check Current Version
   └── Read CLAUDE.md version
        ↓
2. Fetch Latest Version
   └── Clone/download latest
        ↓
3. Compare Versions
   └── What's new? Breaking changes?
        ↓
4. Identify Customizations
   └── What have you modified?
        ↓
5. Plan Update Strategy
   └── Full replace vs. selective merge
        ↓
6. Execute Update
   └── Backup, copy, merge
        ↓
7. Verify Update
   └── Check files, validate

Phase 1: Assess Current Installation

Version Detection

# Find current version in CLAUDE.md
grep "Current Version" CLAUDE.md

# Check when CLAUDE.md was last modified
ls -la CLAUDE.md

# List installed skills (language guides and framework skills)
ls .claude/skills/

# List installed workflows
ls .claude/skills/

AI Will Check

1. •Current CLAUDE.md version (in "Version & Changelog" section)
2. •Which .claude/ files exist (guides, workflows)
3. •Which files appear customized (vs. template defaults)
4. •Project-specific files to preserve:
   • •CLAUDE.md
   • •CLAUDE.md
   • •CLAUDE.md
   • •.claude/memory/*
   • •.claude/tasks/*

Customization Detection

Files that are typically customized:

• •CLAUDE.md (custom guardrails, company standards)
• •CLAUDE.md (always project-specific)
• •CLAUDE.md (project conventions)
• •Any workflow with project-specific modifications

Files that are typically NOT customized:

• •Language guide skills (.claude/skills/*-guide/SKILL.md)
• •Framework skills (.claude/skills/<framework>/SKILL.md)
• •Standard workflows (unless modified for company process)

Phase 2: Fetch Latest Version

Method A: Clone Fresh (Recommended)

# Clone latest version to temporary directory
git clone --depth 1 https://github.com/ar4mirez/samuel.git .ai-update-temp

# Check latest version
grep "Current Version" .ai-update-temp/CLAUDE.md

Method B: If Using Git Subtree

# Update subtree
git subtree pull --prefix=.ai-template \
    https://github.com/ar4mirez/samuel.git main --squash

Method C: Download ZIP

1. •Go to GitHub Releases
2. •Download latest release
3. •Extract to temporary directory

Phase 3: Compare Versions

View Changelog

# View what's new
cat .ai-update-temp/CHANGELOG.md | head -100

# Compare versions
echo "Current: $(grep 'Current Version' CLAUDE.md)"
echo "Latest:  $(grep 'Current Version' .ai-update-temp/CLAUDE.md)"

AI Will Analyze

1. •New files - Guides, workflows not in current installation
2. •Modified files - Changes to existing templates
3. •Deleted files - Removed from template (rare)
4. •Breaking changes - Documented in CHANGELOG.md

Update Summary Format

## Update Summary: v1.5.0 → v1.6.0

### New Files (safe to add):
- .claude/skills/new-framework/SKILL.md
- .claude/skills/new-workflow.md

### Modified Files (review recommended):
- CLAUDE.md (guardrails updated)
- .claude/skills/code-review.md (new checks)

### Your Customizations (will preserve):
- CLAUDE.md (project-specific)
- CLAUDE.md (project-specific)
- .claude/memory/* (decision logs)
- .claude/tasks/* (PRDs and tasks)

### Breaking Changes:
- None (or list if any)

Phase 4: Plan Update Strategy

Strategy A: Full Replace (Recommended for minor updates)

Best when:

• •No customizations to CLAUDE.md
• •Just want latest guides and workflows
• •Version jump is small (e.g., 1.5.0 → 1.6.0)

Process:

1. •Backup project-specific files
2. •Replace all template files
3. •Restore project-specific files

Strategy B: Selective Merge

Best when:

• •Heavy customization to CLAUDE.md
• •Only want specific new features
• •Version jump is large

Process:

1. •Keep current files
2. •Add only new guides/workflows
3. •Manually review and merge changed files

Strategy C: New Files Only

Best when:

• •Significant CLAUDE.md customization
• •Only interested in new language/framework skills
• •Don't want to risk breaking customizations

Process:

1. •Keep all existing files
2. •Copy only skill directories that don't exist yet

AI Will Recommend

Based on:

• •Number and type of customizations
• •Size of version jump
• •Breaking changes in changelog
• •User's stated preferences

Phase 5: Execute Update

Full Replace Steps

# 1. Create backup directory
mkdir -p .ai-backup

# 2. Backup CLAUDE.md (if customized)
cp CLAUDE.md .ai-backup/

# 3. Backup project-specific files
cp CLAUDE.md .ai-backup/ 2>/dev/null || true
cp CLAUDE.md .ai-backup/ 2>/dev/null || true
cp CLAUDE.md .ai-backup/ 2>/dev/null || true
cp -r .claude/memory .ai-backup/ 2>/dev/null || true
cp -r .claude/tasks .ai-backup/ 2>/dev/null || true

# 4. Copy new template files
cp .ai-update-temp/CLAUDE.md ./
cp -r .ai-update-temp/.claude ./

# 5. Restore project-specific files
cp .ai-backup/project.md .claude/ 2>/dev/null || true
cp .ai-backup/patterns.md .claude/ 2>/dev/null || true
cp .ai-backup/state.md .claude/ 2>/dev/null || true
cp -r .ai-backup/memory/* .claude/memory/ 2>/dev/null || true
cp -r .ai-backup/tasks/* .claude/tasks/ 2>/dev/null || true

# 6. If you had CLAUDE.md customizations, merge them
# (AI will help with this step)

# 7. Clean up
rm -rf .ai-update-temp
rm -rf .ai-backup

Selective Add Steps

# Add only new language guide skills
cp -r .ai-update-temp/.claude/skills/new-language-guide/ .claude/skills/

# Add only new framework skills
cp -r .ai-update-temp/.claude/skills/new-framework/ .claude/skills/

# Add only new workflows
cp .ai-update-temp/.claude/skills/new-workflow.md .claude/skills/

Handling CLAUDE.md Customizations

If you've customized CLAUDE.md:

1. •

   Diff the files:

   bash

   diff CLAUDE.md .ai-update-temp/CLAUDE.md
   

2. •

   Identify your customizations (usually in specific sections)

3. •

   AI will help merge:

   • •Take new guardrails from template
   • •Preserve your custom additions
   • •Update version number

Phase 6: Verify Update

Verification Checklist

• • CLAUDE.md shows new version number
• • New language/framework skills present
• • New workflows present
• • Project-specific files preserved:
  • • CLAUDE.md
  • • CLAUDE.md
  • • CLAUDE.md
  • • .claude/memory/*
  • • .claude/tasks/*
• • No merge conflicts in customized sections
• • AI assistant loads CLAUDE.md correctly

Verification Commands

# Check version
grep "Current Version" CLAUDE.md

# List all skills (language guides and framework skills)
echo "=== Skills ==="
ls .claude/skills/

echo "=== Workflows ==="
ls .claude/skills/

# Verify project files exist
echo "=== Project Files ==="
ls -la CLAUDE.md CLAUDE.md CLAUDE.md 2>/dev/null

# Count memory files
echo "=== Memory Files ==="
ls .claude/memory/ 2>/dev/null | wc -l

Test AI Loading

Start a new AI session and verify:

1. •AI acknowledges CLAUDE.md version
2. •Guardrails are applied correctly
3. •Workflows are accessible

Usage Examples

Example 1: Standard Update

User Request:

@.claude/skills/update-framework/SKILL.md

Update to the latest version of Samuel

AI Will:

1. •Check current version
2. •Clone latest version
3. •Compare and show what's new
4. •Ask about customizations
5. •Execute update with backups
6. •Verify completion

Example 2: Check for Updates Only

User Request:

@.claude/skills/update-framework/SKILL.md

Check what's new in the latest version (don't update yet)

AI Will:

1. •Check current version
2. •Clone latest version
3. •Show detailed comparison
4. •List new features and changes
5. •NOT make any changes

Example 3: Selective Update

User Request:

@.claude/skills/update-framework/SKILL.md

I only want to add the new React and Next.js framework skills.
Keep everything else as-is.

AI Will:

1. •Verify those skills don't exist yet
2. •Clone latest version
3. •Copy only the specified skill directories
4. •Clean up temporary files

Example 4: Team Version Sync

User Request:

@.claude/skills/update-framework/SKILL.md

Verify my installation matches version 1.6.0 that the team is using.

AI Will:

1. •Check current version
2. •Compare with 1.6.0 requirements
3. •List any missing files
4. •Suggest updates if needed

Example 5: Update with Customizations

User Request:

@.claude/skills/update-framework/SKILL.md

Update to latest. I have custom guardrails in CLAUDE.md that I need to keep.

AI Will:

1. •Check current version
2. •Identify customized sections in CLAUDE.md
3. •Clone latest version
4. •Perform intelligent merge:
   • •New template content
   • •Your custom guardrails preserved
5. •Show diff for review before finalizing

Best Practices

Before Updating

1. •Commit current state - Ensure clean git history
2. •Document customizations - Know what you've changed
3. •Read the changelog - Understand what's new

During Update

1. •Always backup - Never skip the backup step
2. •Review diffs - Especially for CLAUDE.md changes
3. •Test incrementally - Verify after each major step

After Updating

1. •Verify functionality - Test AI loading and workflows
2. •Clean up backups - Remove .ai-backup when confirmed
3. •Update team - Inform team of version update
4. •Run cleanup workflow - Remove unused guides if needed

Related Workflows

Reference Documentation

For detailed migration steps, conflict resolution examples, and troubleshooting procedures, see:

• •references/process.md - Detailed update procedures and rollback steps