Plugin Updating

Plugin Updating

Handles plugin version management for the Shopware AI Coding Tools marketplace.

Template synchronization for templates/plugin-setup/ and shared shell scripts is covered by .claude/rules/template-sync.md, which activates automatically when a template or consumer file is touched.

Plugin Inventory

Current plugin names and versions:

```! for f in plugins/*/.claude-plugin/plugin.json; do name=$(basename "$(dirname "$(dirname "$f")")") ver=$(jq -r .version "$f" 2>/dev/null) printf '%s: %s\n' "$name" "$ver" done

## Version Bump

When updating a plugin's version:

### Step 1: Identify the plugin

Match the plugin name from the user's request against the names listed above. If the name does not appear there, stop and ask the user which plugin they mean.

### Step 2: Determine version bump level

If the user specifies a target version, use it. Otherwise, reason about the changes to determine MAJOR, MINOR, or PATCH.

**Core question:** "Can users do something they could not do before?"

MAJOR — Consumer behavior must change to keep working Plugin renamed or extracted Skill invocation model changed MCP tool surface rewritten Agent names/roles replaced Config files require migration

MINOR — New user-facing capability added New skill, MCP tool, hook type, agent, command, or environment Significant new parameters on existing tools New independently-queryable test rule

PATCH — Everything else Bug fixes, refinements, internal refactoring Description/docs improvements Validation/guard additions to existing features Removing deprecated internals

**Watch for these traps:**
- "Added" does not always mean MINOR — adding validation to an existing feature is PATCH (same capability, better quality)
- "Breaking" in a description does not always mean MAJOR — if the orchestrator absorbs the change transparently, consumers are unaffected
- Batch additions that individually seem incremental can collectively warrant MINOR when they form a cohesive new capability

For detailed triggers, public API definitions, and edge cases see `references/version-bump-reasoning.md`.

### Step 3: Bump plugin.json and all SKILL.md versions

Run the bundled helper script:

```bash
bash "${CLAUDE_SKILL_DIR}/scripts/bump-plugin-version.sh"  

It updates plugins//.claude-plugin/plugin.json (surgical text replacement that preserves formatting) and rewrites the version: field in every plugins//skills/*/SKILL.md frontmatter. Do not edit these files by hand.

Step 4: Update CHANGELOG.md

Read the existing plugins//CHANGELOG.md. Add a new version section at the top following the existing format.

Step 5: Stage changes

git add plugins/

Do not commit. The user will commit when ready.

Step 6: Sync the setup skill version (if applicable)

If the plugin has a SETUP.md, the version field in plugins//skills/setting-up/SKILL.md must match the new plugin version. Update it in place — leave the rest of the frontmatter and body alone. See .claude/rules/template-sync.md for the body-sync workflow.

SETUP.md Format Reference

Plugins that participate in the setup skill pattern have a SETUP.md at their root with these required sections:

| Heading | Level | Purpose | |---------|-------|---------| | # {Plugin Name} Setup | H1 | Plugin name | | ## Prerequisites | H2 | External tools to check | | ### {tool name} | H3 | One per tool: Check, Install, Required by | | ## Configuration Files | H2 | Config files to create | | ### {filename} | H3 | One per file: Required, Location | | #### Setup Questions | H4 | Numbered questions with options | | #### Minimal Config | H4 | Simplest valid config (code block) | | ## Validation | H2 | Steps to verify setup | | ## Post-Setup | H2 | Restart requirements, next steps |

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: shopwareLabs
• Source: shopwareLabs/ai-coding-tools
• License: MIT

Install and usage instructions live in the source repository linked above.