zhongwei/gh-linus-mcmanamey-unify-2-1-plugin
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
master
gh-linus-mcmanamey-unify-2-…/hooks
History
Zhongwei Li 506a828b22 Initial commit
2025-11-30 08:37:55 +08:00
..
combined-prompt-hook.py
Initial commit
2025-11-30 08:37:55 +08:00
orchestrator_interceptor.py
Initial commit
2025-11-30 08:37:55 +08:00
README.md
Initial commit
2025-11-30 08:37:55 +08:00
skill-activation-prompt.py
Initial commit
2025-11-30 08:37:55 +08:00

README.md

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:

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

  1. Verify configuration:

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

  2. Check executability:

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

  3. Test directly:

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

  4. 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:

  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 View Git Blame Copy Permalink