8

unnamed

Leo Miranda edited this page 2026-01-27 21:58:35 +00:00

Table of Contents

• Sprint 3: Hooks Implementation
• Sprint Goals
• Issues
• Dependencies
• Technical Architecture
• Hook Implementation Pattern
• Hook Event Types for This Sprint
• Acceptance Criteria
• All Hooks
• Lessons Applied

Type: Change Proposal Implementation Version: V5.2.0 Status: In Progress Date: 2026-01-27 Origin: V5.2.0 Plugin Enhancements Proposal Sprint: Sprint 3 Milestone: Sprint 3 - Hooks

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	Priority	Complexity
#225	git-flow	Commit enforcement hook	High	Medium
#226	git-flow	Branch name validation hook	High	Medium
#227	clarity-assist	Auto-suggest hook	Medium	Medium
#228	data-platform	Schema diff detection hook	Medium	Complex
#229	contract-validator	SessionStart auto-validate hook	High	Medium
#230	contract-validator	Breaking change detection	High	Complex

Dependencies

#229 (SessionStart auto-validate) --> #230 (Breaking change detection)

#225, #226, #227, #228 are independent and can be done in parallel

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)	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

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

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