Supporting material availability
This catalog copy contains the inline guidance below, but does not include the following supporting paths. They are external prerequisites, not bundled files:
Ask for the original supporting material or an existing installation before using a step that depends on these paths; this catalog does not identify a verified download source for them. Resolve each path relative to that installation, inspect its contents, and verify any applicable license and execution prerequisites. Do not run a command or claim a referenced procedure was followed until its required file exists. Do not fabricate the missing scripts or treat an unrelated file with the same name as equivalent. Independent steps fully documented here can proceed within the user’s authorized scope; report any dependent step as unavailable.
SpecKit Safe Update
This skill provides safe update capabilities for GitHub SpecKit installations, preserving customizations while applying template updates.
Installation: Before adding any marketplace or manual clone, inspect the
exact plugin revision and every bundled file, report scripts and network or
filesystem behavior, and ask for explicit user approval. Do not install a moving
branch directly into an active agent directory.
When to Use
- You need to update or install SpecKit templates while preserving project customizations.
- You want a safe approval flow around update, rollback, or version-specific SpecKit operations.
- The task is to operate the SpecKit updater conversationally instead of running raw commands blindly.
What to do when this skill is invoked
When the user invokes /speckit-updater, you should:
Run the update orchestrator script without any flags (conversational mode):
pwsh -NoProfile -File "<skill_path>/scripts/update-wrapper.ps1"
Parse the output for markers:
[PROMPT_FOR_APPROVAL] - Update scenario (existing SpecKit installation)
[PROMPT_FOR_INSTALL] - Fresh installation scenario (no .specify/ directory)
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
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
Execute approved action by re-running with -Proceed flag:
pwsh -NoProfile -File "<skill_path>/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:
- Validates prerequisites (Git installed, clean Git state, write permissions)
- Loads or creates manifest (.specify/manifest.json)
- Fetches target version from GitHub Releases API
- Compares file hashes to identify customizations
- Creates timestamped backup
- Applies selective updates preserving customized files
- Opens VSCode merge editor for conflicts (Flow A: one at a time)
- Automatically invokes /speckit.constitution for constitution updates
- Updates manifest with new version
- Manages backup retention (keeps last 5)
When you invoke this command, I will:
- Execute the update-orchestrator.ps1 script
- Parse output for markers (
[PROMPT_FOR_APPROVAL] for updates, [PROMPT_FOR_INSTALL] for fresh installations)
- For updates: Present Markdown summary of proposed changes
- For installations: Ask naturally if you want to install SpecKit (without mentioning
-Proceed flag)
- Wait for your approval via chat conversation
- After approval: automatically re-invoke with
-Proceed flag to execute
- Guide you through conflict resolution one file at a time (updates only)
- Open VSCode diff/merge tools as needed (updates only)
- 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 file hashing
- Intelligent Conflict Resolution: Guides through conflicts one-at-a-time with 4 options: merge editor, keep mine, use new, skip
- Version Tracking: Maintains
.specify/manifest.json with file hashes, version info, and backup history
- Automatic Backups: Creates timestamped backups in
.specify/backups/ with automatic retention management
- Fail-Fast with Rollback: Automatically rolls back on any error, restoring pre-update state
- Dry-Run Mode:
--check-only shows exactly what would change without applying updates
- Constitution Integration: Notifies when constitution template has updates (run
/speckit.constitution)
- Custom Command Safety: User-created commands never overwritten, even with
--force
Architecture
Modules
- HashUtils: Normalized hashing (handles line endings, trailing whitespace, BOM)
- VSCodeIntegration: Context detection, Quick Pick, diff/merge editor integration
- GitHubApiClient: GitHub Releases API interaction (unauthenticated, 60 req/hour)
- ManifestManager: Manifest CRUD operations with caching
- BackupManager: Backup creation, restoration, and retention management
- ConflictDetector: File state analysis and conflict detection
Workflow
- Prerequisites validation (critical checks must pass, warnings allow continuation)
- Manifest loading/creation (safe default: assume all files customized if no manifest)
- GitHub API query for target version
- File state analysis (6 actions: add/remove/merge/preserve/update/skip)
- User confirmation with change preview
- Backup creation (timestamped, excludes backups directory)
- Selective file updates (fail-fast with automatic rollback)
- Conflict resolution (Flow A: one-at-a-time, VSCode merge editor)
- Manifest update (version, file hashes, customization flags)
- Backup cleanup (keep 5 most recent, requires confirmation)
- Detailed summary display
Exit Codes
| Code |
Meaning |
| 0 |
Success |
| 1 |
General error |
| 2 |
Prerequisites not met |
| 3 |
Network/API error |
| 4 |
Git error |
| 5 |
User cancelled |
| 6 |
Rollback required (automatic) |
Limitations
- Use this skill only when the task clearly matches the scope described above.
- Do not treat the output as a substitute for environment-specific validation, testing, or expert review.
- Stop and ask for clarification if required inputs, permissions, safety boundaries, or success criteria are missing.
1---2name: speckit-updater3description: SpecKit Safe Update4risk: critical5source: community6date_added: "2026-03-06"7metadata:8 source: https://skillmd.com/skills/iradoweck/speckit-updater9---1011## Supporting material availability1213This catalog copy contains the inline guidance below, but does not include the following supporting paths. They are external prerequisites, not bundled files:141516Ask for the original supporting material or an existing installation before using a step that depends on these paths; this catalog does not identify a verified download source for them. Resolve each path relative to that installation, inspect its contents, and verify any applicable license and execution prerequisites. Do not run a command or claim a referenced procedure was followed until its required file exists. Do not fabricate the missing scripts or treat an unrelated file with the same name as equivalent. Independent steps fully documented here can proceed within the user’s authorized scope; report any dependent step as unavailable.171819# SpecKit Safe Update2021This skill provides safe update capabilities for GitHub SpecKit installations, preserving customizations while applying template updates.2223**Installation**: Before adding any marketplace or manual clone, inspect the24exact plugin revision and every bundled file, report scripts and network or25filesystem behavior, and ask for explicit user approval. Do not install a moving26branch directly into an active agent directory.2728## When to Use29- You need to update or install SpecKit templates while preserving project customizations.30- You want a safe approval flow around update, rollback, or version-specific SpecKit operations.31- The task is to operate the SpecKit updater conversationally instead of running raw commands blindly.3233## What to do when this skill is invoked3435When the user invokes `/speckit-updater`, you should:36371. **Run the update orchestrator script** without any flags (conversational mode):38 ```powershell39 pwsh -NoProfile -File "<skill_path>/scripts/update-wrapper.ps1"40 ```41422. **Parse the output** for markers:43 - **`[PROMPT_FOR_APPROVAL]`** - Update scenario (existing SpecKit installation)44 - **`[PROMPT_FOR_INSTALL]`** - Fresh installation scenario (no .specify/ directory)45463. **For Updates** (`[PROMPT_FOR_APPROVAL]` marker found):47 - **Present the Markdown summary** showing:48 - Current version vs. available version49 - Files to update/add/remove50 - Conflicts detected (if any)51 - Files preserved (customized)52 - Backup location53 - Custom commands54 - **Ask the user for approval** to proceed with the update55 - **If approved**, re-run with `-Proceed` flag56 - **If declined**, inform the user the update was cancelled57584. **For Fresh Installations** (`[PROMPT_FOR_INSTALL]` marker found):59 - **Present a natural installation offer** to the user, such as:60 - "SpecKit is not currently installed in this project. Would you like me to install it?"61 - "I can install the latest SpecKit templates for you. This will create the .specify/ directory structure and download the templates from GitHub."62 - **Do NOT mention the `-Proceed` flag** to the user (this is an implementation detail)63 - **If user approves** (says "yes", "proceed", "install it", etc.), re-run with `-Proceed` flag64 - **If user declines**, inform them the installation was cancelled65665. **Execute approved action** by re-running with `-Proceed` flag:67 ```powershell68 pwsh -NoProfile -File "<skill_path>/scripts/update-wrapper.ps1" -Proceed69 ```7071**Special cases:**72- If user requests `-CheckOnly`: run with that flag and show the report73- If user requests `-Rollback`: run with that flag and confirm restoration74- If user requests specific `-Version`: include that parameter7576## Commands7778### /speckit-updater7980Updates SpecKit templates, commands, and scripts while preserving customizations.8182**Usage:**83- `/speckit-updater` - Interactive update/install with conversational approval workflow (recommended for Claude Code)84- `/speckit-updater -Proceed` - Proceed with update/install after approval (used by Claude after user confirms)85- `/speckit-updater -CheckOnly` - Check for updates without applying86- `/speckit-updater -Version v0.0.72` - Update to specific version87- `/speckit-updater -Force` - Force overwrite SpecKit files (preserves custom commands)88- `/speckit-updater -Rollback` - Restore from previous backup89- `/speckit-updater -Auto` - DEPRECATED: Use conversational workflow instead (shows warning, maps to -Proceed)9091**Fresh Installation (No .specify/ directory):**92- First invocation shows installation offer with `[PROMPT_FOR_INSTALL]` marker93- Claude Code presents natural question to user (e.g., "Would you like me to install SpecKit?")94- User approves via conversational response (e.g., "yes", "proceed", "install it")95- Claude re-invokes with `-Proceed` flag automatically (implementation detail hidden from user)96- Script creates `.specify/` structure, downloads templates, creates manifest97- Exit code 0 throughout (awaiting approval is not an error)98- Consistent with update flow: both use conversational approval workflow99100**Process:**1011. Validates prerequisites (Git installed, clean Git state, write permissions)1022. Loads or creates manifest (.specify/manifest.json)1033. Fetches target version from GitHub Releases API1044. Compares file hashes to identify customizations1055. Creates timestamped backup1066. Applies selective updates preserving customized files1077. Opens VSCode merge editor for conflicts (Flow A: one at a time)1088. Automatically invokes /speckit.constitution for constitution updates1099. Updates manifest with new version11010. Manages backup retention (keeps last 5)111112**When you invoke this command, I will:**1131. Execute the update-orchestrator.ps1 script1142. Parse output for markers (`[PROMPT_FOR_APPROVAL]` for updates, `[PROMPT_FOR_INSTALL]` for fresh installations)1153. **For updates**: Present Markdown summary of proposed changes1164. **For installations**: Ask naturally if you want to install SpecKit (without mentioning `-Proceed` flag)1175. Wait for your approval via chat conversation1186. After approval: automatically re-invoke with `-Proceed` flag to execute1197. Guide you through conflict resolution one file at a time (updates only)1208. Open VSCode diff/merge tools as needed (updates only)1219. Report results with detailed summary122123**Conversational Workflow:** The skill uses a two-step approval process:124- **Step 1**: Outputs summary → script exits → waits for approval125- **Step 2**: After approval, Claude re-invokes with `-Proceed` → applies updates126127**Requirements:**128- Git installed and in PATH129- Internet connection for fetching updates from GitHub130- Write permissions to .specify/ and .claude/ directories131- Clean or staged Git working directory132133**The script is located at:** `{skill_path}/scripts/update-wrapper.ps1` (entry point) and `{skill_path}/scripts/update-orchestrator.ps1` (main logic)134135**Entry point command:**136```powershell137pwsh -NoProfile -Command "& '{skill_path}/scripts/update-wrapper.ps1' [parameters]"138```139140**Note:** Both PowerShell-style (`-CheckOnly`) and Linux-style (`--check-only`) flags are supported via the wrapper script.141142## Features143144- **Customization Preservation**: Automatically detects and preserves user customizations using normalized file hashing145- **Intelligent Conflict Resolution**: Guides through conflicts one-at-a-time with 4 options: merge editor, keep mine, use new, skip146- **Version Tracking**: Maintains `.specify/manifest.json` with file hashes, version info, and backup history147- **Automatic Backups**: Creates timestamped backups in `.specify/backups/` with automatic retention management148- **Fail-Fast with Rollback**: Automatically rolls back on any error, restoring pre-update state149- **Dry-Run Mode**: `--check-only` shows exactly what would change without applying updates150- **Constitution Integration**: Notifies when constitution template has updates (run `/speckit.constitution`)151- **Custom Command Safety**: User-created commands never overwritten, even with `--force`152153## Architecture154155### Modules156- **HashUtils**: Normalized hashing (handles line endings, trailing whitespace, BOM)157- **VSCodeIntegration**: Context detection, Quick Pick, diff/merge editor integration158- **GitHubApiClient**: GitHub Releases API interaction (unauthenticated, 60 req/hour)159- **ManifestManager**: Manifest CRUD operations with caching160- **BackupManager**: Backup creation, restoration, and retention management161- **ConflictDetector**: File state analysis and conflict detection162163### Workflow1641. Prerequisites validation (critical checks must pass, warnings allow continuation)1652. Manifest loading/creation (safe default: assume all files customized if no manifest)1663. GitHub API query for target version1674. File state analysis (6 actions: add/remove/merge/preserve/update/skip)1685. User confirmation with change preview1696. Backup creation (timestamped, excludes backups directory)1707. Selective file updates (fail-fast with automatic rollback)1718. Conflict resolution (Flow A: one-at-a-time, VSCode merge editor)1729. Manifest update (version, file hashes, customization flags)17310. Backup cleanup (keep 5 most recent, requires confirmation)17411. Detailed summary display175176## Exit Codes177178| Code | Meaning |179|------|---------|180| 0 | Success |181| 1 | General error |182| 2 | Prerequisites not met |183| 3 | Network/API error |184| 4 | Git error |185| 5 | User cancelled |186| 6 | Rollback required (automatic) |187188## Limitations189- Use this skill only when the task clearly matches the scope described above.190- Do not treat the output as a substitute for environment-specific validation, testing, or expert review.191- Stop and ask for clarification if required inputs, permissions, safety boundaries, or success criteria are missing.