SpecKit Safe Update - Claude Code Skill

1# SpecKit Safe Update
2 
3This skill provides safe update capabilities for GitHub SpecKit installations, preserving customizations while applying template updates.
4 
5**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.
6 
7## What to do when this skill is invoked
8 
9When the user invokes `/speckit-updater`, you should:
10 
111. **Run the update orchestrator script** without any flags (conversational mode):
12   ```powershell
13   pwsh -NoProfile -Command "& 'C:\Users\bobby\.claude\skills\speckit-updater\scripts\update-wrapper.ps1'"
14   ```
15 
162. **Parse the output** for markers:
17   - **`[PROMPT_FOR_APPROVAL]`** - Update scenario (existing SpecKit installation)
18   - **`[PROMPT_FOR_INSTALL]`** - Fresh installation scenario (no .specify/ directory)
19 
203. **For Updates** (`[PROMPT_FOR_APPROVAL]` marker found):
21   - **Present the Markdown summary** showing:
22     - Current version vs. available version
23     - Files to update/add/remove
24     - Conflicts detected (if any)
25     - Files preserved (customized)
26     - Backup location
27     - Custom commands
28   - **Ask the user for approval** to proceed with the update
29   - **If approved**, re-run with `-Proceed` flag
30   - **If declined**, inform the user the update was cancelled
31 
324. **For Fresh Installations** (`[PROMPT_FOR_INSTALL]` marker found):
33   - **Present a natural installation offer** to the user, such as:
34     - "SpecKit is not currently installed in this project. Would you like me to install it?"
35     - "I can install the latest SpecKit templates for you. This will create the .specify/ directory structure and download the templates from GitHub."
36   - **Do NOT mention the `-Proceed` flag** to the user (this is an implementation detail)
37   - **If user approves** (says "yes", "proceed", "install it", etc.), re-run with `-Proceed` flag
38   - **If user declines**, inform them the installation was cancelled
39 
405. **Execute approved action** by re-running with `-Proceed` flag:
41   ```powershell
42   pwsh -NoProfile -Command "& 'C:\Users\bobby\.claude\skills\speckit-updater\scripts\update-wrapper.ps1' -Proceed"
43   ```
44 
45**Special cases:**
46- If user requests `-CheckOnly`: run with that flag and show the report
47- If user requests `-Rollback`: run with that flag and confirm restoration
48- If user requests specific `-Version`: include that parameter
49 
50## Commands
51 
52### /speckit-updater
53 
54Updates SpecKit templates, commands, and scripts while preserving customizations.
55 
56**Usage:**
57- `/speckit-updater` - Interactive update/install with conversational approval workflow (recommended for Claude Code)
58- `/speckit-updater -Proceed` - Proceed with update/install after approval (used by Claude after user confirms)
59- `/speckit-updater -CheckOnly` - Check for updates without applying
60- `/speckit-updater -Version v0.0.72` - Update to specific version
61- `/speckit-updater -Force` - Force overwrite SpecKit files (preserves custom commands)
62- `/speckit-updater -Rollback` - Restore from previous backup
63- `/speckit-updater -Auto` - DEPRECATED: Use conversational workflow instead (shows warning, maps to -Proceed)
64 
65**Fresh Installation (No .specify/ directory):**
66- First invocation shows installation offer with `[PROMPT_FOR_INSTALL]` marker
67- Claude Code presents natural question to user (e.g., "Would you like me to install SpecKit?")
68- User approves via conversational response (e.g., "yes", "proceed", "install it")
69- Claude re-invokes with `-Proceed` flag automatically (implementation detail hidden from user)
70- Script creates `.specify/` structure, downloads templates, creates manifest
71- Exit code 0 throughout (awaiting approval is not an error)
72- Consistent with update flow: both use conversational approval workflow
73 
74**Process:**
751. Validates prerequisites (Git installed, clean Git state, write permissions)
762. Loads or creates manifest (.specify/manifest.json)
773. Fetches target version from GitHub Releases API
784. Compares file hashes to identify customizations
795. Creates timestamped backup
806. Applies selective updates preserving customized files
817. Opens VSCode merge editor for conflicts (Flow A: one at a time)
828. Automatically invokes /speckit.constitution for constitution updates
839. Updates manifest with new version
8410. Manages backup retention (keeps last 5)
85 
86**When you invoke this command, I will:**
871. Execute the update-orchestrator.ps1 script
882. Parse output for markers (`[PROMPT_FOR_APPROVAL]` for updates, `[PROMPT_FOR_INSTALL]` for fresh installations)
893. **For updates**: Present Markdown summary of proposed changes
904. **For installations**: Ask naturally if you want to install SpecKit (without mentioning `-Proceed` flag)
915. Wait for your approval via chat conversation
926. After approval: automatically re-invoke with `-Proceed` flag to execute
937. Guide you through conflict resolution one file at a time (updates only)
948. Open VSCode diff/merge tools as needed (updates only)
959. Report results with detailed summary
96 
97**Conversational Workflow:** The skill uses a two-step approval process:
98- **Step 1**: Outputs summary → script exits → waits for approval
99- **Step 2**: After approval, Claude re-invokes with `-Proceed` → applies updates
100 
101**Requirements:**
102- Git installed and in PATH
103- Internet connection for fetching updates from GitHub
104- Write permissions to .specify/ and .claude/ directories
105- Clean or staged Git working directory
106 
107**The script is located at:** `{skill_path}/scripts/update-wrapper.ps1` (entry point) and `{skill_path}/scripts/update-orchestrator.ps1` (main logic)
108 
109**Entry point command:**
110```powershell
111pwsh -NoProfile -Command "& '{skill_path}/scripts/update-wrapper.ps1' [parameters]"
112```
113 
114**Note:** Both PowerShell-style (`-CheckOnly`) and Linux-style (`--check-only`) flags are supported via the wrapper script.
115 
116## Features
117 
118- **Customization Preservation**: Automatically detects and preserves user customizations using normalized file hashing
119- **Intelligent Conflict Resolution**: Guides through conflicts one-at-a-time with 4 options: merge editor, keep mine, use new, skip
120- **Version Tracking**: Maintains `.specify/manifest.json` with file hashes, version info, and backup history
121- **Automatic Backups**: Creates timestamped backups in `.specify/backups/` with automatic retention management
122- **Fail-Fast with Rollback**: Automatically rolls back on any error, restoring pre-update state
123- **Dry-Run Mode**: `--check-only` shows exactly what would change without applying updates
124- **Constitution Integration**: Notifies when constitution template has updates (run `/speckit.constitution`)
125- **Custom Command Safety**: User-created commands never overwritten, even with `--force`
126 
127## Architecture
128 
129### Modules
130- **HashUtils**: Normalized hashing (handles line endings, trailing whitespace, BOM)
131- **VSCodeIntegration**: Context detection, Quick Pick, diff/merge editor integration
132- **GitHubApiClient**: GitHub Releases API interaction (unauthenticated, 60 req/hour)
133- **ManifestManager**: Manifest CRUD operations with caching
134- **BackupManager**: Backup creation, restoration, and retention management
135- **ConflictDetector**: File state analysis and conflict detection
136 
137### Workflow
1381. Prerequisites validation (critical checks must pass, warnings allow continuation)
1392. Manifest loading/creation (safe default: assume all files customized if no manifest)
1403. GitHub API query for target version
1414. File state analysis (6 actions: add/remove/merge/preserve/update/skip)
1425. User confirmation with change preview
1436. Backup creation (timestamped, excludes backups directory)
1447. Selective file updates (fail-fast with automatic rollback)
1458. Conflict resolution (Flow A: one-at-a-time, VSCode merge editor)
1469. Manifest update (version, file hashes, customization flags)
14710. Backup cleanup (keep 5 most recent, requires confirmation)
14811. Detailed summary display
149 
150## Exit Codes
151 
152| Code | Meaning |
153|------|---------|
154| 0 | Success |
155| 1 | General error |
156| 2 | Prerequisites not met |
157| 3 | Network/API error |
158| 4 | Git error |
159| 5 | User cancelled |
160| 6 | Rollback required (automatic) |
161