# Plugin Update Process

**Standard operating procedure for updating plugins in this marketplace**

---

## When to Update

Update plugin version when you:
- Add new commands, skills, or agents
- Modify existing command/skill behavior
- Fix bugs in plugin components
- Add or update documentation that affects usage

**Don't update for:**
- Experimental WIP changes
- Non-plugin files (root-level docs, etc.)
- Typo fixes in comments (unless user-facing)

---

## The Workflow

### Use `/update-plugin` Command

```bash
/update-plugin <plugin-name>

# Example:
/update-plugin meta
```

**The command will:**
1. Detect changes in plugin directory
2. Help categorize changes (Added/Changed/Fixed/Removed)
3. Update CHANGELOG.md
4. Bump version in plugin.json (semver)
5. Show diff and optionally commit

---

## Semver Guidelines

| Bump Type | When | Example |
|-----------|------|---------|
| **Patch** (0.3.2 → 0.3.3) | Bug fixes, docs, minor tweaks | Fixed truncation in /work output |
| **Minor** (0.3.2 → 0.4.0) | New features, commands, skills | Added /update-plugin command |
| **Major** (0.3.2 → 1.0.0) | Breaking changes, removed features | Removed deprecated /old-command |

**Rules:**
- New commands/skills = Minor
- New command features = Minor
- Bug fixes = Patch
- Breaking changes = Major (rare)

---

## Changelog Format

Follow [Keep a Changelog](https://keepachangelog.com/):

```markdown
## [0.4.0] - 2025-12-20

### Added
- **/update-plugin command**: Interactive workflow for version updates
  - Guides through change categorization and semver bumping
  - Explains plugin versioning context for testing

### Changed
- **work command**: Removed output limit to show all items
  - Changed from `exo ready | head -15` to `exo ready`

### Fixed
- **work command**: Fixed truncation error with >15 items

### Removed
- Nothing
```

**Focus on value**, not implementation details.

---

## Plugin Versioning & Context

**Critical concept:** Claude Code sessions cache plugin versions.

### How It Works

```
Session A (current):
  - Loads meta plugin v0.3.2 at startup
  - You edit commands, bump to v0.3.3
  - Session A still uses v0.3.2 (cached)
  - Sub-agents spawned in Session A use v0.3.2

Session B (new):
  - Fresh Claude Code instance
  - Loads meta plugin v0.3.3
  - Sees all your changes

Headless (recommended):
  - Each `claude ...` command is fresh session
  - Picks up latest version immediately
  - Best for testing after version bump
```

### Testing After Version Bump

**Always test with headless** to verify new version works:

```bash
# After bumping meta plugin to v0.3.3
claude --dangerously-skip-permissions --model haiku \
  "test the updated command"

# This gets fresh v0.3.3, not cached v0.3.2
```

**Why this matters:**
- Sub-agents won't see your changes (they use parent session's cache)
- Current session won't reload plugins mid-session
- Headless = clean slate = actual new version

---

## Manual Process (If Not Using Command)

If you need to update manually:

1. **Check current version:**
   ```bash
   cat plugins/<name>/.claude-plugin/plugin.json | grep version
   ```

2. **Decide semver bump** (see table above)

3. **Update CHANGELOG.md:**
   ```markdown
   ## [NEW_VERSION] - $(date +%Y-%m-%d)

   ### Changed
   - Description of change
   ```

4. **Update plugin.json:**
   ```json
   "version": "NEW_VERSION",
   ```

5. **Commit:**
   ```bash
   git add plugins/<name>/
   git commit -m "chore(<name>): brief description

   - List changes

   Version: OLD → NEW"
   ```

6. **Test with headless** to verify

---

## Continuous Improvement Integration

**Future enhancement**: The continuous-improvement skill should detect plugin edits and proactively suggest:

```
"I notice you modified meta/commands/work.md.
Should I run /update-plugin meta to document this change?"
```

**Current state**: Manual trigger only (run `/update-plugin` yourself)

**Blocker**: Proactive automation still needs wiring; run `/update-plugin` manually for now

---

## Checklist

Before committing plugin changes:

- [ ] Run `/update-plugin <plugin-name>`
- [ ] Categorize changes (Added/Changed/Fixed/Removed)
- [ ] Choose appropriate semver bump
- [ ] Verify CHANGELOG.md entry is clear
- [ ] Verify plugin.json version updated
- [ ] Test with headless Claude to confirm new version works
- [ ] Commit with descriptive message

---

## Related

- **Command**: `/update-plugin` (commands/update-plugin.md)
- **Testing**: `references/command-testing.md`
- **Semver**: https://semver.org/
- **Changelog format**: https://keepachangelog.com/

---

*Last updated: 2025-12-20*
