zhongwei/gh-linus-mcmanamey-unify-2-1-plugin

Files

Zhongwei Li 506a828b22 Initial commit

2025-11-30 08:37:55 +08:00

14 KiB

Raw Blame History

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:

skill-activation-prompt - Detects domain-specific needs and recommends skills
orchestrator-interceptor - Analyzes complexity and routes to multi-agent orchestration
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:

Read prompt once from stdin
Pass to skill-activation-prompt.py → Get skill recommendations (JSON)
Pass to orchestrator_interceptor.py → Get complexity analysis (JSON)
Parse and merge both JSON outputs
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:

{
  "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:

cp -r .claude/plugins/repos/unify_2_1/hooks/* ~/.claude/hooks/

Then configure in ~/.claude/settings.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:

{
  "skills": {
    "schema-reference": {
      "priority": "critical",
      "promptTriggers": {
        "keywords": ["schema", "table", "column"],
        "intentPatterns": ["generate.*table", "create.*etl"]
      }
    }
  }
}

Adjust Orchestrator Classification

Edit orchestrator_interceptor.py:

# 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:

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

# 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

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

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

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

Verify configuration:

cat .claude/settings.json | grep -A 2 hooks

Check executability:

ls -l .claude/plugins/repos/unify_2_1/hooks/*.{sh,py}

Test directly:

echo '{"prompt":"test"}' | python3 .claude/plugins/repos/unify_2_1/hooks/orchestrator_interceptor.py

Restart Claude Code (required for settings changes)

Dependencies Missing

# 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:

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:

Check logs: ~/.claude/hook_logs/orchestrator_hook.log
Test hooks individually (see Testing section)
Verify dependencies (Python, loguru)
Review this README

License

MIT License (same as parent plugin)

14 KiB Raw Blame History

Unify 2.1 Plugin Hooks

Overview

Architecture

Hook 1: Skill Activation

Hook 2: Orchestrator Interceptor

Hook 3: Combined Hook

Installation

Option 1: Plugin-Level (Recommended)

Option 2: Global Level

Configuration

Adjust Skill Detection

Adjust Orchestrator Classification

Adjust Cost Estimates

Monitoring & Logs

Log Location

View Logs

Log Format

Log Rotation

Examples

Example 1: Simple Domain Query

Example 2: Complex Multi-Layer Task

Example 3: PySpark ETL Implementation

Testing

Test Skill Hook Only

Test Orchestrator Hook Only

Test Combined Hook

Troubleshooting

Hook Not Running

Dependencies Missing

Hook Errors

Performance Impact

Minimal Overhead

When Hooks Skip

Fail-Safe Design

Integration with Plugin

Plugin Components Using Hooks

Workflow

Files

Version History

Support

License

14 KiB

Raw Blame History