Initial commit
This commit is contained in:
Zhongwei Li
472
hooks/README.md
Normal file
472
hooks/README.md
Normal file
@@ -0,0 +1,472 @@
|
||||
# Unify 2.1 Plugin Hooks
|
||||
|
||||
Intelligent prompt interception system with dual-stage hook pipeline for automatic skill activation and orchestrator routing.
|
||||
|
||||
## Overview
|
||||
|
||||
This plugin provides **three hooks** that work together to enhance Claude Code's capabilities:
|
||||
|
||||
1. **skill-activation-prompt** - Detects domain-specific needs and recommends skills
|
||||
2. **orchestrator-interceptor** - Analyzes complexity and routes to multi-agent orchestration
|
||||
3. **combined-prompt-hook** - Chains both hooks seamlessly
|
||||
|
||||
## Architecture
|
||||
|
||||
```
|
||||
┌──────────────────────────────────────────────────────────────┐
|
||||
│ USER PROMPT SUBMITTED │
|
||||
└────────────────┬─────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌────────────────────────────────────┐
|
||||
│ combined-prompt-hook.py │ ← Single entry point
|
||||
│ (Hook Orchestration Layer) │
|
||||
└────────────────┬───────────────────┘
|
||||
│
|
||||
┌────────────┴────────────┐
|
||||
│ │
|
||||
▼ ▼
|
||||
┌───────────────────┐ ┌──────────────────────┐
|
||||
│ STAGE 1: SKILLS │ │ STAGE 2: ORCHESTRATOR│
|
||||
│ skill-activation │ │ orchestrator- │
|
||||
│ -prompt.py │ │ interceptor.py │
|
||||
└────────┬──────────┘ └──────────┬───────────┘
|
||||
│ │
|
||||
▼ ▼
|
||||
┌─────────────┐ ┌──────────────┐
|
||||
│ Detects │ │ Analyzes │
|
||||
│ domain │ │ complexity │
|
||||
│ skills │ │ & routing │
|
||||
│ needed │ │ │
|
||||
└─────────────┘ └──────────────┘
|
||||
│ │
|
||||
└────────────┬─────────────┘
|
||||
│
|
||||
▼
|
||||
┌──────────────────────┐
|
||||
│ COMBINED CONTEXT │
|
||||
│ injected into │
|
||||
│ Claude's conversation│
|
||||
└──────────────────────┘
|
||||
```
|
||||
|
||||
## Hook 1: Skill Activation
|
||||
|
||||
**File**: `skill-activation-prompt.py`
|
||||
|
||||
**Purpose**: Load domain-specific knowledge before execution
|
||||
|
||||
**Detection Rules** (from `../skills/skill-rules.json`):
|
||||
- Keywords: `["pyspark", "schema", "bronze", "silver", "gold", "etl", "transform"]`
|
||||
- Intent patterns: `["generate.*pyspark", "create.*table", "transform.*data"]`
|
||||
|
||||
**Example Output**:
|
||||
```
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
🎯 SKILL ACTIVATION CHECK
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
|
||||
⚠️ CRITICAL SKILLS (REQUIRED):
|
||||
→ schema-reference
|
||||
|
||||
📚 RECOMMENDED SKILLS:
|
||||
→ pyspark-patterns
|
||||
|
||||
ACTION: Use Skill tool BEFORE responding
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
```
|
||||
|
||||
## Hook 2: Orchestrator Interceptor
|
||||
|
||||
**File**: `orchestrator_interceptor.py`
|
||||
|
||||
**Purpose**: Analyze complexity and route to optimal execution strategy
|
||||
|
||||
**Classification Rules**:
|
||||
|
||||
| Pattern | Reason | Complexity | Action |
|
||||
|---------|--------|------------|--------|
|
||||
| "what is", "explain", <20 words | Simple query | simple_query | Skip orchestration |
|
||||
| Contains "bronze", "silver", "gold" (2+) | Cross-layer work | high_complexity | Multi-agent (6-8) |
|
||||
| "all", "across", "entire", "multiple" | Broad scope | complex_task | Multi-agent (4-6) |
|
||||
| "linting", "formatting" + "all"/"entire" | Quality sweep | high_complexity | Multi-agent (6-8) |
|
||||
| "implement", "create", "build" + >10 words | Implementation | moderate_task | Single agent or 2-3 |
|
||||
|
||||
**Cost Estimates**:
|
||||
- Simple query: ~500 tokens, $0.002
|
||||
- Moderate task: ~6,000 tokens, $0.018
|
||||
- Complex task: ~17,000 tokens, $0.051
|
||||
- High complexity: ~43,000 tokens, $0.129
|
||||
|
||||
**Example Output**:
|
||||
```
|
||||
<orchestrator-analysis-required>
|
||||
ORCHESTRATOR INTERCEPTION ACTIVE
|
||||
|
||||
BEFORE responding to the user, you MUST:
|
||||
|
||||
1. Launch the master-orchestrator agent
|
||||
2. USER PROMPT: "Fix linting across bronze, silver, and gold layers"
|
||||
3. Classification: Cross Layer Work (High Complexity)
|
||||
4. COST ESTIMATION:
|
||||
- Total estimated: ~43,000 tokens
|
||||
- Approximate cost: $0.129 USD
|
||||
|
||||
Present execution plan with user approval options.
|
||||
</orchestrator-analysis-required>
|
||||
```
|
||||
|
||||
## Hook 3: Combined Hook
|
||||
|
||||
**File**: `combined-prompt-hook.py`
|
||||
|
||||
**Purpose**: Chain both hooks seamlessly in pure Python
|
||||
|
||||
**Logic**:
|
||||
1. Read prompt once from stdin
|
||||
2. Pass to skill-activation-prompt.py → Get skill recommendations (JSON)
|
||||
3. Pass to orchestrator_interceptor.py → Get complexity analysis (JSON)
|
||||
4. Parse and merge both JSON outputs
|
||||
5. Return combined JSON context
|
||||
|
||||
**Benefits**:
|
||||
- No bash/jq dependencies
|
||||
- Better error handling
|
||||
- Type-safe with proper JSON parsing
|
||||
- Easier to debug and maintain
|
||||
|
||||
## Installation
|
||||
|
||||
### Option 1: Plugin-Level (Recommended)
|
||||
|
||||
Update `.claude/settings.json` to use the plugin hooks:
|
||||
|
||||
```json
|
||||
{
|
||||
"hooks": {
|
||||
"user-prompt-submit": ".claude/plugins/repos/unify_2_1/hooks/combined-prompt-hook.py"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Option 2: Global Level
|
||||
|
||||
Copy hooks to global hooks directory:
|
||||
|
||||
```bash
|
||||
cp -r .claude/plugins/repos/unify_2_1/hooks/* ~/.claude/hooks/
|
||||
```
|
||||
|
||||
Then configure in `~/.claude/settings.json`:
|
||||
|
||||
```json
|
||||
{
|
||||
"hooks": {
|
||||
"user-prompt-submit": ".claude/hooks/combined-prompt-hook.py"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Restart Claude Code** after configuration changes.
|
||||
|
||||
## Configuration
|
||||
|
||||
### Adjust Skill Detection
|
||||
|
||||
Edit `../skills/skill-rules.json`:
|
||||
|
||||
```json
|
||||
{
|
||||
"skills": {
|
||||
"schema-reference": {
|
||||
"priority": "critical",
|
||||
"promptTriggers": {
|
||||
"keywords": ["schema", "table", "column"],
|
||||
"intentPatterns": ["generate.*table", "create.*etl"]
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Adjust Orchestrator Classification
|
||||
|
||||
Edit `orchestrator_interceptor.py`:
|
||||
|
||||
```python
|
||||
# Add custom patterns
|
||||
def should_orchestrate(prompt: str) -> tuple[bool, str, str]:
|
||||
# Your custom logic here
|
||||
if "custom_pattern" in prompt.lower():
|
||||
return True, "custom_reason", "high_complexity"
|
||||
```
|
||||
|
||||
### Adjust Cost Estimates
|
||||
|
||||
Edit `orchestrator_interceptor.py`:
|
||||
|
||||
```python
|
||||
token_estimates = {
|
||||
"moderate_task": {
|
||||
"orchestrator_analysis": 1000,
|
||||
"agent_execution": 5000,
|
||||
"total_estimated": 6000,
|
||||
"cost_usd": 0.018
|
||||
},
|
||||
# Adjust as needed
|
||||
}
|
||||
```
|
||||
|
||||
## Monitoring & Logs
|
||||
|
||||
### Log Location
|
||||
|
||||
All orchestrator decisions logged to:
|
||||
```
|
||||
~/.claude/hook_logs/orchestrator_hook.log
|
||||
```
|
||||
|
||||
### View Logs
|
||||
|
||||
```bash
|
||||
# Real-time monitoring
|
||||
tail -f ~/.claude/hook_logs/orchestrator_hook.log
|
||||
|
||||
# Recent entries
|
||||
tail -50 ~/.claude/hook_logs/orchestrator_hook.log
|
||||
|
||||
# Search classifications
|
||||
grep "Classified as" ~/.claude/hook_logs/orchestrator_hook.log
|
||||
|
||||
# View cost estimates
|
||||
grep "Cost estimate" ~/.claude/hook_logs/orchestrator_hook.log
|
||||
```
|
||||
|
||||
### Log Format
|
||||
|
||||
```
|
||||
2025-11-10 23:00:44 | INFO | ================================================================================
|
||||
2025-11-10 23:00:44 | INFO | Hook triggered - Session: abc123
|
||||
2025-11-10 23:00:44 | INFO | CWD: /workspaces/unify_2_1_dm_niche_rms_build_d10
|
||||
2025-11-10 23:00:44 | INFO | Prompt: Fix all linting errors across bronze, silver, and gold layers
|
||||
2025-11-10 23:00:44 | INFO | Classified as CROSS-LAYER WORK (3 layers)
|
||||
2025-11-10 23:00:44 | INFO | Decision: ORCHESTRATE
|
||||
2025-11-10 23:00:44 | INFO | Reason: cross_layer_work
|
||||
2025-11-10 23:00:44 | INFO | Complexity: high_complexity
|
||||
2025-11-10 23:00:44 | INFO | Cost estimate: $0.129 USD (~43,000 tokens)
|
||||
2025-11-10 23:00:44 | INFO | Hook completed successfully
|
||||
2025-11-10 23:00:44 | INFO | ================================================================================
|
||||
```
|
||||
|
||||
### Log Rotation
|
||||
|
||||
- **Rotation**: 10 MB
|
||||
- **Retention**: 30 days
|
||||
- **Location**: `~/.claude/hook_logs/orchestrator_hook.log`
|
||||
|
||||
## Examples
|
||||
|
||||
### Example 1: Simple Domain Query
|
||||
|
||||
**Prompt**: "What is TableUtilities?"
|
||||
|
||||
**Skill Hook**:
|
||||
```
|
||||
📚 RECOMMENDED SKILLS: → pyspark-patterns
|
||||
```
|
||||
|
||||
**Orchestrator Hook**:
|
||||
```
|
||||
<simple-query-detected>
|
||||
Handle directly without orchestration overhead.
|
||||
</simple-query-detected>
|
||||
```
|
||||
|
||||
**Result**: Skill loaded for accurate answer, no orchestration overhead
|
||||
|
||||
### Example 2: Complex Multi-Layer Task
|
||||
|
||||
**Prompt**: "Fix linting across bronze, silver, and gold layers"
|
||||
|
||||
**Skill Hook**:
|
||||
```
|
||||
📚 RECOMMENDED SKILLS:
|
||||
→ project-architecture
|
||||
→ pyspark-patterns
|
||||
```
|
||||
|
||||
**Orchestrator Hook**:
|
||||
```
|
||||
Classification: Cross-layer work (High complexity)
|
||||
Cost: $0.129 USD (~43,000 tokens)
|
||||
Strategy: Multi-agent (6-8 agents in parallel)
|
||||
```
|
||||
|
||||
**Result**: Architecture loaded + Multi-agent orchestration plan presented
|
||||
|
||||
### Example 3: PySpark ETL Implementation
|
||||
|
||||
**Prompt**: "Generate gold table g_x_mg_vehicle_stats from silver_cms and silver_fvms"
|
||||
|
||||
**Skill Hook**:
|
||||
```
|
||||
⚠️ CRITICAL SKILLS:
|
||||
→ schema-reference (exact schemas)
|
||||
📚 RECOMMENDED SKILLS:
|
||||
→ pyspark-patterns (TableUtilities methods)
|
||||
```
|
||||
|
||||
**Orchestrator Hook**:
|
||||
```
|
||||
Classification: Implementation task (Moderate)
|
||||
Cost: $0.018 USD (~6,000 tokens)
|
||||
Strategy: Single pyspark-developer agent
|
||||
```
|
||||
|
||||
**Result**: Schemas + patterns loaded, orchestrator plans single-agent execution
|
||||
|
||||
## Testing
|
||||
|
||||
### Test Skill Hook Only
|
||||
|
||||
```bash
|
||||
echo '{"prompt":"Generate PySpark table from bronze_cms","session_id":"test","cwd":"/workspaces"}' | \
|
||||
python3 .claude/plugins/repos/unify_2_1/hooks/skill-activation-prompt.py | jq
|
||||
```
|
||||
|
||||
### Test Orchestrator Hook Only
|
||||
|
||||
```bash
|
||||
echo '{"session_id":"test","cwd":"/workspaces","prompt":"Fix linting across all layers"}' | \
|
||||
python3 .claude/plugins/repos/unify_2_1/hooks/orchestrator_interceptor.py | jq
|
||||
```
|
||||
|
||||
### Test Combined Hook
|
||||
|
||||
```bash
|
||||
echo '{"session_id":"test","cwd":"/workspaces","prompt":"Generate gold table from silver data"}' | \
|
||||
python3 .claude/plugins/repos/unify_2_1/hooks/combined-prompt-hook.py | jq
|
||||
```
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Hook Not Running
|
||||
|
||||
1. **Verify configuration**:
|
||||
```bash
|
||||
cat .claude/settings.json | grep -A 2 hooks
|
||||
```
|
||||
|
||||
2. **Check executability**:
|
||||
```bash
|
||||
ls -l .claude/plugins/repos/unify_2_1/hooks/*.{sh,py}
|
||||
```
|
||||
|
||||
3. **Test directly**:
|
||||
```bash
|
||||
echo '{"prompt":"test"}' | python3 .claude/plugins/repos/unify_2_1/hooks/orchestrator_interceptor.py
|
||||
```
|
||||
|
||||
4. **Restart Claude Code** (required for settings changes)
|
||||
|
||||
### Dependencies Missing
|
||||
|
||||
```bash
|
||||
# Check loguru
|
||||
python3 -c "import loguru; print(f'loguru {loguru.__version__}')"
|
||||
|
||||
# Install if needed
|
||||
pip install loguru
|
||||
|
||||
# Check jq
|
||||
which jq || sudo apt-get install -y jq
|
||||
```
|
||||
|
||||
### Hook Errors
|
||||
|
||||
Hooks are fail-safe - errors don't block prompts:
|
||||
- Error logged to `orchestrator_hook.log`
|
||||
- Prompt passes through unchanged
|
||||
- Claude responds normally
|
||||
|
||||
Check logs:
|
||||
```bash
|
||||
tail -50 ~/.claude/hook_logs/orchestrator_hook.log | grep ERROR
|
||||
```
|
||||
|
||||
## Performance Impact
|
||||
|
||||
### Minimal Overhead
|
||||
|
||||
- **Skill hook**: <50ms (keyword matching, local file read)
|
||||
- **Orchestrator hook**: <100ms (regex patterns, logging)
|
||||
- **Total**: ~150ms added to each prompt
|
||||
|
||||
### When Hooks Skip
|
||||
|
||||
- Simple queries: Both hooks run but skip actions (~100ms)
|
||||
- Domain queries: Skill loads, orchestrator skips (~120ms)
|
||||
- Complex tasks: Both hooks activate fully (~150ms)
|
||||
|
||||
### Fail-Safe Design
|
||||
|
||||
- Hooks never block prompts
|
||||
- Errors are caught and logged
|
||||
- Default action: allow prompt through unchanged
|
||||
|
||||
## Integration with Plugin
|
||||
|
||||
### Plugin Components Using Hooks
|
||||
|
||||
- **16 Agents** - All benefit from orchestrator routing
|
||||
- **30 Commands** - Some trigger orchestrator explicitly (`/orchestrate`)
|
||||
- **9 Skills** - Activated automatically by skill hook
|
||||
|
||||
### Workflow
|
||||
|
||||
```
|
||||
User types prompt
|
||||
↓
|
||||
Combined hook analyzes
|
||||
↓
|
||||
Skills loaded (if needed)
|
||||
↓
|
||||
Orchestrator invoked (if complex)
|
||||
↓
|
||||
Specialized agents launched (if approved)
|
||||
↓
|
||||
Results aggregated
|
||||
↓
|
||||
User receives comprehensive response
|
||||
```
|
||||
|
||||
## Files
|
||||
|
||||
```
|
||||
.claude/plugins/repos/unify_2_1/hooks/
|
||||
├── README.md # This file
|
||||
├── combined-prompt-hook.py # Main entry point (chains hooks in Python)
|
||||
├── orchestrator_interceptor.py # Complexity analysis + routing
|
||||
└── skill-activation-prompt.py # Skill detection (Python implementation)
|
||||
```
|
||||
|
||||
## Version History
|
||||
|
||||
**1.0.0** (2025-11-10)
|
||||
- Initial release
|
||||
- Dual-stage hook pipeline
|
||||
- Skill activation + orchestrator routing
|
||||
- Cost estimation
|
||||
- Comprehensive logging
|
||||
|
||||
## Support
|
||||
|
||||
For issues:
|
||||
1. Check logs: `~/.claude/hook_logs/orchestrator_hook.log`
|
||||
2. Test hooks individually (see Testing section)
|
||||
3. Verify dependencies (Python, loguru)
|
||||
4. Review this README
|
||||
|
||||
## License
|
||||
|
||||
MIT License (same as parent plugin)
|
||||
Reference in New Issue
Block a user