claude-cli-advanced-starter-pack 1.1.0 → 1.8.0

package/templates/hooks/token-usage-monitor.template.js

@@ -0,0 +1,193 @@
+/**
+ * Token Usage Monitor Hook
+ *
+ * Tracks cumulative token usage across the session.
+ * Auto-respawn warning at 90% of context window.
+ * Provides real-time token consumption feedback.
+ *
+ * Event: PostToolUse
+ *
+ * Configuration: Reads from .claude/config/hooks-config.json
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+// Default configuration
+const DEFAULT_CONFIG = {
+  context_limit: 200000,           // Estimated context window
+  warning_threshold: 0.75,         // Warn at 75%
+  critical_threshold: 0.90,        // Critical at 90%
+  auto_compact_suggestion: true,   // Suggest compaction at critical
+  session_timeout_ms: 300000,      // 5 minutes
+};
+
+// Paths
+const CONFIG_PATH = path.join(process.cwd(), '.claude', 'config', 'hooks-config.json');
+const STATE_PATH = path.join(process.cwd(), '.claude', 'config', 'token-usage-state.json');
+
+/**
+ * Load configuration
+ */
+function loadConfig() {
+  try {
+    if (fs.existsSync(CONFIG_PATH)) {
+      const config = JSON.parse(fs.readFileSync(CONFIG_PATH, 'utf8'));
+      return { ...DEFAULT_CONFIG, ...(config.token_usage || {}) };
+    }
+  } catch (e) {
+    // Use defaults
+  }
+  return DEFAULT_CONFIG;
+}
+
+/**
+ * Load state
+ */
+function loadState() {
+  try {
+    if (fs.existsSync(STATE_PATH)) {
+      return JSON.parse(fs.readFileSync(STATE_PATH, 'utf8'));
+    }
+  } catch (e) {
+    // Fresh state
+  }
+  return {
+    session_id: null,
+    session_start: null,
+    total_input_chars: 0,
+    total_output_chars: 0,
+    estimated_tokens: 0,
+    tool_calls: 0,
+    last_activity: null,
+    warnings_shown: 0,
+  };
+}
+
+/**
+ * Save state
+ */
+function saveState(state) {
+  try {
+    const dir = path.dirname(STATE_PATH);
+    if (!fs.existsSync(dir)) {
+      fs.mkdirSync(dir, { recursive: true });
+    }
+    fs.writeFileSync(STATE_PATH, JSON.stringify(state, null, 2), 'utf8');
+  } catch (e) {
+    // Silent
+  }
+}
+
+/**
+ * Estimate tokens from text (rough approximation)
+ */
+function estimateTokens(text) {
+  if (!text) return 0;
+  // Average ~4 characters per token for English text
+  return Math.ceil(text.length / 4);
+}
+
+/**
+ * Generate session ID
+ */
+function generateSessionId() {
+  return Date.now().toString(36) + Math.random().toString(36).substr(2, 5);
+}
+
+/**
+ * Format number with commas
+ */
+function formatNumber(num) {
+  return num.toLocaleString();
+}
+
+/**
+ * Main hook handler
+ */
+module.exports = async function tokenUsageMonitor(context) {
+  const approve = () => ({ continue: true });
+
+  try {
+    const config = loadConfig();
+    let state = loadState();
+    const now = Date.now();
+
+    // Check for new session
+    if (!state.session_start || (now - state.last_activity) > config.session_timeout_ms) {
+      state = {
+        session_id: generateSessionId(),
+        session_start: now,
+        total_input_chars: 0,
+        total_output_chars: 0,
+        estimated_tokens: 0,
+        tool_calls: 0,
+        last_activity: now,
+        warnings_shown: 0,
+      };
+    }
+
+    // Parse hook input
+    let inputChars = 0;
+    let outputChars = 0;
+
+    try {
+      const input = JSON.parse(process.env.CLAUDE_HOOK_INPUT || '{}');
+
+      // Count input characters
+      if (input.tool_input) {
+        const inputStr = typeof input.tool_input === 'string'
+          ? input.tool_input
+          : JSON.stringify(input.tool_input);
+        inputChars = inputStr.length;
+      }
+
+      // Count output characters
+      if (input.tool_output) {
+        const outputStr = typeof input.tool_output === 'string'
+          ? input.tool_output
+          : JSON.stringify(input.tool_output);
+        outputChars = outputStr.length;
+      }
+    } catch (e) {
+      // Skip counting on error
+    }
+
+    // Update totals
+    state.total_input_chars += inputChars;
+    state.total_output_chars += outputChars;
+    state.tool_calls++;
+    state.last_activity = now;
+
+    // Estimate tokens
+    const totalChars = state.total_input_chars + state.total_output_chars;
+    state.estimated_tokens = estimateTokens(totalChars);
+
+    // Calculate usage percentage
+    const usagePercent = state.estimated_tokens / config.context_limit;
+
+    // Check thresholds
+    if (usagePercent >= config.critical_threshold) {
+      if (state.warnings_shown < 3) { // Don't spam
+        console.log(`[token-usage-monitor] CRITICAL: ${(usagePercent * 100).toFixed(1)}% of context used`);
+        console.log(`[token-usage-monitor] Estimated tokens: ${formatNumber(state.estimated_tokens)}`);
+        if (config.auto_compact_suggestion) {
+          console.log('[token-usage-monitor] Consider using /context-audit or starting a new session');
+        }
+        state.warnings_shown++;
+      }
+    } else if (usagePercent >= config.warning_threshold) {
+      if (state.warnings_shown < 2) {
+        console.log(`[token-usage-monitor] WARNING: ${(usagePercent * 100).toFixed(1)}% of context used`);
+        state.warnings_shown++;
+      }
+    }
+
+    saveState(state);
+
+    return approve();
+  } catch (error) {
+    console.error(`[token-usage-monitor] Error: ${error.message}`);
+    return approve();
+  }
+};

package/templates/patterns/README.md

@@ -0,0 +1,129 @@
+# Agent Patterns Library
+
+Reusable patterns for Claude Code agent orchestration.
+
+## Quick Reference
+
+| Pattern | Use Case | Complexity |
+|---------|----------|------------|
+| [Two-Tier Query Pipeline](two-tier-query-pipeline.md) | Intent classification + execution | Medium |
+| [L1→L2 Orchestration](l1-l2-orchestration.md) | Master-worker parallel tasks | Medium |
+| [Multi-Phase Orchestration](multi-phase-orchestration.md) | Sequential phases with parallel tasks | High |
+
+## Choosing a Pattern
+
+### Simple Task Routing
+**Use: Two-Tier Query Pipeline**
+- User requests vary in type
+- Different handlers for different intents
+- Need confidence-based routing
+
+### Parallel Subtask Execution
+**Use: L1→L2 Orchestration**
+- Task decomposes into independent parts
+- Parallel execution improves speed
+- Need result aggregation
+
+### Complex Multi-Step Projects
+**Use: Multi-Phase Orchestration**
+- Work has natural phase boundaries
+- Validation needed between phases
+- Phases may have parallel subtasks
+
+## Pattern Combinations
+
+### Query → Orchestration
+
+```
+User Request
+     ↓
+┌─────────────────┐
+│ Query Pipeline  │  Classify intent
+└─────────────────┘
+     ↓
+┌─────────────────┐
+│ L1→L2 Pattern   │  Execute with specialists
+└─────────────────┘
+```
+
+### Phase → Orchestration
+
+```
+┌─────────────────────────────┐
+│     Phase 1: Discovery      │
+│  ┌───────────────────────┐  │
+│  │   L1→L2 Orchestration │  │  Parallel exploration
+│  └───────────────────────┘  │
+└─────────────────────────────┘
+            ↓
+┌─────────────────────────────┐
+│   Phase 2: Implementation   │
+│  ┌───────────────────────┐  │
+│  │   L1→L2 Orchestration │  │  Parallel coding
+│  └───────────────────────┘  │
+└─────────────────────────────┘
+```
+
+## Implementation Tips
+
+### 1. Start Simple
+Begin with the simplest pattern that solves your problem. Add complexity only when needed.
+
+### 2. Use Appropriate Models
+- L1 Orchestrators: Sonnet (needs reasoning)
+- L2 Search/Explore: Haiku (fast, cheap)
+- L2 Analysis/Generate: Sonnet (quality needed)
+
+### 3. Handle Failures Gracefully
+Always have fallback behavior when agents fail.
+
+### 4. Log Extensively
+Track agent launches, completions, and aggregations for debugging.
+
+### 5. Use Background Agents
+For long-running tasks, use `run_in_background: true` to avoid blocking.
+
+## Creating New Patterns
+
+When documenting a new pattern:
+
+1. **Overview**: What problem does it solve?
+2. **When to Use**: Clear use cases
+3. **Architecture**: Visual diagram
+4. **Implementation**: Code examples
+5. **Examples**: Real-world usage
+6. **Related Patterns**: Connections to other patterns
+
+## Pattern Template
+
+```markdown
+# Pattern Name
+
+Brief description.
+
+## Overview
+
+What this pattern does.
+
+## When to Use
+
+- Use case 1
+- Use case 2
+
+## Architecture
+
+[Diagram]
+
+## Implementation
+
+[Code]
+
+## Example
+
+[Complete example]
+
+## Related Patterns
+
+- Pattern A
+- Pattern B
+```

package/templates/patterns/l1-l2-orchestration.md

@@ -0,0 +1,189 @@
+# L1→L2 Orchestration Pattern
+
+Hierarchical agent coordination with parallel L2 spawning.
+
+## Overview
+
+A master-worker pattern where:
+- **L1 (Orchestrator)**: Decomposes task, coordinates workers, aggregates results
+- **L2 (Specialists)**: Execute specific subtasks in parallel
+
+## When to Use
+
+- Complex tasks that can be broken into independent subtasks
+- Parallel execution would improve speed
+- Subtasks require different specializations
+
+## Architecture
+
+```
+                    ┌─────────────────────┐
+                    │   L1 Orchestrator   │
+                    │   - Decompose task  │
+                    │   - Dispatch L2s    │
+                    │   - Aggregate       │
+                    └─────────────────────┘
+                             ↓
+        ┌────────────────────┼────────────────────┐
+        ↓                    ↓                    ↓
+┌───────────────┐    ┌───────────────┐    ┌───────────────┐
+│ L2 Specialist │    │ L2 Specialist │    │ L2 Specialist │
+│   (Search)    │    │   (Analyze)   │    │   (Document)  │
+└───────────────┘    └───────────────┘    └───────────────┘
+```
+
+## Implementation
+
+### L1 Orchestrator
+
+```typescript
+async function orchestrate(task: string) {
+  // Step 1: Decompose task into subtasks
+  const subtasks = await decomposeTask(task);
+
+  // Step 2: Identify dependencies
+  const { independent, dependent } = categorizeSubtasks(subtasks);
+
+  // Step 3: Launch independent L2 agents in parallel
+  const parallelResults = await launchParallelL2s(independent);
+
+  // Step 4: Launch dependent L2 agents sequentially
+  const sequentialResults = await launchSequentialL2s(dependent, parallelResults);
+
+  // Step 5: Aggregate results
+  return aggregateResults([...parallelResults, ...sequentialResults]);
+}
+```
+
+### L2 Launcher
+
+```typescript
+async function launchParallelL2s(subtasks: Subtask[]) {
+  // Launch all in single message for true parallelism
+  const agents = subtasks.map(subtask => ({
+    description: subtask.title,
+    prompt: subtask.prompt,
+    subagent_type: subtask.type,
+    run_in_background: true
+  }));
+
+  // All agents start simultaneously
+  const handles = await Promise.all(agents.map(a => Task(a)));
+
+  // Wait for all to complete
+  return Promise.all(handles.map(h => waitForAgent(h)));
+}
+```
+
+### Task Decomposition
+
+```typescript
+function decomposeTask(task: string): Subtask[] {
+  // Example: "Analyze and document the authentication system"
+
+  return [
+    {
+      id: 'search',
+      title: 'Find auth files',
+      prompt: 'Search for all authentication-related files',
+      type: 'Explore',
+      dependencies: []
+    },
+    {
+      id: 'analyze',
+      title: 'Analyze auth flow',
+      prompt: 'Analyze the authentication flow and security',
+      type: 'Plan',
+      dependencies: ['search']
+    },
+    {
+      id: 'document',
+      title: 'Generate docs',
+      prompt: 'Document the authentication system',
+      type: 'general-purpose',
+      dependencies: ['analyze']
+    }
+  ];
+}
+```
+
+### Result Aggregation
+
+```typescript
+function aggregateResults(results: AgentResult[]): FinalResult {
+  return {
+    summary: results.map(r => r.summary).join('\n\n'),
+    files: results.flatMap(r => r.files || []),
+    insights: results.flatMap(r => r.insights || []),
+    recommendations: prioritizeRecommendations(results)
+  };
+}
+```
+
+## Complete Example
+
+```typescript
+// Task: "Analyze the codebase for performance issues"
+
+// L1 Orchestrator breaks into:
+const subtasks = [
+  // Independent (run in parallel)
+  { id: 'bundle', type: 'Explore', prompt: 'Find bundle size issues' },
+  { id: 'queries', type: 'Explore', prompt: 'Find slow database queries' },
+  { id: 'renders', type: 'Explore', prompt: 'Find excessive re-renders' },
+
+  // Dependent (run after above complete)
+  { id: 'report', type: 'general-purpose', prompt: 'Generate performance report',
+    dependencies: ['bundle', 'queries', 'renders'] }
+];
+
+// Execution:
+// 1. L1 launches 3 Explore agents in parallel
+// 2. All 3 complete with findings
+// 3. L1 launches report agent with aggregated findings
+// 4. L1 returns final report
+```
+
+## Model Selection by Level
+
+| Level | Model | Reasoning |
+|-------|-------|-----------|
+| L1 | Sonnet | Needs to coordinate, decompose, aggregate |
+| L2 Search | Haiku | Simple file discovery |
+| L2 Analysis | Sonnet | Complex reasoning required |
+| L2 Generate | Sonnet | Quality output needed |
+
+## Error Handling
+
+```typescript
+async function orchestrateWithRecovery(task) {
+  const subtasks = await decomposeTask(task);
+  const results = [];
+
+  for (const subtask of subtasks) {
+    try {
+      const result = await executeSubtask(subtask);
+      results.push({ subtask, result, success: true });
+    } catch (error) {
+      // Log failure but continue with other subtasks
+      results.push({ subtask, error, success: false });
+    }
+  }
+
+  // Report partial success if some failed
+  const successful = results.filter(r => r.success);
+  const failed = results.filter(r => !r.success);
+
+  return {
+    results: aggregateResults(successful.map(r => r.result)),
+    failures: failed.map(f => ({ task: f.subtask.id, error: f.error })),
+    partial: failed.length > 0
+  };
+}
+```
+
+## Related Patterns
+
+- Two-Tier Query Pipeline
+- Multi-Phase Orchestration
+- Dependency Ordering