💫 Toolkit to help you get started with SDD or any other process!
docs(upgrade): document integration upgrade / extension update as the project-files upgrade path (#3326)
Pascal THUET914d7b887f25
diff --git a/docs/upgrade.md b/docs/upgrade.mdindex 0e0824dc6..708664d26 100644--- a/docs/upgrade.md+++ b/docs/upgrade.md@@ -12,7 +12,7 @@| **CLI Tool — pin a version** | `specify self upgrade --tag vX.Y.Z[suffix]` | Upgrade to a specific release tag instead of the latest stable. Suffixes are limited to dev, alpha/beta/rc, and/or build metadata forms. || **CLI Tool — manual fallback** | `uv tool install specify-cli --force --from git+https://github.com/github/[email protected]` | When `specify self upgrade` isn't available (older installs) or when you want explicit control. || **CLI Tool — manual fallback (pipx)** | `pipx install --force git+https://github.com/github/[email protected]` | Same as above, for pipx installs. |-| **Project Files** | `specify init --here --force --integration <your-agent>` | Update slash commands, templates, and scripts in your project |+| **Project Files** | Run `specify integration upgrade <key>`, then `specify extension update` | Refresh installed integration files and extensions in your project || **Both** | Run CLI upgrade, then project update | Recommended for major version updates |---@@ -89,91 +89,94 @@ specify self check## Part 2: Updating Project Files-When Spec Kit releases new features (like new slash commands or updated templates), you need to refresh your project's Spec Kit files.+When Spec Kit releases new features (like new slash commands, updated templates, or extension changes), you need to refresh the Spec Kit files that were installed into your project.### What gets updated?-Running `specify init --here --force` will update:+For existing Spec Kit projects, use the manifest-aware upgrade path first:-- ✅ **Slash command files** (`.claude/commands/`, `.github/prompts/`, etc.)-- ✅ **Script files** (`.specify/scripts/`) — **only with `--force`**; without it, only missing files are added-- ✅ **Template files** (`.specify/templates/`) — **only with `--force`**; without it, only missing files are added-- ✅ **Shared memory files** (`.specify/memory/`) - **⚠️ See warnings below**+- ✅ **Integration command/skill files** (`.claude/skills/`, `.github/prompts/`, `.agents/skills/`, etc.)+- ✅ **Managed shared scripts and templates** (`.specify/scripts/`, `.specify/templates/`) when they are unchanged from the previous managed copy+- ✅ **Installed extensions** when you run `specify extension update`++The integration upgrade command uses the install manifest to detect local edits. If a managed integration file was modified after install, the command stops and asks you to inspect the change or rerun with `--force`.### What stays safe?-These files are **never touched** by the upgrade—the template packages don't even contain them:+These files are **never touched** by the manifest-aware integration/extension upgrade path:- ✅ **Your specifications** (`specs/001-my-feature/spec.md`, etc.) - **CONFIRMED SAFE**- ✅ **Your implementation plans** (`specs/001-my-feature/plan.md`, `tasks.md`, etc.) - **CONFIRMED SAFE**+- ✅ **Your constitution** (`.specify/memory/constitution.md`) when using `specify integration upgrade`- ✅ **Your source code** - **CONFIRMED SAFE**- ✅ **Your git history** - **CONFIRMED SAFE**The `specs/` directory is completely excluded from template packages and will never be modified during upgrades.-### Update command+### 1. Check installed integrationsRun this inside your project directory:```bash-specify init --here --force --integration <your-agent>+specify integration status```-Replace `<your-agent>` with your AI coding agent. Refer to this list of [Supported AI Coding Agent Integrations](reference/integrations.md)+This reports the default integration, all installed integrations, and any modified or missing managed files. You can also inspect `.specify/integration.json`; installed integrations are listed under `installed_integrations`.-**Example:**+### 2. Upgrade each installed integration++Run this inside your project directory:```bash-specify init --here --force --integration copilot+specify integration upgrade <key>```-### Understanding the `--force` flag+Replace `<key>` with an installed integration key such as `copilot`, `claude`, or `codex`. In projects with multiple installed integrations, run the command once per installed key.-Without `--force`, the CLI warns you and asks for confirmation:+**Example:**-```text-Warning: Current directory is not empty (25 items)-Template files will be merged with existing content and may overwrite existing files-Proceed? [y/N]+```bash+specify integration upgrade claude+specify integration upgrade codex```-With `--force`, it skips the confirmation and proceeds immediately. It also **overwrites shared infrastructure files** (`.specify/scripts/` and `.specify/templates/`) with the latest versions from the installed Spec Kit release.+See the [integration reference](reference/integrations.md#upgrade-an-integration) for options such as `--script`, `--integration-options`, and `--force`.-Without `--force`, shared infrastructure files that already exist are skipped — the CLI will print a warning listing the skipped files so you know which ones were not updated.+### 3. Update installed extensions-**Important: Your `specs/` directory is always safe.** The `--force` flag only affects template files (commands, scripts, templates, memory). Your feature specifications, plans, and tasks in `specs/` are never included in upgrade packages and cannot be overwritten.-----+Run:-## ⚠️ Important Warnings+```bash+specify extension update+```-### 1. Constitution file will be overwritten+With no extension argument, this updates all installed extensions. Use `specify extension update <extension-id-or-name>` to update only one extension. See the [extensions reference](reference/extensions.md#update-extensions) for details.-**Known issue:** `specify init --here --force` currently overwrites `.specify/memory/constitution.md` with the default template, erasing any customizations you made.+### Fallback: re-run init-**Workaround:**+If a project predates manifests, has missing integration metadata, or needs a broader recovery, you can still re-run init:```bash-# 1. Back up your constitution before upgrading-cp .specify/memory/constitution.md .specify/memory/constitution-backup.md+specify init --here --force --integration <your-agent>+```-# 2. Run the upgrade-specify init --here --force --integration copilot+Use this as an escape hatch rather than the default project-file upgrade path. It refreshes the selected integration and shared project scaffolding, but it does not use the same per-integration manifest checks before overwriting files.-# 3. Restore your customized constitution-mv .specify/memory/constitution-backup.md .specify/memory/constitution.md-```+## ⚠️ Important Warnings-Or use git to restore it:+### 1. Constitution file and memory customizations-```bash-# After upgrade, restore from git history-git restore .specify/memory/constitution.md-```+`specify integration upgrade <key>` does not update `.specify/memory/constitution.md`.++The fallback `specify init --here --force --integration <your-agent>` path also preserves an existing `.specify/memory/constitution.md`; if the file is missing, init creates it from the current constitution template. You do not need a constitution backup/restore step for the manifest-aware upgrade path.-### 2. Custom script or template modifications+As with any broad fallback refresh, commit or back up local customizations before using `init --here --force` so you can review the resulting diff.-If you customized files in `.specify/scripts/` or `.specify/templates/`, the `--force` flag will overwrite them. Back them up first:+### 2. Custom integration, script, or template modifications++`specify integration upgrade <key>` blocks when manifest-tracked integration files were modified locally, unless you pass `--force`.++Shared scripts and templates are refreshed when they still match the previously recorded managed copy. Local customizations are preserved unless you explicitly use a force/refresh option that overwrites them. If you customized files in `.specify/scripts/` or `.specify/templates/`, commit or back them up first:```bash# Back up custom templates and scripts@@ -215,29 +218,29 @@ Restart your IDE to refresh the command list.# Upgrade CLI (auto-detects uv tool vs pipx install)specify self upgrade-# Update project files to get new commands-specify init --here --force --integration copilot+# Inspect installed integrations+specify integration status-# Restore your constitution if customized-git restore .specify/memory/constitution.md+# Update project files to get new commands+specify integration upgrade <key>+specify extension update```### Scenario 2: "I customized templates and constitution"```bash-# 1. Back up customizations-cp .specify/memory/constitution.md /tmp/constitution-backup.md+# 1. Commit or back up customizations+git statuscp -r .specify/templates /tmp/templates-backup# 2. Upgrade CLIspecify self upgrade-# 3. Update project-specify init --here --force --integration copilot+# 3. Use the manifest-aware project update first+specify integration upgrade <key>+specify extension update-# 4. Restore customizations-mv /tmp/constitution-backup.md .specify/memory/constitution.md-# Manually merge template changes if needed+# 4. If the upgrade reports modified managed files, inspect the diff before using --force```### Scenario 3: "I see duplicate slash commands in my IDE"@@ -262,14 +265,14 @@ rm speckit.old-command-name.mdThe git extension is now opt-in, so upgrades do not install it unless you add it explicitly.```bash-# Manually back up files you customized-cp .specify/memory/constitution.md .specify/memory/constitution.backup.md+# Upgrade CLI+specify self upgrade-# Run upgrade-specify init --here --force --integration copilot+# Refresh integration files and installed extensions+specify integration upgrade <key>+specify extension update-# Restore customizations-mv .specify/memory/constitution.backup.md .specify/memory/constitution.md+# The git extension is not added unless you run `specify extension add git````If you later decide you want the git extension's commands and hooks, install it explicitly:@@ -315,19 +318,21 @@ Alternatively, run the `/speckit.specify` command which creates `.specify/featur- Codex requires `CODEX_HOME` environment variable- Some agents need workspace restart or cache clearing-### "I lost my constitution customizations"+### "Will init overwrite my constitution customizations?"++Current `specify init --here --force` preserves an existing `.specify/memory/constitution.md`; it creates the file from the template only when it is missing.-**Fix:** Restore from git or backup:+If you previously lost constitution changes through an older workflow or manual replacement, restore from git or backup:```bash-# If you committed before upgrading+# If you committed the customized constitutiongit restore .specify/memory/constitution.md# If you backed up manuallycp /tmp/constitution-backup.md .specify/memory/constitution.md```-**Prevention:** Always commit or back up `constitution.md` before upgrading.+**Prevention:** Use `specify integration upgrade <key>` for routine project-file updates. If you need the fallback `specify init --here --force` path, commit first so you can review the full diff afterward.### "Warning: Current directory is not empty"@@ -354,7 +359,7 @@ Only Spec Kit infrastructure files:- Agent command files (`.claude/commands/`, `.github/prompts/`, etc.)- Scripts in `.specify/scripts/`- Templates in `.specify/templates/`-- Memory files in `.specify/memory/` (including constitution)+- Missing memory files such as `.specify/memory/constitution.md` may be created from templates; an existing constitution is preserved**What stays untouched:**@@ -365,7 +370,7 @@ Only Spec Kit infrastructure files:**How to respond:**-- **Type `y` and press Enter** - Proceed with the merge (recommended if upgrading)+- **Type `y` and press Enter** - Proceed with the merge when using the fallback init path- **Type `n` and press Enter** - Cancel the operation- **Use `--force` flag** - Skip this confirmation entirely:@@ -375,11 +380,11 @@ Only Spec Kit infrastructure files:**When you see this warning:**-- ✅ **Expected** when upgrading an existing Spec Kit project+- ✅ **Expected** when using the fallback init path in an existing Spec Kit project- ✅ **Expected** when adding Spec Kit to an existing codebase- ⚠️ **Unexpected** if you thought you were creating a new project in an empty directory-**Prevention tip:** Before upgrading, commit or back up your `.specify/memory/constitution.md` if you customized it.+**Prevention tip:** Before using the fallback init path, commit your current work so any refreshed files are easy to review or restore.### "CLI upgrade doesn't seem to work"@@ -418,14 +423,15 @@ uv tool install specify-cli --from git+https://github.com/github/spec-kit.git### "Do I need to run specify every time I open my project?"-**Short answer:** No, you only run `specify init` once per project (or when upgrading).+**Short answer:** No, you only run `specify init` once per project, or later as a fallback recovery path.**Explanation:**The `specify` CLI tool is used for:- **Initial setup:** `specify init` to bootstrap Spec Kit in your project-- **Upgrades:** `specify init --here --force` to update templates and commands+- **Routine project-file upgrades:** `specify integration upgrade <key>` and `specify extension update`+- **Fallback recovery:** `specify init --here --force` when integration metadata is missing or the manifest-aware path cannot be used- **Diagnostics:** `specify check` to verify tool installationOnce you've run `specify init`, the slash commands (like `/speckit.specify`, `/speckit.plan`, etc.) are **permanently installed** in your project's agent folder (`.claude/`, `.github/prompts/`, `.pi/prompts/`, `.omp/commands/`, etc.). Your AI coding agent reads these command files directly—no need to run `specify` again.