Skip to content

💫 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.md
index 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 integrations
Run 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 status
cp -r .specify/templates /tmp/templates-backup
# 2. Upgrade CLI
specify 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.md
The 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 constitution
git restore .specify/memory/constitution.md
# If you backed up manually
cp /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 installation
Once 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.