@dragonflymcp/plugin 1.0.0

package/templates/commands/compete.md.template

@@ -0,0 +1,90 @@
+Run a competitive evaluation comparing Zen-assisted vs vanilla Claude Code generation.
+
+When the user runs this command, you should:
+
+1. **Resolve the spec**
+   - If the user provides a spec ID directly, use it
+   - If they provide a spec name, use `zen_spec_get` with `name` to find the ID
+   - If no argument, use `zen_spec_get` with `latest: true`
+
+2. **Start the competition**
+   - Call `compete_start` with the spec_id
+   - Display the session ID and configuration
+   - Show the evaluation dimensions and weights
+
+3. **Run rounds in parallel**
+   For each round (1 to N):
+   - Launch a **control arm** subagent (worktree, model: sonnet) with the control_prompt
+     - The control agent generates code from the spec with NO MCP tools
+   - Launch a **treatment arm** subagent (worktree, model: sonnet) with the treatment_prompt
+     - The treatment agent uses full zen MCP tools
+   - Both run in parallel via Task tool with `isolation: "worktree"`
+
+4. **Evaluate each arm**
+   After both arms complete for a round:
+   - Use the evaluation_instructions to score each output
+   - Call `compete_submit` for each arm with the 6-dimension scores
+   - Display round results as they complete
+
+5. **Report results**
+   - After all rounds, display the CompeteSummary:
+     - Overall winner
+     - Per-dimension p-values and effect sizes
+     - Composite statistics
+   - If treatment wins, offer to run ablation testing
+
+6. **Optional: Ablation testing**
+   If the user agrees to ablation:
+   - Call `compete_ablate_start` to get per-category prompts
+   - For each category × rounds, launch subagents with ablation prompts
+   - Call `compete_ablate_submit` for each run
+   - Display the minimal effective toolset
+
+## Usage
+
+```
+/compete <spec-id>              # Run with specific spec
+/compete string-utils           # Run with spec by name
+/compete                        # Run with latest spec
+/compete <spec-id> --rounds 10  # Override round count
+```
+
+## What It Measures
+
+| Dimension | Weight | Go Command |
+|-----------|--------|------------|
+| correctness | 0.30 | `go test -race -count=1 ./...` |
+| contracts | 0.20 | `go test -run TestProperty ./...` |
+| security | 0.20 | `gosec ./...` |
+| performance | 0.10 | `go test -bench=. -benchmem ./...` |
+| complexity | 0.10 | `gocyclo -avg .` |
+| lint | 0.10 | `go vet ./... && staticcheck ./...` |
+
+## Statistical Methods
+
+- **Welch's t-test**: Unequal variance comparison between arms
+- **Cohen's d**: Effect size measurement (small=0.2, medium=0.5, large=0.8)
+- **Significance level**: Default α=0.05 (configurable)
+
+## Example Output
+
+```
+Competition Complete: 5 rounds
+
+Overall Winner: treatment (p=0.003, d=1.42)
+
+Dimension Analysis:
+  correctness:  treatment wins (p=0.01, d=1.1)
+  contracts:    treatment wins (p=0.02, d=0.9)
+  security:     inconclusive  (p=0.15, d=0.4)
+  performance:  inconclusive  (p=0.08, d=0.5)
+  complexity:   treatment wins (p=0.04, d=0.8)
+  lint:         inconclusive  (p=0.22, d=0.3)
+
+Run ablation testing? (y/n)
+```
+
+## Related Commands
+
+- `/spec` - Define specifications for evaluation
+- `/feature` - Start a new feature workflow

package/templates/commands/costs.md.template

@@ -0,0 +1,111 @@
+Show cost analysis for AI model usage across flows and concepts.
+
+When the user runs this command, you should:
+
+1. Aggregate provenance data from koan/provenance/
+2. Calculate costs by concept, model, and time period
+3. Show cost efficiency metrics and trends
+
+Usage:
+- `/costs` - Show all-time costs
+- `/costs --last-week` - Show last 7 days
+- `/costs --by-concept` - Break down by concept
+- `/costs --by-flow` - Break down by flow
+
+Process:
+1. Read all provenance files from koan/provenance/actions/
+2. Aggregate cost data
+3. Calculate metrics
+4. Present insights
+
+Example output:
+```
+Zen Cost Analysis
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Period: All time
+Total flows: 15
+Total actions: 87
+Total cost: $0.2475
+
+By Concept:
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+story           (sonnet)   15 actions   $0.045   (5%)
+code-analysis   (sonnet)   15 actions   $0.045   (5%)
+architecture    (opus)     15 actions   $0.225   (25%) ⭐
+verification    (sonnet)   15 actions   $0.045   (5%)
+implementation  (sonnet)   15 actions   $0.045   (5%)
+quality         (sonnet)   30 actions   $0.090   (10%)
+security        (sonnet)   15 actions   $0.045   (5%)
+version         (sonnet)   15 actions   $0.045   (5%)
+context         (sonnet)    5 actions   $0.015   (2%)
+documentation   (sonnet)   15 actions   $0.045   (5%)
+
+By Model:
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Opus:    15 actions   $0.225   (25%)
+Sonnet: 140 actions   $0.420   (75%)
+
+Cost Efficiency:
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Smart model assignment savings:
+- Actual cost:     $0.2475
+- All-sonnet cost: $1.4850
+- Savings:         $1.2375 (83%)
+
+Average cost per feature:
+- With smart assignment: $0.0165
+- With all-sonnet:       $0.0990
+- Savings per feature:   $0.0825
+
+Cost breakdown per feature:
+┌─────────────────┬────────┬──────────┬──────────┐
+│ Concept         │ Model  │ Cost     │ % Total  │
+├─────────────────┼────────┼──────────┼──────────┤
+│ Story           │ Sonnet │ $0.003   │  5%      │
+│ Code-Analysis   │ Sonnet │ $0.003   │  5%      │
+│ Architecture    │ Opus   │ $0.015   │ 25% ⭐   │
+│ Verification    │ Sonnet │ $0.003   │  5%      │
+│ Implementation  │ Sonnet │ $0.003   │  5%      │
+│ Quality (x2)    │ Sonnet │ $0.006   │ 10%      │
+│ Security        │ Sonnet │ $0.003   │  5%      │
+│ Version         │ Sonnet │ $0.003   │  5%      │
+│ Context         │ Sonnet │ $0.003   │  5%      │
+│ Documentation   │ Sonnet │ $0.003   │  5%      │
+└─────────────────┴────────┴──────────┴──────────┘
+
+Insights:
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+✓ Smart model assignment working as designed
+✓ Architecture (Opus) accounts for 25% of cost
+✓ This is expected - architecture requires deep reasoning
+✓ Other 9 concepts efficiently use Sonnet (major cost savings)
+
+Recent Trends (Last 7 Days):
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Features completed: 3
+Total cost: $0.0495
+Average cost per feature: $0.0165
+Model usage: 25% Opus, 75% Sonnet
+Cost efficiency: Consistent 83% savings
+
+Top Flows by Cost:
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+1. flow-001 "Add dark mode" - $0.0165
+2. flow-002 "User auth"     - $0.0185 (arch revision +$0.002)
+3. flow-003 "API endpoints" - $0.0155
+```
+
+Key Insights:
+- Architecture is expensive but necessary (prevents costly rework)
+- Sonnet is sufficient for 9/10 concepts (major cost savings)
+- Consistent cost per feature enables budget forecasting
+- Can identify outliers (e.g., flow-002 with arch revision)
+
+This command helps validate the smart model assignment strategy and identify opportunities for optimization.

package/templates/commands/estimate.md.template

@@ -0,0 +1,196 @@
+# /estimate Command
+
+Get predictive estimates before executing a task.
+
+## Usage
+
+```
+/estimate "Add OAuth authentication"
+/estimate --workflow refactor "Reorganize the auth module"
+/estimate --compare est-20250106  # Compare prediction to actual
+```
+
+## Purpose
+
+This command predicts outcomes BEFORE execution:
+- Expected duration
+- Expected cost
+- Risk factors
+- Optimization suggestions
+- SLO pass/fail likelihood
+
+## Process
+
+When you run `/estimate "<task>"`:
+
+1. **Load Historical Data**
+   ```bash
+   cat koan/slo/metrics/*/*.yaml  # Monthly performance data
+   ```
+
+2. **Classify Task**
+   - Use task-routing.yaml patterns
+   - Determine base complexity
+
+3. **Analyze Complexity**
+   - Count acceptance criteria (from story)
+   - Check code analysis results (if available)
+   - Identify scope indicators
+
+4. **Match Historical Tasks**
+   - Find similar past tasks by type + complexity
+   - Calculate statistical distributions
+
+5. **Generate Predictions**
+   - Expected values (mean)
+   - P50 (median)
+   - P95 (worst case)
+   - Confidence level
+
+6. **Assess SLO Risk**
+   - Compare predictions to SLO thresholds
+   - Flag potential violations
+
+7. **Suggest Optimizations**
+   - Skills to enable
+   - Cached patterns to use
+   - Workflow adjustments
+
+## Output Format
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+Predictive Estimate
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Task: "Add OAuth authentication"
+Type: NEW FEATURE (full-feature-flow)
+
+┌─────────────────────────────────────────────────┐
+│ Predictions                                     │
+├─────────────────────────────────────────────────┤
+│ Duration:  15-25 min (expected: 18 min)         │
+│ Cost:      $0.02-0.05 (expected: $0.03)         │
+│ Quality:   85% likely to pass review            │
+│ Context:   ~8,500 tokens (15% overflow risk)    │
+│                                                 │
+│ Confidence: 75% (based on 12 similar tasks)     │
+└─────────────────────────────────────────────────┘
+
+SLO Assessment:
+  Duration: ✅ LIKELY PASS (< 20 min SLO)
+  Cost:     ⚠️ AT RISK ($0.03 approaches $0.05 budget)
+  Quality:  ✅ LIKELY PASS (> 80% target)
+
+Risk Factors:
+  • OAuth complexity varies by provider count
+  • No cached architecture pattern found
+  • First auth feature in this project
+
+Recommendations:
+  1. Enable 'incremental-loading' skill
+     → Expected 40% context reduction
+
+  2. Use oauth-authentication example
+     → Path: .claude/examples/architecture/oauth-authentication.yaml
+     → Expected 50% faster architecture phase
+
+  3. Consider breaking into phases:
+     → Phase 1: Google OAuth only
+     → Phase 2: Add GitHub provider
+     → Reduces per-task complexity
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Proceed? [y] Yes  [o] Optimize first  [n] Cancel
+```
+
+## Comparing Predictions
+
+After a task completes, compare predictions to actuals:
+
+```
+/estimate --compare est-20250106-143052
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+Prediction Accuracy Report
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Estimate: est-20250106-143052
+Task: "Add OAuth authentication"
+
+              Predicted    Actual      Accuracy
+Duration:     18 min       22 min      82%
+Cost:         $0.03        $0.028      107%
+Quality:      85%          passed      ✓
+
+Analysis:
+  • Duration underestimated by 4 min
+  • Reason: Provider-specific error handling took longer
+  • Learning: Add +20% buffer for multi-provider OAuth
+
+Updated Model:
+  • oauth-related tasks: duration_factor += 0.2
+  • Confidence for similar tasks: now 78%
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+## Historical Data Requirements
+
+Estimates work best with historical data in:
+```
+koan/slo/metrics/
+├── architecture/
+│   └── 2025-01.yaml
+├── implementation/
+│   └── 2025-01.yaml
+└── quality/
+    └── 2025-01.yaml
+```
+
+Without historical data, estimates use:
+- Task type base complexity
+- Industry benchmarks
+- Conservative confidence (50%)
+
+## Complexity Indicators
+
+| Indicator | Low | Medium | High |
+|-----------|-----|--------|------|
+| Acceptance criteria | 1-3 | 4-6 | 7+ |
+| Affected files | 1-3 | 4-10 | 11+ |
+| Call graph depth | 1-2 | 3-4 | 5+ |
+| New vs existing | Existing | Mixed | All new |
+
+## Integration with /workflow
+
+Estimates can auto-run before workflows:
+
+```yaml
+# In config.yaml
+workflow:
+  pre_flight_estimate: true  # Auto-estimate before execution
+  estimate_approval_threshold: "at_risk"  # Ask user if AT RISK
+```
+
+When enabled:
+```
+/workflow "Add OAuth"
+
+Running pre-flight estimate...
+
+⚠️ Cost prediction ($0.03) is AT RISK vs budget ($0.05)
+
+Recommendations available. View estimate? [y/n]
+```
+
+## WYSIWID Principle
+
+Estimates are fully transparent:
+- All complexity factors shown
+- Historical data sources cited
+- Confidence levels explained
+- Recommendations include reasoning
+
+What you see in the estimate is exactly what informed the predictions.

package/templates/commands/explore.md.template

@@ -0,0 +1,186 @@
+---
+name: explore
+description: "Explore multiple solution approaches using Tree-of-Thoughts reasoning"
+usage: "/explore <problem description>"
+---
+
+# Explore Command
+
+Use Tree-of-Thoughts reasoning to explore multiple approaches to a complex problem before committing to a solution.
+
+## Usage
+
+```bash
+/explore "Design a caching strategy for the API"
+/explore "Refactor the user service for better testability"
+/explore "Debug the intermittent authentication failures"
+```
+
+## When to Use
+
+- Complex architectural decisions with multiple valid approaches
+- Debugging problems where the root cause is unclear
+- Refactoring with multiple strategies to consider
+- Any decision where the stakes are high and reversal is costly
+
+## Process
+
+When you invoke `/explore`, the following happens:
+
+### 1. Problem Analysis
+
+The problem is decomposed into:
+- Sub-goals that need to be achieved
+- Constraints that must be satisfied
+- Decision points where alternatives exist
+
+### 2. Branch Generation
+
+Multiple solution approaches are generated:
+- Each branch is a coherent strategy
+- Branches are meaningfully different (not minor variations)
+- Typically 2-4 branches are explored
+
+### 3. Evaluation
+
+Each branch is scored on:
+- **Feasibility** (1-10): Can we actually build this?
+- **Maintainability** (1-10): Will it be easy to maintain?
+- **Scalability** (1-10): Will it grow with our needs?
+- **Security** (1-10): Are there security concerns?
+- **Complexity** (1-10): How hard is implementation?
+
+### 4. Selection
+
+The highest-scoring path is selected:
+- Clear winners (>1.5 point lead) are chosen confidently
+- Close scores may trigger hybrid consideration
+- Low confidence (<0.7) triggers deeper evaluation
+
+### 5. Documentation
+
+Results are stored in `koan/explorations/` for future reference.
+
+## Output Format
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+Exploration: Design a caching strategy for the API
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Problem Decomposition:
+- Goal: Reduce API latency for frequent queries
+- Constraints: Must invalidate on data changes
+- Decision Points: Cache location, invalidation strategy
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+Branch 1: Redis with TTL
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+Score: 8.5/10
+
+Steps:
+1. Set up Redis cluster
+2. Implement cache-aside pattern
+3. TTL-based expiration
+
+Pros:
+✓ Proven technology
+✓ Good performance
+✓ Easy to debug
+
+Cons:
+✗ Requires Redis infrastructure
+✗ TTL may serve stale data
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+Branch 2: In-memory with event invalidation
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+Score: 7.8/10
+
+Steps:
+1. Use in-memory cache per instance
+2. Pub/sub for invalidation events
+3. Background refresh
+
+Pros:
+✓ No external dependencies
+✓ Immediate invalidation
+✓ Simpler ops
+
+Cons:
+✗ Memory pressure per instance
+✗ Cold start problem
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+Branch 3: CDN edge caching
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+Score: 6.2/10
+
+Steps:
+1. Configure CDN cache headers
+2. Implement cache purge API
+3. Vary headers for personalization
+
+Pros:
+✓ Global distribution
+✓ Offloads origin
+
+Cons:
+✗ Limited control
+✗ Personalization challenges
+✗ Purge latency
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+Selected: Branch 1 - Redis with TTL
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+Confidence: 0.85
+
+Rationale:
+Clear winner with best balance of performance and reliability.
+TTL staleness mitigated by short expiration for volatile data.
+
+Why others rejected:
+- In-memory: Memory constraints with large datasets
+- CDN: Personalization needs make edge caching impractical
+
+Next Steps:
+1. Set up Redis cluster in staging
+2. Implement cache service wrapper
+3. Add cache hit/miss metrics
+
+Exploration saved: koan/explorations/exp-001.yaml
+```
+
+## Options
+
+```bash
+/explore "problem" --branches 5    # Explore 5 paths instead of default 3
+/explore "problem" --depth 3       # Explore deeper (more steps per path)
+/explore "problem" --quick         # Faster evaluation, less thorough
+```
+
+## Backtracking
+
+If you later discover the chosen path doesn't work:
+
+```bash
+/explore --backtrack "Redis scaling is problematic"
+```
+
+This will:
+1. Document the failure
+2. Store the learning
+3. Re-evaluate remaining paths
+4. Suggest alternative
+
+## Integration
+
+Exploration integrates with:
+- **Architecture**: Complex designs trigger exploration automatically
+- **Debugging**: Repeated failures trigger exploration
+- **Retrospective**: Learnings from explorations stored for future
+
+## Files Created
+
+- `koan/explorations/exp-{id}.yaml` - Full exploration record
+- `koan/learnings/patterns/` - Extracted decision patterns