Speckit Upgrade

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-<STAMP>/ 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?

• <each-installed-key> (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 <new-key> 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 <backup-path>/. 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 <key> --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:

• <file1>
• <file2>

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 <key> --force --script sh with argv-only execution.

Then for each previously-modified file:

diff "$BACKUP/<file>" "<file>"

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 <integration>. The legacy slash-commands still work but create duplicate triggers. Options:

1. dedupe — delete the legacy <path>/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.<single-word>.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 <plugin-root>/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 <id> or specify preset add <id> 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:

## SpecKit Upgrade Complete

**CLI version:** specify <X.Y.Z>
**Backup:** /tmp/specify-upgrade-backup-<STAMP>/ (preserved)
**Integrations upgraded:**
- claude → manifest <oldhash> → <newhash> (N modified files restored)
- codex  → manifest <oldhash> → <newhash> (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-<STAMP>/ is the operator's safety net. Surface it explicitly in the final report.