Upgrade Plugin

Orchestrate project-level migrations by reading CHANGELOG.md as the single source of truth for migration steps.

When to Use

Called by /workflows:upgrade command to handle the upgrade process.

How It Works

1. Detect Current Version

Read thoughts/.version in the project directory:

current: v1.2.2
migrated_from: v1.2.1
migration_date: 2026-02-03

If file doesn't exist, detect from directory structure and create it.

2. Read CHANGELOG

Read CHANGELOG.md from the plugin directory to understand:

• •What changed in the target version
• •Migration steps required
• •Version detection patterns
• •What to ask the user

The CHANGELOG contains all version-specific migration logic.

3. Execute Migration

Follow the migration steps described in CHANGELOG:

• •Ask user questions using AskUserQuestion (for groupings, edge cases, cleanup)
• •Copy/move files as described
• •Update cross-references
• •Preserve originals until user confirms cleanup

4. Update Version File

After successful migration, update thoughts/.version:

current: v1.3.0
migrated_from: v1.2.2
migration_date: 2026-02-04

Key Principles

• •CHANGELOG is source of truth - All version-specific logic lives there
• •Project-level tracking - Each project has its own thoughts/.version
• •Ask, don't assume - Use AskUserQuestion for all decisions
• •Preserve data - Never delete without user confirmation
• •Generate reports - Show what was done after migration

Example Workflow

1. User runs /workflows:upgrade
2. Skill reads thoughts/.version → "v1.2.2"
3. Skill reads CHANGELOG.md → finds v1.3.0 migration section
4. Skill follows migration steps from CHANGELOG
5. Skill asks user questions via AskUserQuestion
6. Skill executes migration
7. Skill updates thoughts/.version → "v1.3.0"
8. Skill generates report

This design means the skill never needs updating - only CHANGELOG changes per version.