SpecKit Safe Update - Claude Code Skill

Safe updates for GitHub SpecKit installations, preserving your customizations.

Overview

This Claude Code skill provides a safe, automated way to update SpecKit templates, commands, and scripts while preserving user customizations, eliminating the need for destructive specify init --force updates.

Features

• Smart Merge with Frictionless Onboarding (New in v0.6.0): Automatic version detection and intelligent 3-way merge
  • Zero conflicts for first-time users with unmodified SpecKit installations (was ~15)
  • Fingerprint-based version detection: Fast signature check (<100ms) identifies installed SpecKit version automatically
  • Intelligent 3-way merge: Section-level semantic understanding reduces conflicts from ~15 to 0-2
  • No user configuration: Fully automatic operation, works out of the box
• Automatic SpecKit Installation (v0.4.0): Offers to install SpecKit in non-SpecKit projects with one command
• Customization Preservation: Automatically detects and preserves your customized files
• Smart Conflict Resolution: Intelligent two-tier conflict handling
  • Small files (≤100 lines): Git conflict markers with VSCode CodeLens integration
  • Large files (>100 lines): Side-by-side Markdown diff files for easier review
• False Positive Detection: Auto-resolves conflicts where files are identical to upstream
• Conversational Approval: Two-step workflow designed for Claude Code
• Version Tracking: Maintains manifest with file hashes and version information
• Automatic Backups: Creates timestamped backups with retention management
• Fail-Fast with Rollback: Automatic rollback on failure, preserves diff files for debugging
• Dry-Run Mode: Check what would change before applying updates
• Constitution Integration: Seamless integration with /speckit.constitution command
• Welcome Experience: First-time installs show helpful next steps

Prerequisites

Supported Environment:

• OS: Windows 11 (macOS/Linux support welcome - see #15)
• Shell: PowerShell 7+
• AI: Claude Code (CLI or VSCode extension)
• Git: In PATH
• Internet: For GitHub API access

Note: This skill is designed specifically for Windows + PowerShell + Claude Code. Community contributions for other platforms/models are welcome but not maintained by the project owner.

Configuration

GitHub Token (Optional):

The updater works without authentication (60 requests/hour). For higher rate limits (5,000 requests/hour), set the GITHUB_PAT environment variable:

$env:GITHUB_PAT = "ghp_YOUR_TOKEN_HERE"

See CLAUDE.md for complete token setup, team collaboration, CI/CD integration, and troubleshooting.

Installation

Plugin Installation (Recommended)

Install via the NotMyself plugin marketplace:

# Add the marketplace
/plugin marketplace add NotMyself/claude-plugins
 
# Install the skill
/plugin install speckit-updater

The skill will be automatically available - no restart required!

Manual Installation (Alternative)

For advanced users or development:

# Navigate to Claude Code skills directory
cd $env:USERPROFILE\.claude\skills
 
# Clone this repository
git clone https://github.com/NotMyself/claude-win11-speckit-update-skill speckit-updater
 
# Restart VSCode to load the skill

Verify installation: The /speckit-update command should be available in Claude Code.

Migration: Already using manual installation? See Migration Guide for upgrading to plugin-based installation (optional).

Usage

First-Time Installation (New in v0.4.0!)

If you run /speckit-updater in a project without SpecKit installed, the updater will automatically offer to install it for you:

/speckit-updater

Interactive Mode (Terminal):

SpecKit is not installed in this project.

This skill can install the latest SpecKit templates and create a manifest to track future updates.

Would you like to install SpecKit now? (Y/n) Y

Non-Interactive Mode (Claude Code): Claude will ask naturally: "SpecKit is not currently installed in this project. Would you like me to install it?"

Simply reply "yes" or "install it" and Claude will handle the rest automatically.

What Gets Installed:

• .specify/ directory structure (memory/, backups/)
• Latest SpecKit templates from GitHub
• All official SpecKit slash commands in .claude/commands/
• Manifest file to track future updates
• Welcome message with next steps

Graceful Decline: If you decline installation, you'll see a helpful error message explaining what SpecKit is and how to install it manually.

Check for Updates (Dry-Run)

/speckit-updater --check-only

Shows what would change without applying any updates.

Update to Latest Version

/speckit-updater

Two-step conversational workflow:

1. Shows summary with [PROMPT_FOR_APPROVAL] marker
2. You approve via chat → Claude re-invokes with -Proceed

Update to Specific Version

/speckit-updater --version v0.0.72

Update to a specific SpecKit release tag.

Rollback to Previous Version

/speckit-updater --rollback

Restore from a previous backup.

Force Update

/speckit-updater --force

Overwrite SpecKit files even if customized (preserves custom commands).

Skip Backup (Not Recommended)

/speckit-updater --no-backup

Skip backup creation. Use only if you're absolutely sure.

How It Works

Customization Detection

The updater automatically detects which files you've customized by comparing file hashes:

• Customized files are preserved and never overwritten
• Unchanged files are safely updated to the latest version
• Your custom commands are always protected, even with --force

Smart Update Process

When you run /speckit-updater:

1. Safety First: Creates a timestamped backup before making any changes
2. Intelligent Analysis: Compares your files with the latest SpecKit templates
3. Conflict Detection: Identifies files that need your attention
4. Conversational Approval: Shows you exactly what will change and waits for your approval
5. Safe Application: Updates only what's safe, preserving your customizations
6. Automatic Rollback: If anything goes wrong, automatically restores from backup

Backup & Recovery

• Automatic backups created before every update in .specify/backups/
• Timestamped folders make it easy to find the right backup
• Quick rollback with /speckit-updater --rollback
• Automatic cleanup keeps your 5 most recent backups

Error Handling

Exit Codes

Automatic Rollback

If an error occurs during update:

1. Error message is displayed
2. Automatic rollback is attempted (if backup exists)
3. Files are restored to pre-update state
4. Exit code 6 is returned

License

MIT License - see LICENSE