@dragonflymcp/plugin 1.0.0

package/templates/commands/observe.md.template

@@ -0,0 +1,211 @@
+# Observe Command
+
+Analyze prompt observability data to understand Claude Code usage patterns.
+
+## Usage
+
+```
+/observe [subcommand] [options]
+```
+
+## Subcommands
+
+### `stats` (default)
+Show usage statistics.
+
+```
+/observe stats
+/observe stats --period=week
+```
+
+### `prompts`
+List recent prompts.
+
+```
+/observe prompts --limit=10
+/observe prompts --concept=architecture
+```
+
+### `costs`
+Estimate costs based on token usage.
+
+```
+/observe costs
+/observe costs --period=month
+```
+
+### `patterns`
+Analyze usage patterns.
+
+```
+/observe patterns
+```
+
+## Process
+
+When you run this command:
+
+1. **Load Observability Data**
+   - Read `koan/observability/prompts.jsonl`
+   - Load `koan/observability/daily-stats.json`
+
+2. **Analyze Based on Subcommand**
+   - Aggregate data by concept, model, or time period
+   - Calculate token usage and estimated costs
+   - Identify patterns and anomalies
+
+3. **Display Results**
+   - Formatted tables and summaries
+   - Cost breakdowns by model
+   - Usage trends
+
+## Example Output
+
+### Stats Output
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+Prompt Observability - Last 7 Days
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Total Calls:     247
+Total Tokens:    ~89,420
+Estimated Cost:  $2.68
+
+By Model:
+┌──────────┬───────┬──────────┬──────────┐
+│ Model    │ Calls │ Tokens   │ Cost     │
+├──────────┼───────┼──────────┼──────────┤
+│ sonnet    │ 189   │ 45,230   │ $0.11    │
+│ sonnet   │ 48    │ 32,190   │ $0.96    │
+│ opus     │ 10    │ 12,000   │ $1.61    │
+└──────────┴───────┴──────────┴──────────┘
+
+By Concept:
+┌─────────────────┬───────┬──────────┐
+│ Concept         │ Calls │ Tokens   │
+├─────────────────┼───────┼──────────┤
+│ implementation  │ 78    │ 28,420   │
+│ quality         │ 62    │ 18,600   │
+│ story           │ 45    │ 12,150   │
+│ architecture    │ 32    │ 19,200   │
+│ verification    │ 20    │ 8,050    │
+│ version         │ 10    │ 3,000    │
+└─────────────────┴───────┴──────────┘
+
+Daily Trend:
+Mon: ████████████░░░░░░░░ 42 calls
+Tue: ██████████████░░░░░░ 51 calls
+Wed: ████████████████░░░░ 58 calls
+Thu: ██████████░░░░░░░░░░ 38 calls
+Fri: ████████████████████ 58 calls
+```
+
+### Prompts Output
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+Recent Prompts
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+1. [2025-01-15 10:45:32] architecture.design (opus)
+   Tokens: ~1,200 | Session: abc123
+
+2. [2025-01-15 10:42:18] implementation.generate (sonnet)
+   Tokens: ~450 | Session: abc123
+
+3. [2025-01-15 10:38:05] story.create (sonnet)
+   Tokens: ~280 | Session: abc123
+
+4. [2025-01-15 10:35:22] quality.review (sonnet)
+   Tokens: ~320 | Session: abc122
+
+5. [2025-01-15 10:30:11] verification.verify_architecture (sonnet)
+   Tokens: ~680 | Session: abc122
+```
+
+### Costs Output
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+Cost Analysis - January 2025
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Estimated Total: $12.45
+
+Model Breakdown:
+┌──────────┬──────────────┬────────────┬───────────┐
+│ Model    │ Input Tokens │ Est. Cost  │ % of Total│
+├──────────┼──────────────┼────────────┼───────────┤
+│ opus     │ 45,000       │ $6.75      │ 54.2%     │
+│ sonnet   │ 125,000      │ $3.75      │ 30.1%     │
+│ sonnet    │ 780,000      │ $1.95      │ 15.7%     │
+└──────────┴──────────────┴────────────┴───────────┘
+
+Pricing Reference:
+- Opus:   $15.00 / 1M input tokens
+- Sonnet: $3.00  / 1M input tokens
+- Sonnet:  $0.25  / 1M input tokens
+
+Cost Optimization Tips:
+1. Architecture uses 54% of budget (Opus) - consider Sonnet for lower-risk designs
+2. Quality checks are efficient (Sonnet) - good usage pattern
+3. Consider caching repeated prompts
+```
+
+### Patterns Output
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+Usage Patterns Analysis
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Peak Hours:
+- Most active: 10:00-12:00, 14:00-16:00
+- Lowest: 07:00-09:00, 18:00-20:00
+
+Workflow Patterns:
+- Average concepts per session: 4.2
+- Most common flow: story → architecture → implementation
+- Verification rate: 68% of architectures verified
+
+Retry Patterns:
+- Average retries per concept: 1.3
+- Highest retry rate: implementation (1.8)
+- Lowest retry rate: version (1.0)
+
+Recommendations:
+1. Implementation has high retry rate - consider adding examples
+2. Quality reviews rarely need retries - prompt is effective
+3. Architecture could benefit from planning phase more often
+```
+
+## Data Storage
+
+Observability data is stored in:
+
+```
+koan/observability/
+├── prompts.jsonl        # Raw prompt logs (JSONL format)
+├── daily-stats.json     # Aggregated daily statistics
+└── prompts-*.jsonl.gz   # Archived logs (rotated)
+```
+
+## Privacy
+
+- Only metadata is logged (concept, action, model, token estimates)
+- Actual prompt content is NOT stored
+- Logs can be disabled by setting `PROMPT_OBSERVABILITY_ENABLED=false`
+
+## Integration
+
+Enable observability by adding the hook to your project:
+
+```bash
+# In .claude/settings.json
+{
+  "hooks": {
+    "PostToolUse": [".claude/hooks/post-prompt-observe.sh"]
+  }
+}
+```

package/templates/commands/pr-review.md.template

@@ -0,0 +1,164 @@
+# /pr-review Command
+
+Analyze and review pull requests using MCP tools.
+
+## Usage
+
+```
+/pr-review <pr_url>                    # Analyze PR
+/pr-review submit <pr_url> [--approve] # Submit formal review
+/pr-review comment <pr_url> <file:line> <message>  # Add inline comment
+```
+
+## Purpose
+
+This command invokes the pr-review concept to:
+- Analyze code changes for quality issues
+- Check architectural impact
+- Scan for security concerns
+- Suggest improvements
+- Submit reviews via GitHub MCP
+
+## Process
+
+When you run `/pr-review <url>`:
+
+1. **Fetch PR Details**
+   - Get changed files via GitHub MCP
+   - Load existing comments
+
+2. **Analyze Changes**
+   - Code quality assessment
+   - Pattern consistency check
+   - Error handling completeness
+
+3. **Check Architecture**
+   - Component boundaries
+   - Dependency direction
+   - Impact on call graph (via AST index)
+
+4. **Security Scan**
+   - Input validation
+   - Secrets handling
+   - Common vulnerabilities
+
+5. **Generate Report**
+   - Categorized findings
+   - Severity ratings
+   - Specific suggestions
+
+## Output Format
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+PR Analysis: #123 - Add OAuth authentication
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Summary:
+  Files Changed: 8
+  Additions:     245
+  Deletions:     32
+
+┌─────────────────────────────────────────────────┐
+│ Code Quality: 85%                               │
+├─────────────────────────────────────────────────┤
+│ MEDIUM  src/auth/oauth.ts:45                    │
+│         Error handling could be more specific   │
+│         → Catch specific OAuth errors           │
+│                                                 │
+│ LOW     src/auth/oauth.ts:78                    │
+│         Magic string detected                   │
+│         → Extract 'google' to constant          │
+└─────────────────────────────────────────────────┘
+
+┌─────────────────────────────────────────────────┐
+│ Architectural Impact: LOW RISK                  │
+├─────────────────────────────────────────────────┤
+│ AuthService  - New dependency added             │
+│ UserController - New endpoint registered        │
+│ Call Graph: +5 new calls, 2 modified            │
+└─────────────────────────────────────────────────┘
+
+┌─────────────────────────────────────────────────┐
+│ Security: 90%                                   │
+├─────────────────────────────────────────────────┤
+│ INFO    Ensure OAuth secrets in env variables   │
+│         File: src/auth/config.ts                │
+└─────────────────────────────────────────────────┘
+
+┌─────────────────────────────────────────────────┐
+│ Testing                                         │
+├─────────────────────────────────────────────────┤
+│ Tests Added: 3                                  │
+│ Coverage:    ~85% (estimated)                   │
+│ New Code:    ✓ Covered                          │
+└─────────────────────────────────────────────────┘
+
+Recommendations:
+  MUST ADDRESS:
+    • Add specific error types for OAuth failures
+
+  SHOULD ADDRESS:
+    • Extract provider names to constants
+    • Add integration test for token refresh
+
+  NICE TO HAVE:
+    • Add JSDoc comments for public methods
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Analysis saved to: koan/reviews/pr-123-analysis.yaml
+
+Submit review? [a] Approve  [c] Comment  [r] Request Changes  [n] Skip
+```
+
+## Submitting Reviews
+
+With `/pr-review submit`:
+
+```
+/pr-review submit https://github.com/owner/repo/pull/123 --approve
+
+Submitting review...
+
+✓ Review submitted: APPROVE
+  Summary posted with 3 inline comments
+
+View at: https://github.com/owner/repo/pull/123#pullrequestreview-...
+```
+
+## Adding Comments
+
+```
+/pr-review comment #123 src/auth.ts:45 "Consider using AuthError type"
+
+✓ Comment posted at src/auth.ts line 45
+```
+
+## Review Criteria
+
+| Category | Checks |
+|----------|--------|
+| Code Quality | Clean code, error handling, duplication, naming |
+| Architecture | Boundaries, dependencies, patterns |
+| Security | Input validation, auth, secrets, injection |
+| Performance | N+1 queries, re-renders, memory leaks |
+| Testing | Coverage, edge cases, integration |
+
+## Storage
+
+- Analysis: `koan/reviews/pr-{number}-analysis.yaml`
+- Notification: `koan/notifications/pr-alert-{timestamp}.yaml` (if high-risk)
+
+## MCP Tools Used
+
+- GitHub MCP: `get_pull_request`, `get_pull_request_files`, `create_pull_request_review`
+- AST Index: `find_symbol`, `get_call_graph` (optional, enhances review)
+- Semantic RAG: `find_similar_code` (optional, finds patterns)
+
+## WYSIWID Principle
+
+Review criteria visible in:
+- `.claude/concepts/pr-review.md`
+- Analysis YAML shows all factors considered
+- No hidden scoring rules

package/templates/commands/predict-cost.md.template

@@ -0,0 +1,251 @@
+---
+name: predict-cost
+description: Predict the cost of implementing a feature before running it
+---
+
+# Predict Cost Command
+
+Estimate the cost of a feature implementation before actually running it.
+
+## Usage
+
+```bash
+/predict-cost "Feature description"
+
+# Examples
+/predict-cost "Add OAuth authentication"
+/predict-cost "Implement dark mode toggle"
+/predict-cost "Create REST API for users"
+```
+
+## How It Works
+
+Analyzes the feature description to estimate which concepts will be invoked and predicts the total cost based on Zen's standard workflow.
+
+## Implementation
+
+When invoked, this command:
+
+1. **Parses** the feature description
+2. **Estimates complexity** (simple, medium, complex)
+3. **Predicts workflow path**:
+   - Story → Architecture → Implementation → Quality → Version
+   - Plus any rework cycles (based on historical data)
+4. **Calculates cost** using current model pricing
+5. **Shows breakdown** by concept and model
+
+## Cost Prediction Model
+
+### Base Workflow (95% of features)
+
+```yaml
+story:
+  model: sonnet
+  cost: $0.003
+
+architecture:
+  model: opus
+  cost: $0.015  # Uses Opus for deep reasoning
+  note: "~50% of total cost"
+
+implementation:
+  model: sonnet
+  cost: $0.003
+
+quality_review:
+  model: sonnet
+  cost: $0.003
+  parallel: true
+
+quality_test:
+  model: sonnet
+  cost: $0.003
+  parallel: true
+
+version:
+  model: sonnet
+  cost: $0.003
+
+total_base: ~$0.030
+```
+
+### Complexity Adjustments
+
+**Simple Features** (80% probability):
+- Single component changes
+- Clear requirements
+- Low risk
+- Expected cost: ~$0.030
+- Success rate: 95%
+
+**Medium Features** (15% probability):
+- Multi-component changes
+- Some ambiguity
+- Medium risk
+- Expected cost: ~$0.035 (includes 1 rework cycle)
+- Success rate: 90%
+
+**Complex Features** (5% probability):
+- Major architectural changes
+- High ambiguity
+- High risk
+- Expected cost: ~$0.050 (includes 2 rework cycles)
+- Success rate: 85%
+- May require manual review
+
+### Rework Probability
+
+Based on historical data:
+- **5% chance**: Quality review needs changes (+$0.003)
+- **3% chance**: Tests fail (+$0.003)
+- **2% chance**: Architecture needs revision (+$0.015)
+
+## Example Output
+
+```
+💰 Cost Prediction
+
+Feature: "Add OAuth authentication"
+Complexity: Medium
+Risk: Medium
+
+Predicted Workflow:
+✓ Story (Sonnet)          $0.003    10%
+✓ Architecture (Opus)     $0.015    50%  ← Deep reasoning
+✓ Implementation (Sonnet) $0.003    10%
+✓ Quality Review (Sonnet) $0.003    10%  │ parallel
+✓ Quality Test (Sonnet)   $0.003    10%  │
+✓ Version (Sonnet)        $0.003    10%
+────────────────────────────────────────
+Baseline Total:           ~$0.030   100%
+
+Rework Probability (based on historical data):
+  5% chance: Quality needs changes  +$0.003
+  3% chance: Tests fail             +$0.003
+  2% chance: Architecture revision  +$0.015
+
+Expected Cost (with rework): ~$0.032
+Maximum Cost (worst case):   ~$0.050
+Minimum Cost (best case):    ~$0.030
+
+Confidence: Medium (based on description analysis)
+Estimated Duration: 12-15 minutes
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+Cost Breakdown by Model:
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+Opus:    $0.015     (50% of cost, 1 action)
+Sonnet:  $0.015     (50% of cost, 5 actions)
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Smart Model Assignment:
+Architecture uses Opus for deep reasoning
+Other concepts use Sonnet for efficiency
+```
+
+## Complexity Detection
+
+The prediction analyzes the description for:
+
+**Simple Indicators**:
+- "add", "update", "fix"
+- Single component mentioned
+- Clear, specific requirements
+- Low-risk patterns
+
+**Medium Indicators**:
+- "implement", "create", "build"
+- Multiple components
+- Some architectural decisions needed
+- Standard integrations
+
+**Complex Indicators**:
+- "migrate", "refactor", "redesign"
+- System-wide changes
+- New integrations
+- Security/performance critical
+- "real-time", "distributed", "scalable"
+
+## Historical Data Integration
+
+If provenance data exists in `koan/provenance/`, the prediction uses it to improve accuracy:
+
+```bash
+# Uses historical data to calculate:
+# - Average cost per feature type
+# - Rework frequency
+# - Success rates by complexity
+# - Actual vs predicted costs
+
+# Shows historical comparison:
+Historical Similar Features:
+  OAuth integration:   $0.032 (12 min)
+  SAML integration:    $0.035 (14 min)
+  JWT authentication:  $0.029 (11 min)
+  Average:             $0.032
+
+Predicted for this feature: $0.032 ✓ Within range
+```
+
+## Configuration
+
+Edit `.claude/config.yaml` to customize:
+
+```yaml
+cost_prediction:
+  enabled: true
+  use_historical_data: true
+  confidence_threshold: 0.7  # Min confidence to show prediction
+
+  # Model costs (updated automatically)
+  opus:
+    cost_per_action: 0.015    # Deep reasoning for architecture
+  sonnet:
+    cost_per_action: 0.003    # Standard execution
+
+  # Rework probabilities (update based on your data)
+  rework_rates:
+    quality_changes: 0.05     # 5%
+    test_failures: 0.03       # 3%
+    arch_revision: 0.02       # 2%
+```
+
+## Limitations
+
+- Prediction is an estimate based on patterns
+- Actual cost may vary by ±20%
+- Cannot predict external dependencies
+- Assumes standard workflow (no custom syncs)
+- Works best with historical provenance data
+
+## Advanced Usage
+
+### Compare Multiple Approaches
+
+```bash
+/predict-cost "Add OAuth using passport.js"
+# Predicted: ~$0.032
+
+/predict-cost "Add OAuth with custom implementation"
+# Predicted: ~$0.045 (higher risk = more rework)
+
+# Compare to make informed decision
+```
+
+### Track Prediction Accuracy
+
+```bash
+# After implementing a feature
+/costs --compare story-001
+
+# Shows:
+# Predicted: ~$0.032
+# Actual:    $0.029
+# Accuracy:  91%
+```
+
+## See Also
+
+- `/costs` - View actual costs after implementation
+- `/trace` - See complete workflow with costs
+- `/workflow` - Alternative entry point with prediction