cpv-add-hook

cpv-add-hook

Overview

Adds a new hook entry to a plugin's hooks/hooks.json. The scaffold is idempotent — re-running with the same event+command is a no-op. The new hook command MUST be cross-platform: prefer Python or Node.js delegation. Bash-only constructs (set -euo pipefail, [[ ]], $(<file), process substitution, brace expansion) will trigger validate_hook MAJOR findings. Loaded dynamically via cpv-the-skills-menu, reached via the Create → Add hook menu branch.

Prerequisites

• uv on PATH
• Target plugin path with .claude-plugin/plugin.json
• A valid hook event name (see "Valid event names" below)
• A cross-platform command string (delegate to Python/Node, NOT bash-isms)

Instructions

1. Pick a valid hook event name from the canonical list.
2. Write the command as a Python or Node delegation. add_component.py writes the command verbatim — it does NOT inspect or reject bash-only constructs at write time — so a bash-only command lands in hooks/hooks.json and is caught only later by validate_hook/validate_plugin --strict (step 5) as a MAJOR. Use Python/Node delegation up front to pass that re-validation.
3. Run the underlying add_component.py --type hook invocation.
4. The script creates hooks/hooks.json if missing or merges into the existing file.
5. Re-validate via cpv-plugin-validation-skill to confirm cross-platform compliance.
6. NEVER write runtime state to ${CLAUDE_PLUGIN_ROOT} (lost on every plugin update). Use ${CLAUDE_PLUGIN_DATA} instead.

Copy this checklist and track your progress:

• Event name validated against canonical list
• Command uses Python/Node delegation (no bash-isms)
• add_component.py --type hook executed
• hooks/hooks.json updated or created
• validate_plugin --strict re-run

Output

• A new entry in hooks/hooks.json keyed by event name.
• Identical entries (same event + same command) are skipped — re-runs are no-ops.
• The file is created if missing; existing entries are preserved.