Plugin Update Workflow

Guide the user through properly documenting and versioning plugin changes. Follow systematic approach: detect changes, categorize them, update changelog, bump version, verify, and prepare for testing with fresh plugin context.

Core Principles

• Track all progress: Use TodoWrite from the start
• Follow semver: Understand patch vs minor vs major
• Document why: Changelog entries explain value, not just what changed
• Verify fresh context: New versions require headless testing to pick up changes
• Ask when unclear: Don't guess at change significance

Plugin to update: $ARGUMENTS

---

Phase 1: Change Detection

Goal: Understand what files were modified in the plugin

Actions:

1. Create todo list with all 5 phases:

   • Detect changes in plugin
   • Categorize and describe changes
   • Update CHANGELOG.md
   • Bump version in plugin.json
   • Verify and prepare for testing

2. Mark Phase 1 as in_progress

3. Read current version from plugins/$PLUGIN_NAME/.claude-plugin/plugin.json

4. Check git status for uncommitted changes in plugin directory:

   git -C /path/to/surf-market status --short plugins/$PLUGIN_NAME/
   

5. If no changes found:

   • Ask user: "No uncommitted changes found. Did you want to update anyway?"
   • If no → exit
   • If yes → ask user to describe changes manually

6. Present modified files to user:

   Current version: 0.3.2
   
   Modified files:
   M plugins/claude-code-meta/commands/update-plugin.md
   A plugins/claude-code-meta/skills/claude-code-meta/references/command-testing.md
   

7. Mark Phase 1 as completed

Output: List of changed files and current version

---

Phase 2: Change Categorization

Goal: Understand what kind of changes were made and their significance

Actions:

1. Mark Phase 2 as in_progress

2. For each modified/added file, categorize the change:

   Change Type Decision Guide:

   Added - Choose when creating something new:

   • New command file created
   • New skill added to plugin
   • New framework/section added to existing doc (e.g., sawdust deep dive)
   • New reference document created
   • New capability that didn't exist before

   Changed - Choose when modifying existing:

   • Updated command behavior (still same command)
   • Enhanced skill description or triggers
   • Improved existing functionality
   • Refactored internal implementation
   • Modified output format

   Fixed - Choose when correcting errors:

   • Bug fixes
   • Typo corrections
   • Broken links repaired
   • Incorrect logic corrected
   • Edge case handling added

   Removed - Choose when deleting:

   • Deprecated command removed
   • Feature deleted
   • Functionality stripped out

   When file is "Modified" but change is additive:

   • If adding significant new section → Added
   • If improving existing content → Changed
   • Example: Adding 7-level sawdust to framework.md → Added (new framework within file)

   Use AskUserQuestion if uncertain with these options:

   Question: "What type of change is this?"
   Header: "Change type"
   Options:
   - Added: "New feature, command, skill, or capability"
   - Changed: "Modified existing behavior or improved functionality"
   - Fixed: "Bug fix or correction"
   - Removed: "Deleted feature or deprecated functionality"
   

3. Ask for one-line description of each change:

   • "Describe this change in one line (focus on user value, not implementation)"
   • Example: "Removed output limit to show all ready items" (not "Changed head -15 to no limit")

4. Determine semver bump needed:

   Semver Guidelines:

   • Patch (0.3.2 → 0.3.3): Bug fixes, documentation, minor tweaks (no behavior change)
   • Minor (0.3.2 → 0.4.0): New features, new commands/skills (backward compatible)
   • Major (0.3.2 → 1.0.0): Breaking changes, removed features (not backward compatible)

   Decision Criteria (Use these to decide autonomously):

   PATCH (0.x.y → 0.x.y+1) - Choose when ALL of these are true:

   • ✓ No new features or commands
   • ✓ No behavior changes for existing functionality
   • ✓ Only fixing bugs, typos, or documentation errors
   • ✓ User experience stays exactly the same

   Examples:

   • Fixed typo in help text
   • Corrected broken link in documentation
   • Fixed edge case bug in existing command
   • Updated example code that was outdated
   • Clarified ambiguous wording in skill description

   MINOR (0.x.y → 0.x+1.0) - Choose when ANY of these are true:

   • ✓ Added new command, skill, or agent
   • ✓ Enhanced existing feature with new capability (backward compatible)
   • ✓ Added significant new section/framework to documentation (like 7-level analysis)
   • ✓ Improved functionality without breaking existing use cases
   • ✓ Added new optional parameters to commands

   Examples:

   • Added /ship command to show what ships today
   • Enhanced sawdust analysis from yes/no to 7-level framework
   • Added new skill for exo-coord usage patterns
   • Improved /razor to support --inbox flag
   • Added decision tree to existing documentation

   MAJOR (0.x.y → 1.0.0 OR x+1.0.0) - Choose when ANY of these are true:

   • ✓ Removed command, skill, or feature
   • ✓ Changed command syntax in non-backward-compatible way
   • ✓ Renamed required parameters
   • ✓ Changed output format that breaks downstream consumers
   • ✓ Moved files in a way that breaks imports

   Examples:

   • Removed deprecated /old-command
   • Changed /capture <text> to /capture --title <text>
   • Switched inbox from single file to per-item files (if not handled gracefully)
   • Removed required field from skill frontmatter

   When in doubt:

   1. If change adds value without breaking anything → Minor
   2. If change fixes something without adding features → Patch
   3. If change removes or breaks anything → Major
   4. If uncertain after checking criteria → Ask user (but lean toward Minor for additive changes)

   Use AskUserQuestion:

   Question: "Based on these changes, what semver bump is appropriate?"
   Header: "Version bump"
   Options:
   - Patch: "Bug fixes or documentation only"
   - Minor: "New features or commands (backward compatible) (Recommended)"
   - Major: "Breaking changes or removed features"
   

5. Calculate new version number

6. Mark Phase 2 as completed

Output: Categorized changes and new version number

---

Phase 3: Update CHANGELOG

Goal: Document changes in changelog following Keep a Changelog format

Actions:

1. Mark Phase 3 as in_progress

2. Read current plugins/$PLUGIN_NAME/CHANGELOG.md

3. Determine if creating new version section or adding to [Unreleased]:

   • If significant changes (minor/major bump) → create new version section
   • If small fixes (patch) → can add to [Unreleased] or create section

4. Build changelog entry:

   ## [$NEW_VERSION] - $(date +%Y-%m-%d)
   
   ### Added
   - New feature X that enables Y
   
   ### Changed
   - Improved Z to handle W better
   
   ### Fixed
   - Fixed issue where A caused B
   

5. Use Edit tool to add entry after ## [Unreleased] line

6. Show user the changelog diff

7. Mark Phase 3 as completed

Output: Updated CHANGELOG.md

---

Phase 4: Bump Version

Goal: Update version number in plugin.json

Actions:

1. Mark Phase 4 as in_progress

2. Read plugins/$PLUGIN_NAME/.claude-plugin/plugin.json

3. Use Edit tool to update version:

   "version": "$OLD_VERSION",
   

   →

   "version": "$NEW_VERSION",
   

4. Verify the edit succeeded

5. Mark Phase 4 as completed

Output: Updated plugin.json with new version

---

Phase 5: Verify & Test Preparation

Goal: Verify changes and explain testing requirements

Actions:

1. Mark Phase 5 as in_progress

2. Show git diff of changes:

   git -C /path/to/surf-market diff plugins/$PLUGIN_NAME/
   

3. Critical: Explain versioning and testing context

   Present to user:

   ✅ Plugin updated: v$OLD_VERSION → v$NEW_VERSION
   
   📝 Files changed:
   - CHANGELOG.md (added v$NEW_VERSION entry)
   - plugin.json (version bumped)
   - [other modified files]
   
   🔄 IMPORTANT: Plugin Version Context
   
   The current Claude session is still using v$OLD_VERSION (cached).
   To test the new v$NEW_VERSION:
   
   1. Headless Claude instances will pick up v$NEW_VERSION
      → Use: claude --dangerously-skip-permissions "command"
   
   2. Sub-agents spawned from this session will use v$OLD_VERSION
      → They see cached plugin context
   
   3. New interactive sessions will load v$NEW_VERSION
      → Restart Claude Code or open new terminal
   
   ✅ Recommended: Test with headless before committing
   

4. Ask user: "Ready to commit these changes? [y/n]"

   If yes:

   git -C /path/to/surf-market add plugins/$PLUGIN_NAME/
   git -C /path/to/surf-market commit -m "chore($PLUGIN_NAME): $BRIEF_SUMMARY
   
   - [list key changes]
   
   Version: $OLD_VERSION → $NEW_VERSION"
   

5. Mark Phase 5 as completed

6. Mark all todos as completed

Output: Verification summary and commit (if approved)

---

Example Usage

# After editing commands/work.md
/update-plugin meta

# Interactive prompts:
# → Change type: Changed
# → Description: Removed output limit to show all ready items
# → Semver bump: Patch
# → Shows changelog preview
# → Shows diff
# → Commit? y

# Result:
# - CHANGELOG.md updated
# - plugin.json: 0.3.2 → 0.3.3
# - Changes committed
# - Reminded to test with headless

---

Integration with Workflow

This command should be triggered:

• Manually: After editing plugin files, run /update-plugin <name>
• Proactively (future): continuous-improvement skill detects plugin edits and suggests running this

When NOT to use:

• Experimental changes not ready to version
• Changes to non-plugin files (use normal git workflow)
• During active development (wait until feature complete)

---

Related Documentation

• Semver spec: https://semver.org/
• Keep a Changelog: https://keepachangelog.com/
• Plugin versioning context: See references/command-testing.md

---

Command version: 1.0.0 Created: 2025-12-20