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

[PascalThuet]

Summary

• Reframe project-file upgrades around the manifest-aware specify integration upgrade <key> flow.
• Add specify integration status and specify extension update to the documented upgrade path.
• Keep specify init --here --force --integration <your-agent> documented as a fallback recovery path.
• Replace the old constitution backup/restore guidance with the current behavior: existing .specify/memory/constitution.md is preserved, while missing constitution files are created from the template.
• Update common upgrade scenarios and troubleshooting so they no longer present full re-init as the routine project update path.

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 --force is explicit. Projects with multiple integrations or installed extensions also need guidance to refresh each installed integration and then update extensions.

Validation

• git diff --check
• npx markdownlint-cli2 docs/upgrade.md

AI Disclosure

This PR was prepared by OpenAI Codex (model: GPT-5) acting as an AI coding agent on behalf of @PascalThuet.

[Copilot]

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 update to 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

[mnriem]

Please address Copilot feedback. If not applicable, please explain why

[PascalThuet]

Copilot review follow-up

Changes

• Replaced the + between the two project-update commands with an explicit run this, then that sequence, avoiding accidental copy/paste as a shell token.
• Changed the extension placeholder to <extension-id-or-name> and clarified that omitting the argument updates every installed extension.
• Rebased the branch onto the current main.

Validation

• npx markdownlint-cli2 docs/upgrade.md: passed
• git diff --check: passed
• CLI source confirms that specify extension update accepts an extension ID or display name.

Head commit: 5db8065

The two review threads were intentionally left open for the reviewer or PR author to resolve.

---

Posted on behalf of @PascalThuet by OpenAI Codex (model: GPT-5, autonomous).

[Copilot]

Review details

• Files reviewed: 1/1 changed files
• Comments generated: 1
• Review effort level: Medium

[mnriem]

Please address Copilot feedback

[PascalThuet]

Addressed the latest Copilot review round.

The upgrade guide now points Claude users to .claude/skills/, matching the current skills-based claude integration and the integrations reference. No broader documentation changes were needed.

Validation: npx markdownlint-cli2 docs/upgrade.md passed; git diff --check passed; the path was verified against ClaudeIntegration.commands_subdir.

Commit: d34644b1d456c98497b9b9ceb72f05cc63e5d3bb

The review thread remains open for the reviewer or PR author to resolve.

Posted on behalf of @PascalThuet by OpenAI Codex (model: GPT-5, autonomous).

[Copilot]

Review details

• Files reviewed: 1/1 changed files
• Comments generated: 0 new
• Review effort level: Medium