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

package/templates/patterns/two-tier-query-pipeline.md

@@ -0,0 +1,192 @@
+# Two-Tier Query Pipeline Pattern
+
+Intent classification followed by specialized execution.
+
+## Overview
+
+A two-tier architecture that separates:
+1. **Tier 1**: Intent classification (what kind of request is this?)
+2. **Tier 2**: Specialized execution (handle based on intent)
+
+## When to Use
+
+- Multiple types of requests need different handling
+- Request routing is complex
+- You want to add new handlers without changing core logic
+
+## Architecture
+
+```
+User Request
+     ↓
+┌──────────────────────┐
+│   Tier 1: Classifier │  (Fast, lightweight)
+│   - Parse intent     │
+│   - Extract entities │
+│   - Route to handler │
+└──────────────────────┘
+     ↓
+┌──────────────────────┐
+│   Tier 2: Handler    │  (Specialized, thorough)
+│   - Execute task     │
+│   - Return result    │
+└──────────────────────┘
+```
+
+## Implementation
+
+### Tier 1: Classifier
+
+```typescript
+interface ClassificationResult {
+  intent: string;
+  confidence: number;
+  entities: Record<string, string>;
+  handler: string;
+}
+
+async function classifyIntent(request: string): Promise<ClassificationResult> {
+  // Pattern matching for common intents
+  const patterns = {
+    'create': /create|add|new|make/i,
+    'read': /get|show|list|find|search/i,
+    'update': /update|edit|modify|change/i,
+    'delete': /delete|remove|destroy/i,
+    'analyze': /analyze|check|review|audit/i
+  };
+
+  for (const [intent, pattern] of Object.entries(patterns)) {
+    if (pattern.test(request)) {
+      return {
+        intent,
+        confidence: 0.8,
+        entities: extractEntities(request),
+        handler: `${intent}Handler`
+      };
+    }
+  }
+
+  return { intent: 'unknown', confidence: 0.5, entities: {}, handler: 'fallbackHandler' };
+}
+```
+
+### Tier 2: Handlers
+
+```typescript
+const handlers = {
+  createHandler: async (entities) => {
+    // Launch specialized creation agent
+    return Task({
+      description: `Create ${entities.type}`,
+      prompt: `Create a new ${entities.type} with: ${JSON.stringify(entities)}`,
+      subagent_type: 'general-purpose'
+    });
+  },
+
+  readHandler: async (entities) => {
+    // Launch exploration agent
+    return Task({
+      description: `Find ${entities.target}`,
+      prompt: `Search for ${entities.target} in the codebase`,
+      subagent_type: 'Explore'
+    });
+  },
+
+  analyzeHandler: async (entities) => {
+    // Launch analysis agent
+    return Task({
+      description: `Analyze ${entities.scope}`,
+      prompt: `Perform analysis on ${entities.scope}`,
+      subagent_type: 'Plan'
+    });
+  },
+
+  fallbackHandler: async (entities) => {
+    // Ask for clarification
+    return { needsClarification: true, entities };
+  }
+};
+```
+
+### Pipeline Execution
+
+```typescript
+async function executeQuery(request: string) {
+  // Tier 1: Classify
+  const classification = await classifyIntent(request);
+
+  if (classification.confidence < 0.7) {
+    // Low confidence - ask for clarification
+    return askForClarification(classification);
+  }
+
+  // Tier 2: Execute
+  const handler = handlers[classification.handler];
+  if (!handler) {
+    throw new Error(`Unknown handler: ${classification.handler}`);
+  }
+
+  return handler(classification.entities);
+}
+```
+
+## Example: Command Router
+
+```typescript
+// User asks: "Create a new hook for validating file writes"
+
+// Tier 1 Classification:
+{
+  intent: 'create',
+  confidence: 0.9,
+  entities: {
+    type: 'hook',
+    target: 'file writes',
+    purpose: 'validation'
+  },
+  handler: 'createHandler'
+}
+
+// Tier 2 Execution:
+// Launches create-hook skill with extracted parameters
+```
+
+## Benefits
+
+1. **Separation of Concerns**: Classification logic is separate from execution
+2. **Extensibility**: Add new handlers without changing classifier
+3. **Testability**: Each tier can be tested independently
+4. **Confidence Handling**: Low-confidence routes can be handled specially
+
+## Variations
+
+### Multi-Intent
+
+Handle requests with multiple intents:
+
+```typescript
+// "Create a user and send them a welcome email"
+// Intent 1: create user
+// Intent 2: send email
+```
+
+### Fallback Chain
+
+Multiple classifiers with fallback:
+
+```typescript
+const classifiers = [patternClassifier, mlClassifier, heuristicClassifier];
+
+async function classifyWithFallback(request) {
+  for (const classifier of classifiers) {
+    const result = await classifier(request);
+    if (result.confidence > 0.7) return result;
+  }
+  return { intent: 'unknown', confidence: 0 };
+}
+```
+
+## Related Patterns
+
+- L1→L2 Orchestration
+- Multi-Phase Orchestration

package/templates/scripts/README.md

@@ -0,0 +1,109 @@
+# Utility Scripts Library
+
+Standalone scripts for deployment validation, logging analysis, and project health monitoring.
+
+## Available Scripts
+
+| Script | Purpose | Language |
+|--------|---------|----------|
+| [validate-deployment.js](validate-deployment.js) | Pre-deployment environment validation | Node.js |
+| [poll-deployment-status.js](poll-deployment-status.js) | Poll deployment until complete | Node.js |
+| [roadmap-scanner.js](roadmap-scanner.js) | Multi-roadmap progress dashboard | Node.js |
+| [analyze-delegation-log.js](analyze-delegation-log.js) | Model usage analysis from JSONL logs | Node.js |
+| [autonomous-decision-logger.js](autonomous-decision-logger.js) | JSONL audit trail for agent decisions | Node.js |
+| [phase-validation-gates.js](phase-validation-gates.js) | 5-gate validation before phase transitions | Node.js |
+| [git-history-analyzer.py](git-history-analyzer.py) | Security audit for sensitive data in git | Python |
+
+## Installation
+
+Copy scripts to your project:
+
+```bash
+# Copy all scripts
+cp -r templates/scripts/ .claude/scripts/
+
+# Or install via ccasp
+ccasp install-scripts
+```
+
+## Usage
+
+### Pre-Deployment Validation
+
+```bash
+# Validate Railway environment
+node .claude/scripts/validate-deployment.js --platform railway
+
+# Validate Cloudflare Pages
+node .claude/scripts/validate-deployment.js --platform cloudflare
+```
+
+### Deployment Polling
+
+```bash
+# Poll Railway deployment until complete
+node .claude/scripts/poll-deployment-status.js \
+  --platform railway \
+  --project-id YOUR_PROJECT_ID \
+  --timeout 300
+
+# Poll Cloudflare Pages deployment
+node .claude/scripts/poll-deployment-status.js \
+  --platform cloudflare \
+  --project-name your-project
+```
+
+### Roadmap Scanning
+
+```bash
+# Scan all roadmaps in current directory
+node .claude/scripts/roadmap-scanner.js
+
+# Generate JSON report
+node .claude/scripts/roadmap-scanner.js --output json
+```
+
+### Log Analysis
+
+```bash
+# Analyze delegation log for model usage
+node .claude/scripts/analyze-delegation-log.js \
+  ~/.claude/logs/delegation.jsonl
+
+# Generate cost estimate
+node .claude/scripts/analyze-delegation-log.js \
+  ~/.claude/logs/delegation.jsonl --cost-estimate
+```
+
+### Git History Audit
+
+```bash
+# Check for sensitive data in git history
+python .claude/scripts/git-history-analyzer.py
+
+# Check specific patterns
+python .claude/scripts/git-history-analyzer.py \
+  --patterns "password|secret|api.key"
+```
+
+## Integration with Claude Code
+
+These scripts can be invoked via Claude Code commands:
+
+```markdown
+<!-- .claude/commands/validate-deploy.md -->
+Run the deployment validation script:
+\`\`\`bash
+node .claude/scripts/validate-deployment.js --platform {{platform}}
+\`\`\`
+```
+
+## Environment Variables
+
+Some scripts require environment variables:
+
+| Variable | Used By | Description |
+|----------|---------|-------------|
+| `RAILWAY_API_TOKEN` | validate-deployment.js | Railway API access |
+| `CLOUDFLARE_API_TOKEN` | validate-deployment.js | Cloudflare API access |
+| `GITHUB_TOKEN` | git-history-analyzer.py | GitHub API (optional) |

package/templates/scripts/analyze-delegation-log.js

@@ -0,0 +1,299 @@
+#!/usr/bin/env node
+/**
+ * Analyze Delegation Log
+ *
+ * Analyzes Claude Code delegation logs to understand model usage,
+ * token consumption, and agent patterns.
+ *
+ * Usage:
+ *   node analyze-delegation-log.js ~/.claude/logs/delegation.jsonl
+ *   node analyze-delegation-log.js log.jsonl --cost-estimate
+ *   node analyze-delegation-log.js log.jsonl --output json
+ */
+
+import { readFileSync, existsSync } from 'fs';
+
+// Approximate costs per 1M tokens (as of 2025)
+const MODEL_COSTS = {
+  'claude-opus-4-5': { input: 15.00, output: 75.00 },
+  'claude-sonnet-4': { input: 3.00, output: 15.00 },
+  'claude-haiku': { input: 0.25, output: 1.25 },
+  'default': { input: 3.00, output: 15.00 },
+};
+
+class DelegationAnalyzer {
+  constructor(logPath, options = {}) {
+    this.logPath = logPath;
+    this.options = options;
+    this.entries = [];
+    this.analysis = {
+      models: {},
+      agents: {},
+      tools: {},
+      sessions: {},
+      timeline: [],
+    };
+  }
+
+  async analyze() {
+    console.log(`\n📊 Analyzing delegation log: ${this.logPath}\n`);
+
+    if (!existsSync(this.logPath)) {
+      console.error(`Error: File not found: ${this.logPath}`);
+      process.exit(1);
+    }
+
+    await this.parseLog();
+    await this.computeMetrics();
+
+    if (this.options.output === 'json') {
+      this.outputJson();
+    } else {
+      this.outputText();
+    }
+  }
+
+  async parseLog() {
+    const content = readFileSync(this.logPath, 'utf8');
+    const lines = content.split('\n').filter(line => line.trim());
+
+    for (const line of lines) {
+      try {
+        const entry = JSON.parse(line);
+        this.entries.push(entry);
+      } catch (e) {
+        // Skip invalid lines
+      }
+    }
+
+    console.log(`Parsed ${this.entries.length} log entries\n`);
+  }
+
+  async computeMetrics() {
+    for (const entry of this.entries) {
+      // Track by model
+      const model = entry.model || 'unknown';
+      if (!this.analysis.models[model]) {
+        this.analysis.models[model] = {
+          calls: 0,
+          inputTokens: 0,
+          outputTokens: 0,
+          errors: 0,
+          avgLatency: 0,
+          latencies: [],
+        };
+      }
+
+      const modelStats = this.analysis.models[model];
+      modelStats.calls++;
+      modelStats.inputTokens += entry.inputTokens || 0;
+      modelStats.outputTokens += entry.outputTokens || 0;
+      if (entry.error) modelStats.errors++;
+      if (entry.latencyMs) modelStats.latencies.push(entry.latencyMs);
+
+      // Track by agent type
+      const agentType = entry.agentType || entry.subagentType || 'main';
+      if (!this.analysis.agents[agentType]) {
+        this.analysis.agents[agentType] = {
+          invocations: 0,
+          totalTokens: 0,
+          avgTokensPerCall: 0,
+        };
+      }
+
+      const agentStats = this.analysis.agents[agentType];
+      agentStats.invocations++;
+      agentStats.totalTokens += (entry.inputTokens || 0) + (entry.outputTokens || 0);
+
+      // Track by tool
+      if (entry.tool) {
+        if (!this.analysis.tools[entry.tool]) {
+          this.analysis.tools[entry.tool] = { calls: 0, errors: 0 };
+        }
+        this.analysis.tools[entry.tool].calls++;
+        if (entry.error) this.analysis.tools[entry.tool].errors++;
+      }
+
+      // Track by session
+      const sessionId = entry.sessionId || 'default';
+      if (!this.analysis.sessions[sessionId]) {
+        this.analysis.sessions[sessionId] = {
+          calls: 0,
+          tokens: 0,
+          start: entry.timestamp,
+          end: entry.timestamp,
+        };
+      }
+
+      const session = this.analysis.sessions[sessionId];
+      session.calls++;
+      session.tokens += (entry.inputTokens || 0) + (entry.outputTokens || 0);
+      if (entry.timestamp > session.end) session.end = entry.timestamp;
+    }
+
+    // Compute averages
+    for (const model of Object.keys(this.analysis.models)) {
+      const stats = this.analysis.models[model];
+      if (stats.latencies.length > 0) {
+        stats.avgLatency = Math.round(
+          stats.latencies.reduce((a, b) => a + b, 0) / stats.latencies.length
+        );
+      }
+      delete stats.latencies;
+    }
+
+    for (const agent of Object.keys(this.analysis.agents)) {
+      const stats = this.analysis.agents[agent];
+      stats.avgTokensPerCall = Math.round(stats.totalTokens / stats.invocations);
+    }
+  }
+
+  estimateCost() {
+    let totalCost = 0;
+    const breakdown = {};
+
+    for (const [model, stats] of Object.entries(this.analysis.models)) {
+      const costs = MODEL_COSTS[model] || MODEL_COSTS['default'];
+      const inputCost = (stats.inputTokens / 1_000_000) * costs.input;
+      const outputCost = (stats.outputTokens / 1_000_000) * costs.output;
+      const modelCost = inputCost + outputCost;
+
+      breakdown[model] = {
+        inputCost: inputCost.toFixed(4),
+        outputCost: outputCost.toFixed(4),
+        totalCost: modelCost.toFixed(4),
+      };
+
+      totalCost += modelCost;
+    }
+
+    return { breakdown, totalCost: totalCost.toFixed(4) };
+  }
+
+  outputText() {
+    console.log('='.repeat(70));
+    console.log('                    DELEGATION LOG ANALYSIS');
+    console.log('='.repeat(70));
+
+    // Model usage
+    console.log('\n📊 Model Usage\n');
+    console.log('Model                      Calls     Input Tokens    Output Tokens    Errors');
+    console.log('-'.repeat(70));
+
+    for (const [model, stats] of Object.entries(this.analysis.models)) {
+      const modelName = model.padEnd(24);
+      const calls = stats.calls.toString().padStart(6);
+      const input = stats.inputTokens.toLocaleString().padStart(15);
+      const output = stats.outputTokens.toLocaleString().padStart(16);
+      const errors = stats.errors.toString().padStart(8);
+      console.log(`${modelName}${calls}${input}${output}${errors}`);
+    }
+
+    // Agent usage
+    console.log('\n🤖 Agent Types\n');
+    console.log('Agent Type              Invocations    Total Tokens    Avg Tokens/Call');
+    console.log('-'.repeat(70));
+
+    for (const [agent, stats] of Object.entries(this.analysis.agents)) {
+      const agentName = agent.padEnd(22);
+      const invocations = stats.invocations.toString().padStart(12);
+      const tokens = stats.totalTokens.toLocaleString().padStart(15);
+      const avg = stats.avgTokensPerCall.toLocaleString().padStart(17);
+      console.log(`${agentName}${invocations}${tokens}${avg}`);
+    }
+
+    // Tool usage (top 10)
+    const toolEntries = Object.entries(this.analysis.tools)
+      .sort((a, b) => b[1].calls - a[1].calls)
+      .slice(0, 10);
+
+    if (toolEntries.length > 0) {
+      console.log('\n🔧 Top 10 Tools\n');
+      console.log('Tool                           Calls    Errors');
+      console.log('-'.repeat(50));
+
+      for (const [tool, stats] of toolEntries) {
+        const toolName = tool.padEnd(30);
+        const calls = stats.calls.toString().padStart(6);
+        const errors = stats.errors.toString().padStart(9);
+        console.log(`${toolName}${calls}${errors}`);
+      }
+    }
+
+    // Cost estimate
+    if (this.options.costEstimate) {
+      const cost = this.estimateCost();
+
+      console.log('\n💰 Cost Estimate\n');
+      console.log('Model                       Input Cost    Output Cost    Total Cost');
+      console.log('-'.repeat(70));
+
+      for (const [model, costs] of Object.entries(cost.breakdown)) {
+        const modelName = model.padEnd(26);
+        const input = `$${costs.inputCost}`.padStart(12);
+        const output = `$${costs.outputCost}`.padStart(14);
+        const total = `$${costs.totalCost}`.padStart(13);
+        console.log(`${modelName}${input}${output}${total}`);
+      }
+
+      console.log('-'.repeat(70));
+      console.log(`${'TOTAL'.padEnd(26)}${''.padStart(26)}$${cost.totalCost}`.padStart(13));
+    }
+
+    // Summary
+    const totalCalls = Object.values(this.analysis.models)
+      .reduce((acc, m) => acc + m.calls, 0);
+    const totalTokens = Object.values(this.analysis.models)
+      .reduce((acc, m) => acc + m.inputTokens + m.outputTokens, 0);
+    const totalErrors = Object.values(this.analysis.models)
+      .reduce((acc, m) => acc + m.errors, 0);
+
+    console.log('\n' + '='.repeat(70));
+    console.log('SUMMARY');
+    console.log('='.repeat(70));
+    console.log(`\n   Total API Calls: ${totalCalls.toLocaleString()}`);
+    console.log(`   Total Tokens:    ${totalTokens.toLocaleString()}`);
+    console.log(`   Error Rate:      ${((totalErrors / totalCalls) * 100).toFixed(2)}%`);
+    console.log(`   Sessions:        ${Object.keys(this.analysis.sessions).length}`);
+    console.log('\n' + '='.repeat(70) + '\n');
+  }
+
+  outputJson() {
+    const output = {
+      analyzedAt: new Date().toISOString(),
+      logPath: this.logPath,
+      totalEntries: this.entries.length,
+      analysis: this.analysis,
+    };
+
+    if (this.options.costEstimate) {
+      output.costEstimate = this.estimateCost();
+    }
+
+    console.log(JSON.stringify(output, null, 2));
+  }
+}
+
+// CLI entry point
+async function main() {
+  const args = process.argv.slice(2);
+
+  if (args.length === 0 || args[0].startsWith('--')) {
+    console.error('Usage: node analyze-delegation-log.js <log-file> [options]');
+    console.error('Options:');
+    console.error('  --cost-estimate    Include cost estimate');
+    console.error('  --output json      Output as JSON');
+    process.exit(1);
+  }
+
+  const logPath = args[0];
+  const options = {
+    costEstimate: args.includes('--cost-estimate'),
+    output: args.includes('--output') ? args[args.indexOf('--output') + 1] : 'text',
+  };
+
+  const analyzer = new DelegationAnalyzer(logPath, options);
+  await analyzer.analyze();
+}
+
+main().catch(console.error);