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

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

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