External/spec-kit
1
0
Fork 0
mirror of https://github.com/github/spec-kit.git synced 2026-08-15 14:02:04 +02:00
Code Issues Packages Projects Releases Wiki Activity

docs(upgrade): document integration upgrade / extension update as the project-files upgrade path (#3326)

Browse Source 
* docs: document manifest-aware project upgrades

Assisted-by: OpenAI Codex (model: GPT-5, autonomous)

* docs: clarify project upgrade commands

Assisted-by: OpenAI Codex (model: GPT-5, autonomous)

* docs: correct Claude skills path

Assisted-by: Codex (model: GPT-5, autonomous)
This commit is contained in:
Pascal THUET
2026-07-22 07:25:49 -05:00
committed by GitHub
parent 29877825ef
commit 914d7b887f
1 changed files with 88 additions and 82 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/upgrade.md
+88 -82
View File
@@ -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 <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 integration status
```
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 <key>
```
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.
**Example:**
```bash
specify integration upgrade claude
specify integration upgrade codex
```
See the [integration reference](reference/integrations.md#upgrade-an-integration) for options such as `--script`, `--integration-options`, and `--force`.
### 3. Update installed extensions
Run:
```bash
specify extension update
```
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.
### Fallback: re-run init
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 <your-agent>
```
Replace `<your-agent>` with your AI coding agent. Refer to this list of [Supported AI Coding Agent Integrations](reference/integrations.md)
**Example:**
```bash
specify init --here --force --integration copilot
```
### Understanding the `--force` flag
Without `--force`, the CLI warns you and asks for confirmation:
```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]
```
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.
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.
**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.
---
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
**Known issue:** `specify init --here --force` currently overwrites `.specify/memory/constitution.md` with the default template, erasing any customizations you made.
`specify integration upgrade <key>` does not update `.specify/memory/constitution.md`.
**Workaround:**
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.
```bash
# 1. Back up your constitution before upgrading
cp .specify/memory/constitution.md .specify/memory/constitution-backup.md
As with any broad fallback refresh, commit or back up local customizations before using `init --here --force` so you can review the resulting diff.
# 2. Run the upgrade
specify init --here --force --integration copilot
### 2. Custom integration, script, or template modifications
# 3. Restore your customized constitution
mv .specify/memory/constitution-backup.md .specify/memory/constitution.md
```
`specify integration upgrade <key>` blocks when manifest-tracked integration files were modified locally, unless you pass `--force`.
Or use git to restore it:
```bash
# After upgrade, restore from git history
git restore .specify/memory/constitution.md
```
### 2. Custom script or template modifications
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 +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?"
**Fix:** Restore from git or backup:
Current `specify init --here --force` preserves an existing `.specify/memory/constitution.md`; it creates the file from the template only when it is missing.
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.