/update-plugins

description: Audit and sync plugin.json registrations with actual disk contents. Detects missing or stale skills, commands, agents, hooks.
usage: /update-plugins [plugin-name] [--dry-run] [--fix]

Update Plugin Registrations

Audit plugin.json files against actual disk contents and fix registration gaps.

Arguments

• `plugin-name` - Optional: specific plugin to audit (default: all plugins)
• `--dry-run` - Show discrepancies without making changes (default behavior)
• `--fix` - Automatically update plugin.json files to add/remove registrations

What It Does

Phase 1: Registration Audit

1. Scans each plugin directory for commands, skills, agents, hooks on disk 2. Compares with plugin.json registrations 3. Reports discrepancies: missing registrations, stale entries 4. Optionally fixes by updating plugin.json files with proper sorting

Phase 1b: Structure Validation (Doctor Check)

Runs `validate_plugin.py` on each affected plugin to verify:

• plugin.json schema matches official Claude Code spec
• Skill frontmatter uses valid fields (`effort`, `context`, `shell`, etc.)
• Agent frontmatter uses valid fields (`maxTurns`, `isolation`, etc.)
• Hook event types are recognized (`PreToolUse`, `PostToolUse`, etc.)
• All referenced paths exist on disk

python3 plugins/abstract/scripts/validate_plugin.py plugins/<plugin>

Phase 1c: Modernization Audit

Checks all hooks for outdated patterns against the Claude Code SDK spec.

1. **Static check** (always): Runs `check_hook_modernization.py` to detect invalid decision values, deprecated fields, and missing error handling 2. **Tome research** (default, skip with `--skip-research`): Dispatches `tome:code-search` to verify patterns against current community practices

# Static check only
python3 scripts/check_hook_modernization.py

# JSON output for programmatic use
python3 scripts/check_hook_modernization.py --json

See `update-plugins/modules/phase1c-modernization.md` for pattern reference and fix instructions.

Phase 2: Plugin Quality Review

Triggers `/plugin-review --tier branch` on affected plugins. Runs quick quality gates (test, lint, typecheck, registration, structure validation) on changed plugins and side-effect checks on related plugins.

Phase 2-4 (On-Demand Modules)

These modules contain full procedural details: format templates, commands, TodoWrite naming conventions, and auto-issue creation procedures.

• See `update-plugins/modules/phase2-performance.md` for

skill-review and performance analysis

• See `update-plugins/modules/phase3-meta-eval.md` for

recursive quality validation

• See `update-plugins/modules/phase4-queue.md` for knowledge

queue promotion checks

Workflow

Execute the Python script with the provided arguments:

# Audit all plugins (dry run - show discrepancies only)
python3 plugins/sanctum/scripts/update_plugin_registrations.py --dry-run

# Audit specific plugin
python3 plugins/sanctum/scripts/update_plugin_registrations.py parseltongue --dry-run

# Fix all plugins (update plugin.json files)
python3 plugins/sanctum/scripts/update_plugin_registrations.py --fix

# Fix specific plugin
python3 plugins/sanctum/scripts/update_plugin_registrations.py abstract --fix

Command Flags

| Flag | Purpose | |------|---------| | `--dry-run` | Show discrepancies without fixing (default) | | `--fix` | Update plugin.json files | | `--skip-modernization` | Skip Phase 1c modernization audit | | `--skip-research` | Skip tome research (keep static check) | | `--skip-meta-eval` | Skip meta-evaluation check | | `--skip-queue` | Skip knowledge queue check | | `--no-auto-issues` | Don't auto-create GitHub issues |

Prerequisites

This command requires the sanctum plugin's Python scripts. Before running, verify the script exists:

# Check if running in night-market repo
if [[ -f "plugins/sanctum/scripts/update_plugin_registrations.py" ]]; then
  echo "Sanctum scripts available - command will work"
else
  echo "ERROR: This command only works in the claude-night-market repository"
  echo "The update_plugin_registrations.py script is not available in this project."
  exit 1
fi

**For non-night-market projects**: This command is night-market-specific. Use `claude plugin update <plugin>@<marketplace>` to update individual plugins.

Script Features

• Smart filtering: Excludes module directories,

__pycache__, test files, __init__.py

• Nested path handling: Detects and reports stale nested registrations
• Alphabetical sorting: Maintains consistent ordering in plugin.json
• Safe by default: Dry-run mode unless --fix is specified
• Enriched output: Orphaned modules show inline descriptions from file content

Discrepancy Types

| Type | Meaning | Action | |------|---------|--------| | Missing | File on disk, not in plugin.json | Add registration | | Stale | In plugin.json, not on disk | Remove or investigate | | Path mismatch | Wrong path format | Correct path |

When To Use

• After adding new commands, skills, agents, or hooks
• During version bumps to ensure completeness
• As part of PR preparation (`/pr` workflow)
• When capabilities-reference.md seems out of sync
• Periodically (weekly/monthly) to catch performance

degradation early

• After major refactors to ensure no regressions in skill

stability

When NOT To Use

• Simple changes that don't need the full workflow
• Work already completed through another sanctum command

Improvement Integration Loop

Phases 1-4 create a continuous feedback loop: registration audit surfaces gaps, performance analysis identifies degradation, meta-evaluation enforces quality, and queue checks prevent knowledge loss. See the phase modules for details.

Integration

This command complements:

• `/plugin-review` - Tiered quality review (invoked as

Phase 2)

• `/update-docs` - Updates documentation after plugin

changes

• `/update-version` - Bumps versions after significant

changes

• `/validate-p