diff --git a/Change-V5.2.0%3A-Plugin-Enhancements-Proposal-%28Sprint-3-Hooks%29.md b/Change-V5.2.0%3A-Plugin-Enhancements-Proposal-%28Sprint-3-Hooks%29.md new file mode 100644 index 0000000..b33a85c --- /dev/null +++ b/Change-V5.2.0%3A-Plugin-Enhancements-Proposal-%28Sprint-3-Hooks%29.md @@ -0,0 +1,130 @@ +> **Type:** Change Proposal Implementation +> **Version:** V5.2.0 +> **Status:** In Progress +> **Date:** 2026-01-27 +> **Origin:** [V5.2.0 Plugin Enhancements Proposal](Change-V5.2.0%3A-Plugin-Enhancements-Proposal) +> **Sprint:** Sprint 3 + +# Sprint 3: Hooks Implementation + +This sprint focuses on implementing 6 foundational hooks across 4 plugins. These hooks provide enforcement, validation, and detection capabilities that other features may depend on. + +## Sprint Goals + +1. Implement commit message enforcement for conventional commits +2. Implement branch naming validation +3. Add intelligent prompt vagueness detection +4. Add schema change detection for data pipelines +5. Add smart contract validation on session start +6. Implement breaking change detection for plugin interfaces + +## Issues + +| # | Plugin | Title | Type | Priority | +|---|--------|-------|------|----------| +| TBD | git-flow | Commit enforcement hook | Feature | High | +| TBD | git-flow | Branch name validation hook | Feature | High | +| TBD | clarity-assist | Auto-suggest hook | Feature | Medium | +| TBD | data-platform | Schema diff detection hook | Feature | Medium | +| TBD | contract-validator | SessionStart auto-validate hook | Feature | High | +| TBD | contract-validator | Breaking change detection | Feature | High | + +*Issue numbers will be updated after creation* + +## Technical Architecture + +### Hook Implementation Pattern + +**CRITICAL LESSON LEARNED:** All hooks must be defined in `hooks/hooks.json`, NOT inline in plugin.json. + +``` +plugins/{name}/ + hooks/ + hooks.json <-- Hook definitions (auto-discovered) + *.sh <-- Shell scripts for command-type hooks +``` + +### Hook Event Types for This Sprint + +| Hook | Event | Tool Filter | Behavior | +|------|-------|-------------|----------| +| Commit enforcement | `PreToolUse` | Bash (git commit) | Block if invalid format | +| Branch validation | `PreToolUse` | Bash (git checkout -b, git switch -c) | Block if invalid name | +| Auto-suggest | `UserPromptSubmit` | N/A | Suggest /clarity-assist | +| Schema diff | `PostToolUse` | Edit (schema files) | Warn on breaking changes | +| Auto-validate | `SessionStart` | N/A | Run if files changed | +| Breaking change | `PostToolUse` | Edit (plugin interfaces) | Warn on breaks | + +### hooks.json Structure + +```json +{ + "hooks": { + "PreToolUse": [ + { + "type": "command", + "command": "${CLAUDE_PLUGIN_ROOT}/hooks/validate-commit.sh", + "tool_name": "Bash" + } + ], + "SessionStart": [ + { + "type": "command", + "command": "${CLAUDE_PLUGIN_ROOT}/hooks/session-check.sh" + } + ] + } +} +``` + +## Dependencies + +``` + +------------------+ + | contract-validator| + | SessionStart hook | + +--------+---------+ + | + v + +------------------+ + | contract-validator| + | Breaking change | + +------------------+ + ++---------------+ +----------------+ +| git-flow | | git-flow | +| Commit hook | | Branch hook | ++---------------+ +----------------+ + (independent) (independent) + ++---------------+ +----------------+ +| clarity-assist| | data-platform | +| Auto-suggest | | Schema diff | ++---------------+ +----------------+ + (independent) (independent) +``` + +The contract-validator hooks have a dependency: Breaking change detection works in conjunction with the SessionStart auto-validate hook. + +## Acceptance Criteria + +### All Hooks +- [ ] Hook defined in `hooks/hooks.json` (NOT plugin.json) +- [ ] Shell script tested independently +- [ ] Hook fires on correct event +- [ ] Non-blocking behavior where appropriate (warnings vs errors) +- [ ] Documentation updated in plugin README + +### Specific Criteria +- **Commit hook:** Validates `type(scope): description` format +- **Branch hook:** Validates `type/description` format, lowercase, max 50 chars +- **Auto-suggest:** Detects vague prompts, suggests but does not block +- **Schema diff:** Detects column removals, type changes in SQL/YAML +- **Auto-validate:** Only runs when plugin files have git changes since last check +- **Breaking change:** Detects interface changes that break existing consumers + +## Lessons Applied + +1. **Plugin Hooks Must Be in Separate File** - All hooks in `hooks/hooks.json` +2. **Test Assertions Match API** - Write tests alongside implementation +3. **Each Issue Gets Feature Branch** - Follow `feat/{issue-number}-description` pattern