/speckit-updater

SpecKit Safe Update

This skill provides safe update capabilities for GitHub SpecKit installations, preserving customizations while applying template updates.

**Installation**: Available via plugin (`/plugin marketplace add NotMyself/claude-plugins` then `/plugin install speckit-updater`) or manual Git clone. See [README.md](../../README.md#installation) for details.

What to do when this skill is invoked

When the user invokes `/speckit-updater`, you should:

1. **Run the update orchestrator script** without any flags (conversational mode):

   pwsh -NoProfile -Command "& 'C:\Users\bobby\.claude\skills\speckit-updater\scripts\update-wrapper.ps1'"

2. **Parse the output** for markers:

• **`[PROMPT_FOR_APPROVAL]`** - Update scenario (existing SpecKit installation)
• **`[PROMPT_FOR_INSTALL]`** - Fresh installation scenario (no .specify/ directory)

3. **For Updates** (`[PROMPT_FOR_APPROVAL]` marker found):

• **Present the Markdown summary** showing:
• Current version vs. available version
• Files to update/add/remove
• Conflicts detected (if any)
• Files preserved (customized)
• Backup location
• Custom commands
• **Ask the user for approval** to proceed with the update
• **If approved**, re-run with `-Proceed` flag
• **If declined**, inform the user the update was cancelled

4. **For Fresh Installations** (`[PROMPT_FOR_INSTALL]` marker found):

• **Present a natural installation offer** to the user, such as:
• "SpecKit is not currently installed in this project. Would you like me to install it?"
• "I can install the latest SpecKit templates for you. This will create the .specify/ directory structure and download the templates from GitHub."
• **Do NOT mention the `-Proceed` flag** to the user (this is an implementation detail)
• **If user approves** (says "yes", "proceed", "install it", etc.), re-run with `-Proceed` flag
• **If user declines**, inform them the installation was cancelled

5. **Execute approved action** by re-running with `-Proceed` flag:

   pwsh -NoProfile -Command "& 'C:\Users\bobby\.claude\skills\speckit-updater\scripts\update-wrapper.ps1' -Proceed"

**Special cases:**

• If user requests `-CheckOnly`: run with that flag and show the report
• If user requests `-Rollback`: run with that flag and confirm restoration
• If user requests specific `-Version`: include that parameter

Commands

/speckit-updater

Updates SpecKit templates, commands, and scripts while preserving customizations.

**Usage:**

• `/speckit-updater` - Interactive update/install with conversational approval workflow (recommended for Claude Code)
• `/speckit-updater -Proceed` - Proceed with update/install after approval (used by Claude after user confirms)
• `/speckit-updater -CheckOnly` - Check for updates without applying
• `/speckit-updater -Version v0.0.72` - Update to specific version
• `/speckit-updater -Force` - Force overwrite SpecKit files (preserves custom commands)
• `/speckit-updater -Rollback` - Restore from previous backup
• `/speckit-updater -Auto` - DEPRECATED: Use conversational workflow instead (shows warning, maps to -Proceed)

**Fresh Installation (No .specify/ directory):**

• First invocation shows installation offer with `[PROMPT_FOR_INSTALL]` marker
• Claude Code presents natural question to user (e.g., "Would you like me to install SpecKit?")
• User approves via conversational response (e.g., "yes", "proceed", "install it")
• Claude re-invokes with `-Proceed` flag automatically (implementation detail hidden from user)
• Script creates `.specify/` structure, downloads templates, creates manifest
• Exit code 0 throughout (awaiting approval is not an error)
• Consistent with update flow: both use conversational approval workflow

**Process:** 1. Validates prerequisites (Git installed, clean Git state, write permissions) 2. Loads or creates manifest (.specify/manifest.json) 3. Fetches target version from GitHub Releases API 4. Compares file hashes to identify customizations 5. Creates timestamped backup 6. Applies selective updates preserving customized files 7. Opens VSCode merge editor for conflicts (Flow A: one at a time) 8. Automatically invokes /speckit.constitution for constitution updates 9. Updates manifest with new version 10. Manages backup retention (keeps last 5)

**When you invoke this command, I will:** 1. Execute the update-orchestrator.ps1 script 2. Parse output for markers (`[PROMPT_FOR_APPROVAL]` for updates, `[PROMPT_FOR_INSTALL]` for fresh installations) 3. **For updates**: Present Markdown summary of proposed changes 4. **For installations**: Ask naturally if you want to install SpecKit (without mentioning `-Proceed` flag) 5. Wait for your approval via chat conversation 6. After approval: automatically re-invoke with `-Proceed` flag to execute 7. Guide you through conflict resolution one file at a time (updates only) 8. Open VSCode diff/merge tools as needed (updates only) 9. Report results with detailed summary

**Conversational Workflow:** The skill uses a two-step approval process:

• **Step 1**: Outputs summary → script exits → waits for approval
• **Step 2**: After approval, Claude re-invokes with `-Proceed` → applies updates

**Requirements:**

• Git installed and in PATH
• Internet connection for fetching updates from GitHub
• Write permissions to .specify/ and .claude/ directories
• Clean or staged Git working directory

**The script is located at:** `{skill_path}/scripts/update-wrapper.ps1` (entry point) and `{skill_path}/scripts/update-orchestrator.ps1` (main logic)

**Entry point command:**

pwsh -NoProfile -Command "& '{skill_path}/scripts/update-wrapper.ps1' [parameters]"

**Note:** Both PowerShell-style (`-CheckOnly`) and Linux-style (`--check-only`) flags are supported via the wrapper script.

Features

• **Customization Preservation**: Automatically detects and preserves user customizations using normalized