Skills
skills/ar4mirez/samuel/update-framework

update-framework

SKILL.md

When to Use

Trigger Action
New version announced Full update
Want new language/framework skills Selective update
Monthly maintenance Check for updates
New team member needs latest Verify version parity
Security advisory Urgent update

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:

    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

Workflow Relationship
initialize-project For first-time installation
cleanup-project Remove unused guides after update
generate-agents-md Regenerate AGENTS.md after update
document-work Document the update decision

Reference Documentation

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

  • references/process.md - Detailed update procedures and rollback steps
Weekly Installs
5
Repository
ar4mirez/samuel
GitHub Stars
3
First Seen
13 days ago
Security Audits
Gen Agent Trust HubPass
SocketFail
SnykWarn
Installed on
opencode5
gemini-cli5
codebuddy5
github-copilot5
codex5
kimi-cli5