# Speckit Upgrade > Upgrade an existing SpecKit installation safely. Use when the operator says: 'upgrade speckit', 'update speckit', 'specify integration upgrade', 'speckit migration to skills', 'safely upgrade spec-kit', 'bump speckit version', '$speckit-upgrade', or has an existing .specify/ directory and wants to move to the current spec-kit release. Preserves customizations (constitution.md, template overrides) via backup-and-restore. Supports upgrading one or both integrations (Claude Code, Codex CLI). Hands off to $speckit-install when .specify/ is missing. Not for installing speckit for the first time (use $speckit-install), not for scaffolding a new spec ($speckit-scaffold-spec), and not for installing this plugin's bundled Codex subagents ($install). - Skill: `racecraft-lab/speckit-upgrade-2` (Agent Skill, multi-file: 2 files) - Install (CLI): `npx skillmds@latest add racecraft-lab/speckit-upgrade-2` - Raw SKILL.md: https://api.skillmd.com/api/skills/racecraft-lab/speckit-upgrade-2/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Integrations & APIs - Author: racecraft-lab (https://skillmd.com/u/racecraft-lab) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/racecraft-lab/speckit-upgrade-2 --- # SpecKit Upgrade ## Scope Upgrade an existing SpecKit installation in the current repository safely. Preserves `.specify/memory/constitution.md` and any other locally-modified files via backup-then-force-then-restore. Supports upgrading one or both integrations (`claude`, `codex`). If `.specify/` is missing, hands off to `$speckit-install` — upgrade only operates on existing installs. This skill is **mutation-heavy** (it modifies files in `.specify/`, `.claude/`, `.codex/`, and writes backups to `/tmp/`). It runs only on explicit operator request and never auto-fires from other skills. ## Scope Boundaries — Not For - Initial install (no `.specify/` directory yet). That is `$speckit-install`. This skill hands off to it automatically. - Scaffolding a new spec from the technical roadmap. That is `$speckit-scaffold-spec`. - Installing this plugin's own bundled Codex subagent TOML files into `~/.codex/agents/`. That is `$install`. - Upgrading the SpecKit CLI binary itself (`specify` package). The operator runs that with `uv tool install --force` — this skill detects when it's out of date and recommends the command, but does not run it for them. ## Repository Structure Migration Guidance For existing projects, after integration upgrade and verification, report that repository structure migration is not available through the current runner. The `migrate-structure` operation has `promotion_status=deferred` and no authoritative request. Neither `dry_run` nor `apply` is an operator contract; do not invoke the operation or claim that it will report or mutate repository state. Record the deferred capability gap and leave repository structure unchanged. Tier-2 PROCESS relocation is separate, but `relocate-process-artifacts` is also deferred and unavailable. Do not recommend or auto-run either operation. ## Input Accept optional integration keys as arguments: - `$speckit-upgrade` (upgrade all installed integrations interactively) - `$speckit-upgrade claude` - `$speckit-upgrade codex` - `$speckit-upgrade claude codex` ## Hard Constraints - Always snapshot the repo state to `/tmp/specify-upgrade-backup-/` BEFORE the first `specify integration upgrade` invocation. - Never use `--force` on the first attempt. Try the safe path first; only escalate to `--force` after explicit operator confirmation AND after the backup exists. - Never delete files from `.claude/commands/` or `.codex/prompts/` without explicit operator confirmation in the dedupe step. - Never delete non-SpecKit-managed files. SpecKit-managed slash-command files are exactly those matching `speckit.*.md` (the dot-prefixed legacy form). Extension commands like `speckit.speckit-utils.doctor.md` are NOT SpecKit-managed and must be preserved. - Never modify `.specify/memory/constitution.md` mid-flight without explicit operator instruction. Restore the operator's backup verbatim, or leave the freshly-templated placeholder in place if they explicitly said so. - Never touch this plugin's own files (`.claude-plugin/`, `codex-skills/`, plugin's `commands/`). - If any `specify` invocation fails for non-diff reasons (network, missing source bundle), STOP and report — do not retry silently. ## Procedure ### 1. Detect state; hand off if needed Use a filesystem directory check for `.specify/` and record the state as PRESENT or ABSENT. If ABSENT: STOP this skill and invoke `$speckit-install` (upgrade operates only on existing installs). If PRESENT: continue. ### 2. Capture current CLI version and installed integrations Use argv-only execution to capture the `specify` version, run `specify self check`, and run `specify integration list`. Preserve stdout, stderr, and exit status for each command in the report. Surface to the operator: - Current CLI version (e.g. `specify 0.6.1`). - Whether `specify self check` reports a newer release. - Each installed integration with its current status. If the CLI itself is outdated, recommend: Invoke `uv tool install specify-cli --force --from git+https://github.com/github/spec-kit.git` with argv-only execution, then re-run this skill after the CLI update finishes. Ask the operator to either upgrade the CLI first (then re-invoke this skill) or confirm they want to proceed with the current CLI version. ### 3. Resolve which integrations to upgrade If the operator passed keys, use them. Otherwise ask: > Which integrations should I upgrade? > - `` (currently installed) > - `all` for everything that's installed > > If you want to ADD a new integration (e.g., add `codex` to a > `claude`-only repo), use `$speckit-install ` instead. ### 4. Snapshot the repo state Create a timestamped backup directory outside the repo, copy `.specify/`, and copy any present `.claude/`, `.codex/`, and `.github/` directories into that backup using filesystem APIs or argv-only file operations. Report the backup path and copied entries. Tell the operator: "Repo state snapshotted to `/`. Manual rollback: restore `.specify/` and any listed integration directories from that backup." ### 5. Per-integration upgrade For each integration the operator chose: #### 5a. Safe (no --force) attempt Invoke `specify integration upgrade --script sh` with argv-only execution. The CLI is diff-aware. If it succeeds, capture output and move to the next integration. #### 5b. If blocked: structured triage The CLI block message names each modified file. Surface them and ask: > The upgrade is blocked because these files are locally modified: > - `` > - `` > > Options: > > 1. `force-and-restore` — back up each modified file (already in > `$BACKUP`), run `--force` to take the new template, then offer > to restore your modifications on top. Recommended when the > upstream updates are bigger than your local edits. > > 2. `keep-mine` — skip this integration's upgrade. Modifications > stay; you miss the upstream template updates. > > 3. `manual-merge` — abort this skill, examine the diff yourself, > re-run after deciding. On `force-and-restore`, invoke `specify integration upgrade --force --script sh` with argv-only execution. Then for each previously-modified file: ```text diff "$BACKUP/" "" ``` Ask whether to restore (file-by-file or all-at-once): - `constitution.md` — almost always restore the backup. This is the operator's project content. - Templates / scripts / gate validators — case-by-case. The CLI's new versions usually carry fixes/features the operator wants. ### 6. Deduplicate legacy commands when both forms are present After upgrading, the new skills directories may now exist alongside the legacy slash-command files. Detect: Use filesystem glob checks to detect legacy command/prompt entries and current skills entries for Claude and Codex. If BOTH legacy and skills paths exist for an integration: > Both legacy slash-commands and skills are installed for ``. > The legacy slash-commands still work but create duplicate triggers. Options: > > 1. `dedupe` — delete the legacy `/speckit.*.md` files. > Recommended unless downstream tooling references the > slash-command names. > 2. `keep-both` — leave the duplicates in place. On `dedupe`, delete only files matching `speckit..md` (e.g. `speckit.constitution.md`, `speckit.specify.md`, `speckit.plan.md`). Files like `speckit.speckit-utils.doctor.md` and any non-`speckit.` files MUST be preserved — those are extension commands or unrelated. Show the exact deletion list before running `rm` so the operator can confirm. ### 7. Verify Invoke `specify check` and `specify integration list` with argv-only execution. Preserve stdout, stderr, and exit status. Confirm each upgraded integration shows `installed` and reports the new manifest. Report any verification mismatch — do not silently continue. ### 8. Offer missing curated extensions and presets speckit-pro maintains a manual recommendation catalog of community extensions and presets. The full list is in `speckit-pro/skills/speckit-coach/references/presets-extensions-guide.md` (section: "The curated set"). Compare `.specify/extensions/` and `.specify/presets/` against the entries in `/scripts/curated-set.json`. - If every entry is present: report "Curated extensions and presets already installed." Continue to Step 9. - Otherwise, list the missing entries and ask which to install. Recommended default is **all**. For each accepted entry, give the operator the `specify extension add ` or `specify preset add ` command and run it only after they confirm. Skipped entries leave the autopilot's post-implementation parallel group running with reduced coverage; it does not fail. ### 9. Report Return a structured summary: ```text ## SpecKit Upgrade Complete **CLI version:** specify **Backup:** /tmp/specify-upgrade-backup-/ (preserved) **Integrations upgraded:** - claude → manifest → (N modified files restored) - codex → manifest → (clean upgrade, no blocks) **Slash-commands deduped:** Yes (claude) / No-changes (codex) **Customizations preserved:** - .specify/memory/constitution.md (restored from backup) - .specify/templates/spec-template.md (kept upgrade version; your edits saved at $BACKUP) - SpecKit prerequisite helper restored from backup **Next steps:** 1. Restart Codex (and Claude Code if it's running) so the new skills load. 2. Skim the summary above — if you preferred the old version of any file, restore from $BACKUP/. 3. Run `specify check` independently to confirm health. ``` Do not continue into any other workflow in the same skill. Upgrade ends here. ## Failure Handling STOP and report — do not improvise — when: - The CLI itself is missing (uncommon for upgrade, but possible; recommend installing it via `$speckit-install`). - A `specify integration upgrade` call fails for non-diff reasons. - The backup directory could not be created (filesystem full, permission denied, etc.). - The operator declines all three options in Step 5b for a blocked upgrade. Their choice stands; do not retry. - A restore step fails mid-flight. Report which files succeeded, which did not, and the backup path. The backup at `/tmp/specify-upgrade-backup-/` is the operator's safety net. Surface it explicitly in the final report.