From 34f177483a874a43aa5278278637c44f30c175e8 Mon Sep 17 00:00:00 2001 From: Pascal Date: Fri, 3 Jul 2026 23:43:24 +0200 Subject: [PATCH] docs: document manifest-aware project upgrades Assisted-by: OpenAI Codex (model: GPT-5, autonomous) --- docs/upgrade.md | 128 ++++++++++++++++++++++++++++-------------------- 1 file changed, 75 insertions(+), 53 deletions(-) diff --git a/docs/upgrade.md b/docs/upgrade.md index 0e0824dc61..a6deddb1a9 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/spec-kit.git@vX.Y.Z` | 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/spec-kit.git@vX.Y.Z` | Same as above, for pipx installs. | -| **Project Files** | `specify init --here --force --integration ` | Update slash commands, templates, and scripts in your project | +| **Project Files** | `specify integration upgrade ` + `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,75 +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/commands/`, `.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 +specify integration status ``` -Replace `` 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`. + +### 2. Upgrade each installed integration + +Run this inside your project directory: + +```bash +specify integration upgrade +``` + +Replace `` with an installed integration key such as `copilot`, `claude`, or `codex`. In projects with multiple installed integrations, run the command once per installed key. **Example:** ```bash -specify init --here --force --integration copilot +specify integration upgrade claude +specify integration upgrade codex ``` -### Understanding the `--force` flag +See the [integration reference](reference/integrations.md#upgrade-an-integration) for options such as `--script`, `--integration-options`, and `--force`. -Without `--force`, the CLI warns you and asks for confirmation: +### 3. Update installed extensions -```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] +Run: + +```bash +specify extension update ``` -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. +With no extension name, this updates all installed extensions. Use `specify extension update ` to update only one extension. See the [extensions reference](reference/extensions.md#update-extensions) for details. -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. +### Fallback: re-run init -**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. +If a project predates manifests, has missing integration metadata, or needs a broader recovery, you can still re-run init: ---- +```bash +specify init --here --force --integration +``` + +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. ## ⚠️ Important Warnings -### 1. Constitution file will be overwritten +### 1. Constitution file and memory customizations + +`specify integration upgrade ` does not update `.specify/memory/constitution.md`. -**Known issue:** `specify init --here --force` currently overwrites `.specify/memory/constitution.md` with the default template, erasing any customizations you made. +The fallback `specify init --here --force --integration ` path can overwrite shared memory files, including `.specify/memory/constitution.md`. If you use the fallback path and customized your constitution, back it up or commit it first. **Workaround:** ```bash -# 1. Back up your constitution before upgrading +# 1. Back up your constitution before using the fallback init path cp .specify/memory/constitution.md .specify/memory/constitution-backup.md -# 2. Run the upgrade +# 2. Run the fallback init refresh specify init --here --force --integration copilot # 3. Restore your customized constitution @@ -167,13 +186,15 @@ mv .specify/memory/constitution-backup.md .specify/memory/constitution.md Or use git to restore it: ```bash -# After upgrade, restore from git history +# After the fallback init refresh, restore from git history git restore .specify/memory/constitution.md ``` -### 2. Custom script or template modifications +### 2. Custom integration, script, or template modifications + +`specify integration upgrade ` blocks when manifest-tracked integration files were modified locally, unless you pass `--force`. -If you customized files in `.specify/scripts/` or `.specify/templates/`, the `--force` flag will overwrite them. Back them up first: +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 +236,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 +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 +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 +283,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 +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: @@ -320,14 +341,14 @@ Alternatively, run the `/speckit.specify` command which creates `.specify/featur **Fix:** Restore from git or backup: ```bash -# If you committed before upgrading +# If you committed before using the fallback init path 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 ` for routine project-file updates. If you need the fallback `specify init --here --force` path, commit or back up `constitution.md` first. ### "Warning: Current directory is not empty" @@ -365,7 +386,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 +396,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 or back up your `.specify/memory/constitution.md` if you customized it. ### "CLI upgrade doesn't seem to work" @@ -418,14 +439,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 ` 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.