Upgrade Guide

Quick Reference

What to Upgrade	Command
CLI tool only	uv tool install maistik-specify-cli --force --from git+ssh://git@gitlab.com/maistik-studio/tools/spec-kit.git
Project files	specify init --here --force --ai claude
Both	Run CLI upgrade first, then project update

Upgrade the CLI

If installed with uv tool install

uv tool install maistik-specify-cli --force --from git+ssh://git@gitlab.com/maistik-studio/tools/spec-kit.git

If using uvx

No upgrade needed — uvx always fetches the latest version.

Verify

specify check

Update Project Files

When new slash commands or templates are released, refresh your project:

specify init --here --force --ai claude

What Gets Updated

• Slash command files (.claude/commands/, .gemini/commands/, etc.)
• Script files (.specify/scripts/)
• Template files (.specify/templates/)
• Memory files (.specify/memory/)

What Stays Safe

Your work is never touched:

• Feature specifications (specs/001-*/spec.md, etc.)
• Implementation plans and tasks
• Source code
• Git history

Constitution Backup

The upgrade overwrites .specify/memory/constitution.md with the default template.

Before upgrading:

cp .specify/memory/constitution.md .specify/memory/constitution-backup.md

After upgrading:

mv .specify/memory/constitution-backup.md .specify/memory/constitution.md
# or restore from git:
git restore .specify/memory/constitution.md

Common Scenarios

New slash commands only

uv tool install maistik-specify-cli --force --from git+ssh://git@gitlab.com/maistik-studio/tools/spec-kit.git
specify init --here --force --ai claude
git restore .specify/memory/constitution.md

Customized templates and constitution

# Back up
cp .specify/memory/constitution.md /tmp/constitution-backup.md
cp -r .specify/templates /tmp/templates-backup

# Upgrade
uv tool install maistik-specify-cli --force --from git+ssh://git@gitlab.com/maistik-studio/tools/spec-kit.git
specify init --here --force --ai claude

# Restore
mv /tmp/constitution-backup.md .specify/memory/constitution.md

Duplicate slash commands in IDE

Some IDE-based agents (Kilo Code, Windsurf) may show duplicates after upgrading. Delete old command files and restart your IDE.

Project without Git

specify init --here --force --ai claude --no-git

Set SPECIFY_FEATURE to tell Spec Kit which feature directory to use:

export SPECIFY_FEATURE="001-my-feature"

Troubleshooting

Commands not showing after upgrade

1. Restart your IDE completely
2. Verify files exist: ls .claude/commands/
3. Check you're in the correct directory

Lost constitution

git restore .specify/memory/constitution.md

CLI not found after upgrade

uv tool list          # Should show maistik-specify-cli
which specify         # Should show the uv tool path

If missing, reinstall:

uv tool uninstall maistik-specify-cli
uv tool install maistik-specify-cli --from git+ssh://git@gitlab.com/maistik-studio/tools/spec-kit.git