docs(upgrade): document integration upgrade / extension update as the project-files upgrade path#3326
Open
PascalThuet wants to merge 1 commit into
Open
Conversation
PascalThuet
force-pushed
the
docs/upgrade-project-files-path
branch
from
51f9b1c to
34f1774
Compare
PascalThuet
changed the title
Assisted-by: OpenAI Codex (model: GPT-5, autonomous)
PascalThuet
force-pushed
the
docs/upgrade-project-files-path
branch
from
34f1774 to
29f29a8
Compare
Contributor
There was a problem hiding this comment.
Pull request overview
Updates the upgrade guide to prioritize the manifest-aware project refresh workflow (integrations + extensions) over full re-init, aligning documentation with the current integration/extension management model in Spec Kit.
Changes:
- Reframes project updates around
specify integration status+specify integration upgrade <key>as the primary upgrade path. - Adds
specify extension updateto the documented project upgrade flow. - Updates constitution guidance to reflect current behavior (preserve existing; only create from template when missing), keeping
specify init --here --force --integration …as a fallback.
Show a summary per file
| File | Description |
|---|---|
| docs/upgrade.md | Rewrites the project upgrade instructions to use integration manifests and extension updates, with updated safety/warnings and scenarios. |
Review details
Tip
Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
- Files reviewed: 1/1 changed files
- Comments generated: 2
- Review effort level: Low
| | **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** | `specify integration upgrade <key>` + `specify extension update` | Refresh installed integration files and extensions in your project | |
| ``` | ||
|
|
||
| ### 1. Constitution file will be overwritten | ||
| With no extension name, this updates all installed extensions. Use `specify extension update <name>` to update only one extension. See the [extensions reference](reference/extensions.md#update-extensions) for details. |
mnriem
requested changes
Jul 6, 2026
mnriem
left a comment
mnriem
left a comment
Collaborator
There was a problem hiding this comment.
Please address Copilot feedback. If not applicable, please explain why
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
specify integration upgrade <key>flow.specify integration statusandspecify extension updateto the documented upgrade path.specify init --here --force --integration <your-agent>documented as a fallback recovery path..specify/memory/constitution.mdis preserved, while missing constitution files are created from the template.Why
The upgrade guide currently sends existing projects through
specify init --here --force, even though installed integrations now have manifests that can detect modified managed files and block unsafe overwrites unless--forceis explicit. Projects with multiple integrations or installed extensions also need guidance to refresh each installed integration and then update extensions.Validation
git diff --checknpx markdownlint-cli2 docs/upgrade.mdAI Disclosure
This PR was prepared by OpenAI Codex (model: GPT-5) acting as an AI coding agent on behalf of @PascalThuet.