Merge experimental/v4.0-meta-orchestration into main

Author: GeneAI

.claude/commands/cache.md

@@ -0,0 +1,88 @@
+Manage the hybrid caching system for LLM cost savings.
+
+## Cache Architecture
+
+The Empathy Framework uses a hybrid cache:
+- **Hash Cache**: Exact match on prompt hash (fast, precise)
+- **Semantic Cache**: Similarity-based matching (handles variations)
+- **Dependency-aware**: Invalidates when source files change
+
+## Commands
+
+### 1. View Cache Statistics
+```bash
+empathy cache stats
+```
+
+Shows:
+- Total entries
+- Hit rate (target: 70%+)
+- Size on disk
+- Oldest/newest entry
+
+### 2. Analyze Cache Effectiveness
+```bash
+empathy cache analyze
+```
+
+Shows:
+- Hit rate by workflow type
+- Most frequently cached queries
+- Cache miss patterns
+- Estimated cost savings
+
+### 3. Clear Cache
+```bash
+# Clear all
+empathy cache clear
+
+# Clear specific workflow
+empathy cache clear --workflow code-review
+
+# Clear entries older than N days
+empathy cache clear --older-than 7d
+```
+
+### 4. Warm Cache
+```bash
+# Pre-populate cache for common queries
+empathy cache warm --workflows code-review,bug-predict
+```
+
+### 5. Configure Cache
+In `empathy.config.yml`:
+```yaml
+cache:
+  enabled: true
+  type: "hybrid"          # hash, semantic, or hybrid
+  max_size_mb: 100        # Maximum cache size
+  ttl_hours: 24           # Time-to-live for entries
+  similarity_threshold: 0.85  # For semantic matching
+```
+
+## Cache Performance Targets
+
+| Metric | Target | Action if Below |
+|--------|--------|-----------------|
+| Hit Rate | >70% | Increase TTL, check query patterns |
+| Avg Latency | <50ms | Check disk I/O, reduce cache size |
+| Size | <100MB | Prune old entries |
+
+## Monitoring
+
+```bash
+# Real-time cache monitoring
+empathy cache monitor
+
+# Export cache metrics
+empathy cache export-metrics --format json
+```
+
+## Output
+
+Provide cache health summary:
+- Hit Rate: XX% (target: 70%+)
+- Entries: X
+- Size: X MB / 100 MB limit
+- Estimated savings: $X.XX
+- Recommendation: [OK / Needs attention]

.claude/commands/cost-report.md

@@ -0,0 +1,64 @@
+Analyze LLM API costs and show savings from intelligent tier routing.
+
+## Leverages Existing Features
+
+The Empathy Framework has powerful cost tracking built-in:
+- `empathy telemetry show` - Recent API calls with costs
+- `empathy telemetry savings` - Savings analysis vs premium baseline
+- `CostTracker` - Automatic cost logging per request
+
+## Execution Steps
+
+### 1. Show Recent Usage
+```bash
+empathy telemetry show --limit 50
+```
+
+### 2. Calculate Savings
+```bash
+empathy telemetry savings --days 30
+```
+
+### 3. Analyze by Workflow
+```bash
+# If available, show cost breakdown by workflow type
+empathy telemetry breakdown 2>/dev/null || echo "Breakdown not available"
+```
+
+### 4. Check Cache Effectiveness
+```bash
+empathy cache stats 2>/dev/null || echo "Cache stats: check .empathy/cache/"
+```
+
+## Analysis to Provide
+
+After running the commands, analyze and report:
+
+### Cost Summary
+| Metric | Value |
+|--------|-------|
+| Total Spend (30d) | $X.XX |
+| Baseline (if all premium) | $X.XX |
+| **Your Savings** | $X.XX (XX%) |
+| Cache Savings | $X.XX |
+
+### Tier Distribution
+Show percentage of calls by tier:
+- CHEAP (Haiku): XX% - outlines, summaries
+- CAPABLE (Sonnet): XX% - code review, generation
+- PREMIUM (Opus): XX% - complex analysis
+
+### Optimization Recommendations
+
+Based on the data, suggest:
+1. **Under-utilizing cheap tier?** - Some tasks could use Haiku
+2. **High cache miss rate?** - Adjust cache TTL or size
+3. **Expensive workflows?** - Identify cost hotspots
+4. **Cost trending up?** - Alert on unusual patterns
+
+### Cost Projection
+- Daily average: $X.XX
+- Projected monthly: $X.XX
+- At current rate, daily limit ($10) reached in: X days
+
+Keep output concise with actionable insights.

.claude/commands/create-agent.md

@@ -0,0 +1,77 @@
+# Create Custom Agent - Socratic Guide
+
+You are helping the user create a custom AI agent for the Empathy Framework. Use the AskUserQuestion tool to gather requirements through a guided conversation.
+
+## Step 1: Understand the Purpose
+
+First, ask the user what they want their agent to do:
+
+Use AskUserQuestion with:
+- Question: "What should this agent do?"
+- Header: "Purpose"
+- Options:
+  - "Analyze code" - Review and analyze source code for issues or patterns
+  - "Generate content" - Create tests, documentation, or other content
+  - "Review & validate" - Check work for quality, security, or correctness
+  - "Transform data" - Convert, migrate, or restructure code/data
+
+## Step 2: Determine Specialization
+
+Based on their answer, ask about specific focus:
+
+Use AskUserQuestion with:
+- Question: "What specific area should this agent focus on?"
+- Header: "Focus Area"
+- Options vary by purpose (e.g., for "Analyze code"):
+  - "Security vulnerabilities"
+  - "Performance issues"
+  - "Code quality & style"
+  - "Architecture & design"
+
+## Step 3: Select Model Tier
+
+Use AskUserQuestion with:
+- Question: "What quality/cost balance do you need?"
+- Header: "Model Tier"
+- Options:
+  - "Cheap (Recommended)" - Fast & low-cost ($0.001-0.01), good for simple analysis
+  - "Capable" - Balanced ($0.01-0.05), good for most development tasks
+  - "Premium" - Highest quality ($0.05-0.20), for complex reasoning
+
+## Step 4: Define Success Criteria
+
+Use AskUserQuestion with:
+- Question: "How will you measure success?"
+- Header: "Success"
+- Options:
+  - "Issues found & reported" - Agent finds and documents problems
+  - "Content generated" - Agent produces requested output
+  - "Validation passed" - Agent confirms quality/correctness
+  - "Recommendations provided" - Agent suggests improvements
+
+## Step 5: Generate the Agent Spec
+
+After gathering all answers, generate the agent specification:
+
+```json
+{
+  "name": "[Generated from purpose + focus]",
+  "role": "[Description based on answers]",
+  "tier": "[Selected tier]",
+  "base_template": "generic",
+  "success_criteria": "[Selected criteria]",
+  "tools": []
+}
+```
+
+Then tell the user:
+1. Show the generated spec in a code block
+2. Offer to save it: `empathy meta-workflow create-agent -q --name "X" --role "Y" --tier "Z" -o agent-spec.json`
+3. Explain how to use it in a team: `empathy meta-workflow create-team`
+
+## Important
+
+- Use AskUserQuestion for EACH step - don't ask multiple questions at once
+- Wait for user response before proceeding to next step
+- Keep the conversation focused and efficient
+- Generate a descriptive agent name based on their choices

.claude/commands/create-team.md

@@ -0,0 +1,95 @@
+# Create Custom Agent Team - Socratic Guide
+
+You are helping the user create a custom AI agent team for their project using the Empathy Framework. Use the AskUserQuestion tool to gather requirements through a guided conversation.
+
+## Step 1: Understand the Team's Mission
+
+Use AskUserQuestion with:
+- Question: "What is the team's overall goal?"
+- Header: "Team Goal"
+- Options:
+  - "Code quality pipeline" - Review, test, and improve code quality
+  - "Release preparation" - Prepare code for production deployment
+  - "Documentation sync" - Keep docs aligned with code
+  - "Security audit" - Comprehensive security analysis
+
+## Step 2: Determine Team Size
+
+Use AskUserQuestion with:
+- Question: "How many agents should be on this team?"
+- Header: "Team Size"
+- Options:
+  - "2 agents (Recommended)" - Simple workflow: analyze then act
+  - "3 agents" - Standard: analyze, execute, validate
+  - "4 agents" - Comprehensive: analyze, execute, validate, report
+  - "5 agents" - Full pipeline with multiple specialists
+
+## Step 3: Define Collaboration Pattern
+
+Use AskUserQuestion with:
+- Question: "How should agents work together?"
+- Header: "Collaboration"
+- Options:
+  - "Sequential (Recommended)" - Each agent waits for the previous one
+  - "Parallel then merge" - Run analysis in parallel, then synthesize
+  - "Pipeline" - Output of each feeds into the next
+
+## Step 4: Select Agent Roles
+
+Based on team size and goal, present role options. For a 3-agent team:
+
+Use AskUserQuestion with multiSelect: true:
+- Question: "Which roles should your team have? (Select 3)"
+- Header: "Roles"
+- Options:
+  - "Analyst" - Examines code/docs and identifies issues
+  - "Generator" - Creates content (tests, docs, fixes)
+  - "Reviewer" - Checks quality and correctness
+  - "Validator" - Verifies results meet criteria
+
+## Step 5: Cost Preference
+
+Use AskUserQuestion with:
+- Question: "What's your cost preference for this team?"
+- Header: "Cost"
+- Options:
+  - "Minimize cost (Recommended)" - Use cheap tier where possible ($0.03-0.10 per run)
+  - "Balance cost/quality" - Mix of cheap and capable ($0.10-0.30 per run)
+  - "Maximize quality" - Use capable/premium tiers ($0.30-0.60 per run)
+
+## Step 6: Generate the Team Template
+
+After gathering all answers, generate the team specification:
+
+```json
+{
+  "id": "[goal-based-id]",
+  "name": "[Descriptive Team Name]",
+  "description": "[Based on goal]",
+  "collaboration_pattern": "[Selected pattern]",
+  "agents": [
+    {
+      "role": "[Role 1]",
+      "purpose": "[What this agent does]",
+      "tier": "[Based on cost preference]",
+      "base_template": "generic"
+    }
+  ],
+  "estimated_cost_range": {
+    "min": 0.03,
+    "max": 0.30
+  }
+}
+```
+
+Then tell the user:
+1. Show the generated template in a code block
+2. Save it to `.empathy/meta_workflows/templates/[id].json`
+3. Explain how to run it: `empathy meta-workflow run [id]`
+
+## Important
+
+- Use AskUserQuestion for EACH step - don't ask multiple questions at once
+- Wait for user response before proceeding to next step
+- For role selection, use multiSelect: true
+- Generate meaningful agent names and purposes based on the goal