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

package/templates/patterns/multi-phase-orchestration.md

@@ -0,0 +1,258 @@
+# Multi-Phase Orchestration Pattern
+
+Sequential phase execution with parallel agents within phases.
+
+## Overview
+
+Organizes work into distinct phases where:
+- Phases execute sequentially (each depends on previous)
+- Tasks within a phase can run in parallel
+- Validation gates between phases ensure quality
+
+## When to Use
+
+- Large projects with natural phase boundaries
+- Work that must be done in a specific order
+- Need for validation between major steps
+
+## Architecture
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                         L1 Controller                        │
+└─────────────────────────────────────────────────────────────┘
+                              ↓
+┌─────────────────────────────────────────────────────────────┐
+│                    Phase 1: Discovery                        │
+│  ┌──────────┐  ┌──────────┐  ┌──────────┐                  │
+│  │ Agent A  │  │ Agent B  │  │ Agent C  │  (parallel)      │
+│  └──────────┘  └──────────┘  └──────────┘                  │
+│                   ↓ Validation Gate                         │
+└─────────────────────────────────────────────────────────────┘
+                              ↓
+┌─────────────────────────────────────────────────────────────┐
+│                   Phase 2: Implementation                    │
+│  ┌──────────┐  ┌──────────┐                                │
+│  │ Agent D  │  │ Agent E  │  (parallel)                    │
+│  └──────────┘  └──────────┘                                │
+│                   ↓ Validation Gate                         │
+└─────────────────────────────────────────────────────────────┘
+                              ↓
+┌─────────────────────────────────────────────────────────────┐
+│                      Phase 3: Testing                        │
+│  ┌──────────┐                                               │
+│  │ Agent F  │  (sequential - needs all results)            │
+│  └──────────┘                                               │
+└─────────────────────────────────────────────────────────────┘
+```
+
+## Implementation
+
+### Phase Controller
+
+```typescript
+interface Phase {
+  id: string;
+  name: string;
+  tasks: Task[];
+  validation: ValidationGate;
+  parallel: boolean;
+}
+
+async function executePhases(phases: Phase[]): Promise<PhaseResults> {
+  const results: PhaseResult[] = [];
+  let context = {}; // Accumulates data across phases
+
+  for (const phase of phases) {
+    console.log(`Starting Phase ${phase.id}: ${phase.name}`);
+
+    // Execute phase tasks
+    const phaseResult = phase.parallel
+      ? await executeParallel(phase.tasks, context)
+      : await executeSequential(phase.tasks, context);
+
+    // Run validation gate
+    const validation = await phase.validation.check(phaseResult);
+
+    if (!validation.passed) {
+      return {
+        completed: results,
+        failed: phase,
+        reason: validation.reason,
+        context
+      };
+    }
+
+    // Update context with phase results
+    context = { ...context, [phase.id]: phaseResult };
+    results.push({ phase, result: phaseResult, validation });
+  }
+
+  return { completed: results, context };
+}
+```
+
+### Parallel Task Execution
+
+```typescript
+async function executeParallel(tasks: Task[], context: Context) {
+  // Prepare prompts with context
+  const preparedTasks = tasks.map(task => ({
+    ...task,
+    prompt: injectContext(task.prompt, context)
+  }));
+
+  // Launch all in parallel
+  const agents = preparedTasks.map(task => Task({
+    description: task.title,
+    prompt: task.prompt,
+    subagent_type: task.type,
+    run_in_background: true
+  }));
+
+  const handles = await Promise.all(agents);
+
+  // Wait for all to complete
+  return Promise.all(handles.map(waitForCompletion));
+}
+```
+
+### Validation Gates
+
+```typescript
+const validationGates = {
+  discovery: {
+    async check(results) {
+      // Verify all files were found
+      const allFilesFound = results.every(r => r.files?.length > 0);
+
+      // Verify no critical errors
+      const noErrors = results.every(r => !r.error);
+
+      return {
+        passed: allFilesFound && noErrors,
+        reason: !allFilesFound ? 'Missing required files' :
+                !noErrors ? 'Errors during discovery' : null
+      };
+    }
+  },
+
+  implementation: {
+    async check(results) {
+      // Run tests on new code
+      const testResult = await runTests();
+
+      // Check for type errors
+      const typeCheck = await runTypeCheck();
+
+      return {
+        passed: testResult.passing && typeCheck.clean,
+        reason: !testResult.passing ? `${testResult.failed} tests failed` :
+                !typeCheck.clean ? `${typeCheck.errors} type errors` : null
+      };
+    }
+  }
+};
+```
+
+## Complete Example
+
+```typescript
+// Project: Implement new feature with testing
+
+const phases: Phase[] = [
+  {
+    id: 'discovery',
+    name: 'Codebase Discovery',
+    parallel: true,
+    tasks: [
+      { title: 'Find related components', type: 'Explore', ... },
+      { title: 'Find API endpoints', type: 'Explore', ... },
+      { title: 'Find existing tests', type: 'Explore', ... }
+    ],
+    validation: validationGates.discovery
+  },
+  {
+    id: 'planning',
+    name: 'Implementation Planning',
+    parallel: false, // Sequential - needs discovery results
+    tasks: [
+      { title: 'Design component structure', type: 'Plan', ... },
+      { title: 'Design API changes', type: 'Plan', ... }
+    ],
+    validation: validationGates.planning
+  },
+  {
+    id: 'implementation',
+    name: 'Code Implementation',
+    parallel: true, // Independent components
+    tasks: [
+      { title: 'Implement component', type: 'general-purpose', ... },
+      { title: 'Implement API', type: 'general-purpose', ... }
+    ],
+    validation: validationGates.implementation
+  },
+  {
+    id: 'testing',
+    name: 'Testing & Validation',
+    parallel: false,
+    tasks: [
+      { title: 'Write unit tests', type: 'general-purpose', ... },
+      { title: 'Run E2E tests', type: 'Bash', ... }
+    ],
+    validation: validationGates.testing
+  }
+];
+
+// Execute
+const result = await executePhases(phases);
+```
+
+## State Management
+
+### PROGRESS.json Integration
+
+```json
+{
+  "current_phase": 2,
+  "phases": [
+    {
+      "id": "discovery",
+      "status": "complete",
+      "tasks": [...],
+      "validation": { "passed": true }
+    },
+    {
+      "id": "implementation",
+      "status": "in_progress",
+      "tasks": [...],
+      "validation": null
+    }
+  ]
+}
+```
+
+### Checkpoint Recovery
+
+```typescript
+async function resumeFromCheckpoint(progressPath: string) {
+  const progress = JSON.parse(await readFile(progressPath));
+
+  // Find incomplete phase
+  const incompleteIndex = progress.phases.findIndex(
+    p => p.status !== 'complete'
+  );
+
+  // Resume from that phase
+  return executePhases(
+    progress.phases.slice(incompleteIndex),
+    progress.context
+  );
+}
+```
+
+## Related Patterns
+
+- L1→L2 Orchestration
+- Phase Validation Gates
+- Two-Tier Query Pipeline

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) |