CCPM Hook Optimization Skill

This skill provides comprehensive guidance for optimizing Claude Code hooks used in CCPM (Claude Code Project Management) to ensure high performance, minimal token usage, and reliable execution.

Table of Contents

1. Hook System Overview
2. Performance Requirements
3. The Three Main Hooks
4. Optimization Strategies
5. Cached Agent Discovery
6. Token Optimization Techniques
7. Benchmarking & Profiling
8. Hook Development Workflow
9. Best Practices
10. Examples & Case Studies

---

Hook System Overview

What are Claude Code Hooks?

Claude Code hooks are event-based automation points that trigger Claude to perform intelligent actions at specific moments in the development workflow:

• UserPromptSubmit: Triggered when user sends a message
• PreToolUse: Triggered before file write/edit operations
• Stop: Triggered after Claude completes a response

CCPM's Three Main Hooks

Hook Execution Flow

User Message
    ↓
[UserPromptSubmit Hook]
    ↓ smart-agent-selector analyzes request
    ↓ Selects best agents (with caching)
    ↓ Injects agent invocation instructions
    ↓
Claude Executes (Agents run in parallel/sequence)
    ↓
File Write/Edit Request
    ↓
[PreToolUse Hook]
    ↓ tdd-enforcer checks for tests
    ↓ Blocks if missing (invokes tdd-orchestrator)
    ↓
File Created/Modified
    ↓
Response Complete
    ↓
[Stop Hook]
    ↓ quality-gate analyzes changes
    ↓ Invokes code-reviewer, security-auditor
    ↓
Complete

---

Performance Requirements

Target Metrics

Execution Time:

• UserPromptSubmit hook: <5 seconds (with caching: <2 seconds)
• PreToolUse hook: <1 second
• Stop hook: <5 seconds

Token Budget:

• Per hook: <5,000 tokens
• Combined overhead: <10,000 tokens per user message

Cache Performance:

• Cache hit rate: 85-95%
• Cached execution: <100ms (vs ~2,000ms uncached)
• Cache invalidation: 5 minutes TTL

Why These Targets Matter

User Experience Impact:
- <1s → Feels instant, no latency
- 1-5s → Acceptable delay
- >5s → Noticeable lag, frustrating

Token Budget Impact:
- <5,000 tokens per hook → Minimal overhead
- <10,000 tokens total → <5% of typical context window
- Well-optimized hooks → Enable more complex agent selection

---

The Three Main Hooks

1. Smart Agent Selector (UserPromptSubmit)

Purpose: Analyze user request and automatically invoke best agents

Original Version: 19,307 lines, ~4,826 tokens Optimized Version: 3,538 lines, ~884 tokens Improvement: 82% token reduction

Key Optimizations:

• Removed verbose explanations (inline comments instead)
• Simplified response format (JSON without markdown)
• Cached agent discovery
• Conditional logic (skip for simple docs questions)

Execution Flow:

User: "Add authentication with JWT"
    ↓
[smart-agent-selector]
    ↓ Task: Implementation
    ↓ Keywords: auth, jwt, security
    ↓ Tech Stack: backend (detected)
    ↓ Score: tdd-orchestrator (85), backend-architect (95), security-auditor (90)
    ↓ Decision: Sequential execution
    ↓
Result: {
  "shouldInvokeAgents": true,
  "selectedAgents": [...],
  "execution": "sequential",
  "injectedInstructions": "..."
}

2. TDD Enforcer (PreToolUse)

Purpose: Ensure test files exist before writing production code

Original Version: 4,853 lines, ~1,213 tokens Optimized Version: 2,477 lines, ~619 tokens Improvement: 49% token reduction

Key Optimizations:

• Hardcoded test file patterns (no dynamic detection)
• Single-pass file existence check
• Simplified JSON response
• Skip expensive type inference

Decision Matrix:

Is test file?              → APPROVE (writing tests first)
Tests exist for module?    → APPROVE (tests are ready)
Config/docs file?         → APPROVE (no TDD needed)
Production code no tests? → BLOCK (invoke tdd-orchestrator)
User bypass?              → APPROVE (with warning)

3. Quality Gate (Stop Hook)

Purpose: Automatically invoke code review and security audit

Original Version: 4,482 lines, ~1,120 tokens Optimized Version: 2,747 lines, ~687 tokens Improvement: 39% token reduction

Key Optimizations:

• Reduced scoring complexity
• Fixed agent list (not dynamic)
• Simplified file type detection
• Removed verbose explanations

Decision Rules: ``

...