Introduce upgrade and remove command

[jaycangel]

Current issue:
There doesn’t seem to be an easy way to upgrade or completely remove spec-kit once it’s been added to an existing project. Because spec-kit installs files across many folders, cleaning it up or replacing it is cumbersome and error-prone.

Suggested improvement:
Provide a built-in command or documented process to upgrade or uninstall spec-kit from a project. This could include:

• A CLI command like spec-kit upgrade or spec-kit remove.
• A manifest or tracking mechanism that records all installed files, making cleanup straightforward.
• Clear documentation on safe manual removal steps if an automated option isn’t feasible.

[albahrani]

The upgrade command is something I am missing a lot. It also hinders the userbase to provide constructive feedback to the latest changes/aditions if there is no clear path for upgrading.

I also thought about an upgrade command, but I think I would prefer an /upgrade command instead since it would allow to utilize AI to upgrade and merge everything. Some parts could use scripts, like the current commands do already.

The hardest part, I think, is to ensure that plan and tasks are "upgraded", so maybe for the start just support upgrade if no plan is in work (between features).
An extension would be ending the current plan (on the old templates) and creating a new plan (on the upgraded template) only with the tasks stil open.

[thawkins]

I just reinstall it in the project but don't do an init.

[BurtHarris]

I had some success using something like this to upgrade:

cd <project root dir>
uvx --from git+https://github.com/github/spec-kit.git specify init --here

The --here causes it to install into an existing project. No guarantees, but it worked for me, once.

[Peltori]

Well it works if you have a project that is just a basic empty repo or doesn't have code in it already. Don't know what will happen if you do that to an existing project.

[albahrani]

The problem is also, that this is not quaranteed to work between versions as the scripts and the constitution.md are not bound to a feature lifecycle, but are "global".
That is why I suggest a first step to focus on an upgrade process during an "idle" state of the project.

There the next command will be (currently) /specify ... and that switches the branch, created markdown documents based on the current templates and constitution, ... and so on. By design (I guess) the feature lifecycle is created kind of "independend" (maybe because of parallel feature implementation in mind???).

To support an upgrade while features are "in flight", the "only" additional step would be closing out the features early (not fully implemented, but in green state). Then upgrade in the "idle" state and finally starting new features ( /specify flow) with the parts of the plan ( and maybe tasks) left open.

[foertel]

Because spec-kit installs files across many folders

At least all the spec-kit files are now in .specify/. We could most likely isolate the agent files (like .claude/commands) via namespaces as well. Personally I'd even prefer symlinks, but I don't know about the powershell folks.

Problems with project-specific modifications to upgradeable files are discussed in #387

The upgrade command is something I am missing a lot.

You can just run the uvx based installer again. It will prompt you:

Warning: Current directory is not empty (20 items)
Template files will be merged with existing content and may overwrite existing files
Do you want to continue? [y/N]: 

It will then download the most current release and replace its own files accordingly, leaving your code untouched.

That is why I suggest a first step to focus on an upgrade process during an "idle" state of the project.

Yep, definitively. You don't want to /plan in one version and /tasks in another. 👌 Just like you would not switch other major software versions mid-sprint.

[pasevin]

I agree. If I want to update to the latest SpecKit version I have to re-initialize it and overwrite a bunch of files. Which is not that bad if the ./specify dir is tracked by git. You can see the changes made and review them.

But it feels that you might miss something important, like for example in the latest update my constitution.md has been updated.
Obviously I had to reject the changes, cause my constitution is already generated. But what if there's something new and important in this new upgrade related to the constitution generation, maybe it would be worth to re-generate it from scratch using the already user generated constitution. I could ask LLM to do this with a couple of manual operations, but it doesn't feel right.

This is just one example, other files I have not customized, so I'm fine just accepting the changes for now. But it would be good to have some sort of upgrade command or a script or a prompt for re-generating constitution for example based on the new template.

[albahrani]

Regenerating the constitution based on the new template with the old constitution as input was what I did during my spec-kit upgrade today. Worked quite well, but a being a bit more explicit would of cause be better.

[ricardoasensio]

The biggest problem lies in the replacement and loss of constitution.md when upgrade.
The process should include a safeguard that detects when the file has already been modified and prompts the user with options: skip / upgrade / restart constitution.md.

[foertel]

No, the constitution should not be in a place that is overwritten by an update at all. 😊

[jeremyeder]

Yeah, this is like requiring users to rebase their fork just to use the project... for enterprise solution we will need more thought here specifically. I think it's an unnecessary mixing of user state. I doubt this is enought but just introducing teams to spec-kit, this is the first thing they seem to be missing: #316

Unsure whether that gets us the control we want. I also think that constitutions and specs generally should be dynamically assembled via a web service (or something like that). Same goes for AGENTS.md....some external source of truth has to govern these things if we are to use spec-kit 👍

[JLevy99]

I would like to see a way to do a controlled update of spec kit by project. i.e. show me the impact of the update and let me decide what I want to update for this project. Just my opinion based on using spec kit for 3 days :)

[rd-michel]

It would also be nice if you could add version numbers to the templates.

eg
** created with spec-kit 0.25 **

If you later check the Git repository, you can see exactly which version of Spec-Kit was used to create this software.

[albahrani]

What about not using template files at all, but including them in the according commands/prompts?

[georgfranz]

Spec kit is great, but an update feature is really missing.

[LuSrackhall]

+1

[aarchila]

Version actual: No parece haber una manera fácil de actualizar o eliminar completamente el kit de especificaciones una vez que se ha agregado a un proyecto existente así mismo limpiarlo o reemplazarlo es engorroso y propenso a errores.

Mejora sugerida:Proporcione un comando integrado o un proceso documentado para actualizar o desinstalar spec-kit de un proyecto. Esto podría incluir:

• Un comando de CLI como spec-kit upgrade o spec-kit remove.
• Un manifiesto o mecanismo de seguimiento que registra todos los archivos instalados, lo que facilita la limpieza.
• Documentación clara sobre los pasos de eliminación manual segura si una opción automatizada no es factible.

[bizcad]

Replacing Files Will Not Work

Rerunning the init command will not work for upgrades because I have made modifications to the all the templates and scripts as I have been working with spec-kit. If I upgrade to get functionality to the latest features, I will lose the customizations I have made to the base .md files, scripts and templates.

⚠️ Alert: I am developing an Aspire/Blazor app.

There are two parts to an upgrade.

• Changes that the authors have made to the base .md, templates and scripts between versions.
• Customizations that user, that's me, made to the base files before I ran a command.

I was not thinking clearly about what would happen if I changed a file and then ran it. So I did not keep track of edits or copilot

Example

My constitution.md file has the following section in it to customize the code quality.

My customization

I wanted my project to be in accordance with Clean Code principles.

    ### I. Code Quality
    - All code must be readable, maintainable, and self-documenting.
    - Use meaningful names, avoid magic numbers, and follow single responsibility and DRY principles.
    - Refactor continuously, but re-check performance baselines after major refactors.
    - Use consistent naming conventions (PascalCase for public classes, etc.) and folder structures.
    - Prefer composition over inheritance (exceptions must be documented).
    - All public methods/classes must include XML documentation (except generated code or private/internal APIs where justified).
    - Automated formatting (e.g., dotnet format) is required pre-commit.
    - No circular dependencies; enforce via architecture tests.
    - All code must comply with [CleanCodeRules.md](../ClientFiles/CleanCodeRules.md); reviewers may cite these rules in PRs.

Specific global requirement for my platform.

• I also wanted to modify the specs to include coding best practices
• In my case it was because I am writing an Aspire/Blazor app. Here is an example of another customization I made to constitution.md

### III. User Experience & Accessibility
- UI components must be reusable, accessible (WCAG 2.1 AA), and follow a consistent design language.
- All forms must include validation feedback, keyboard navigation, and accessibility tags.
- Responsive design for desktop, tablet, and mobile.
- No hard-coded strings; use resource files for localization.
- Accessibility: ARIA tags, color contrast, and keyboard navigation required.
- All Blazor code must comply with [BlazorBestPractices.md](../ClientFiles/BlazorBestPractices.md); reviewers may cite these rules in PRs.

Possible solution

When I run a command to upgrade, the system should do a diff on all of the current files and make a three way comparison between:

• previous spec-kit files
• upgraded spec-kit files
• my customized spec-kit files

There should then be prompts to approve the changes, like copilot does when you tell it to make a change to your code.