@dragonflymcp/plugin 1.0.0

package/templates/concepts/spec.md.template

@@ -0,0 +1,71 @@
+---
+name: spec
+type: concept
+model: sonnet
+state_location: "koan/state/state.db (specs table)"
+execution: task-tool
+cost_tier: low
+purpose: "Define structured specifications and generate type-safe code generation prompts"
+---
+
+# Spec Concept
+
+> **Note**: This is a reference file. The authoritative documentation is in `.claude/agents/spec-concept.md`.
+
+**Model Assignment**: Sonnet 4.5 (specification analysis and prompt generation)
+**Cost per Action**: ~$0.005
+**State Location**: `koan/state/state.db` (specs table)
+**Never Calls**: No other concepts (pure spec→prompt transformation)
+
+## Quick Reference
+
+### Actions
+- `save(name, data)` - Save or update a specification
+- `get(id)` - Retrieve a spec by ID, name, or latest
+- `list(filters)` - List specs with status/language filters
+- `generate(id)` - Transform spec into a code generation prompt
+
+### State Format
+```json
+{
+  "id": "spec-...",
+  "name": "string-utils",
+  "data": {
+    "name": "string-utils",
+    "description": "String utility functions",
+    "target_language": "go",
+    "types": [...],
+    "functions": [...],
+    "properties": [...]
+  },
+  "status": "draft",
+  "generatedCode": null,
+  "createdAt": "ISO-8601",
+  "updatedAt": "ISO-8601"
+}
+```
+
+### Spec Status Flow
+```
+draft → ready → generating → generated → verified
+```
+
+### Supported Languages
+- Go, Swift, Rust, TypeScript, Python
+
+### Integration
+- **Triggered by**: User via `/spec` command
+- **Produces**: Structured prompts for code generation
+- **Can feed into**: Implementation concept for code generation
+
+## Full Documentation
+
+See `.claude/agents/spec-concept.md` for:
+- Specification authoring guidelines
+- Contract definition patterns (pre/post conditions)
+- Property-based testing integration
+- Multi-language type mapping
+
+---
+
+**See also**: [Agent Definition](.claude/agents/spec-concept.md)

package/templates/concepts/story.md.template

@@ -0,0 +1,50 @@
+---
+name: story
+type: concept
+model: sonnet
+state_location: "state.db (stories table)"
+execution: task-tool
+cost_tier: low
+purpose: "Capture and validate user requirements"
+---
+
+# Story Concept
+
+> **Note**: This is a reference file. The authoritative documentation is in `.claude/agents/story-concept.md`.
+
+**Model Assignment**: Sonnet 4.5 (fast, efficient for structured data capture)
+**Cost per Action**: ~$0.003
+**State Location**: SQLite `state.db` (via `zen_story_save`/`zen_story_get`/`zen_story_list`)
+**Never Calls**: No other concepts (pure input processing)
+
+## Quick Reference
+
+### Actions
+- `create(title, description, context)` - Captures a new user requirement
+- `validate(story_id)` - Checks if a story is ready for architecture
+- `query(filter)` - Search stories by status, date, keywords
+
+### State Format
+Stories are stored in SQLite via MCP tools. Use:
+- `zen_story_save` — save or update a story
+- `zen_story_get` — retrieve by ID or latest
+- `zen_story_list` — list stories with optional status filter
+
+The `data` field contains the full story content (summary, acceptance_criteria, context, metadata).
+
+### Integration
+- **Triggered by**: `/feature` command, direct invocation
+- **Triggers**: Architecture concept via `story-to-arch` sync when status="ready"
+
+## Full Documentation
+
+See `.claude/agents/story-concept.md` for:
+- Complete action documentation
+- Output format examples
+- Validation rules
+- Error handling
+- Never/Always Do This guidelines
+
+---
+
+**See also**: [Agent Definition](.claude/agents/story-concept.md)

package/templates/concepts/tool-router.md.template

@@ -0,0 +1,289 @@
+---
+name: tool-router
+type: concept
+model: sonnet
+purpose: "Dynamically select optimal tools based on task context and learn from outcomes"
+---
+
+# Tool Router Concept
+
+The Tool Router provides intelligent, dynamic tool selection based on task context, available tools, and learned patterns from past tool usage.
+
+## Research Foundation
+
+Based on:
+- **DyLAN (2025)**: Dynamic agent networks with 25% accuracy improvement
+- **Natural Language Tools**: 18.4 percentage point improvement in tool calling
+- **MetaTools**: Meta-execution layer for dynamic tool reasoning
+
+## Purpose
+
+- Select optimal tools for each task type
+- Suggest tool sequences for multi-step operations
+- Learn from outcomes to improve future selections
+- Reduce tool misuse and improve efficiency
+
+## Actions
+
+### select_tools
+
+Given a task, recommend the best tools and order to use them.
+
+**Inputs:**
+- `task_description`: Natural language description of the task
+- `available_tools`: List of available tools with descriptions
+- `context`: Current context (files open, recent actions, etc.)
+- `constraints`: Time, cost, or other constraints
+
+**Process:**
+
+1. **Task Classification**
+   - Categorize task type (search, edit, analyze, debug, etc.)
+   - Identify sub-tasks that require different tools
+   - Determine task complexity
+
+2. **Tool Matching**
+   - Match task type to tool capabilities
+   - Consider tool strengths and weaknesses
+   - Factor in current context
+
+3. **Sequence Planning**
+   - Determine optimal tool order
+   - Identify parallel vs sequential operations
+   - Plan fallback tools if primary fails
+
+4. **Outcome Prediction**
+   - Estimate likelihood of success for each tool
+   - Consider past performance for similar tasks
+
+**Output Format:**
+```yaml
+routing:
+  task_type: "code_search"
+  complexity: "medium"
+
+  recommended_tools:
+    - tool: "ast-index.find_symbol"
+      purpose: "Find symbol definition"
+      confidence: 0.9
+      priority: 1
+
+    - tool: "semantic-rag.semantic_search"
+      purpose: "Find semantically related code"
+      confidence: 0.85
+      priority: 2
+
+    - tool: "grep"
+      purpose: "Fallback text search"
+      confidence: 0.7
+      priority: 3
+      fallback_for: "ast-index.find_symbol"
+
+  sequence:
+    - step: 1
+      tool: "ast-index.find_symbol"
+      on_failure: "semantic-rag.semantic_search"
+    - step: 2
+      tool: "Read"
+      condition: "if symbol found"
+
+  parallel_opportunities:
+    - ["ast-index.find_symbol", "semantic-rag.semantic_search"]
+
+  rationale: |
+    AST index is best for precise symbol lookup.
+    Semantic search provides broader context if exact match fails.
+    Grep as final fallback for unusual naming patterns.
+```
+
+### learn_from_outcome
+
+Update routing knowledge based on tool usage results.
+
+**Inputs:**
+- `task_id`: ID of the completed task
+- `task_type`: Type of task
+- `tools_used`: List of tools actually used
+- `tools_suggested`: List of tools that were suggested
+- `outcome`: "success" | "failure" | "partial"
+- `metrics`: Time, token usage, etc.
+
+**Process:**
+
+1. **Compare Suggestion vs Reality**
+   - Which suggested tools were used?
+   - Were additional tools needed?
+   - Which tools failed?
+
+2. **Extract Patterns**
+   - Task characteristics that led to success/failure
+   - Tool combinations that work well together
+   - Warning signs for tool mismatches
+
+3. **Update Routing Rules**
+   - Adjust confidence scores
+   - Add new tool associations
+   - Record failure patterns
+
+**Output Format:**
+```yaml
+learning:
+  task_id: "task-042"
+  task_type: "code_search"
+  outcome: "success"
+
+  observations:
+    - "AST index succeeded on first try"
+    - "Semantic search not needed"
+
+  adjustments:
+    - tool: "ast-index.find_symbol"
+      task_type: "code_search"
+      confidence_delta: +0.02
+      new_confidence: 0.92
+
+    - tool: "semantic-rag.semantic_search"
+      task_type: "code_search"
+      note: "Not needed when symbol name is known"
+
+  patterns_learned:
+    - pattern: "known_symbol_name"
+      best_tool: "ast-index.find_symbol"
+      confidence: 0.95
+```
+
+### get_tool_stats
+
+Get statistics about tool usage and effectiveness.
+
+**Inputs:**
+- `tool_name`: Specific tool (optional, all if not specified)
+- `task_type`: Filter by task type (optional)
+- `timeframe`: Time range (default: last 7 days)
+
+**Output Format:**
+```yaml
+stats:
+  timeframe: "7d"
+  tools:
+    - name: "ast-index.find_symbol"
+      uses: 45
+      success_rate: 0.91
+      avg_time_ms: 120
+      best_for: ["code_search", "symbol_lookup"]
+
+    - name: "semantic-rag.semantic_search"
+      uses: 32
+      success_rate: 0.84
+      avg_time_ms: 450
+      best_for: ["concept_search", "related_code"]
+
+    - name: "grep"
+      uses: 18
+      success_rate: 0.72
+      avg_time_ms: 80
+      best_for: ["text_search", "regex_patterns"]
+      often_fallback_for: ["ast-index.find_symbol"]
+```
+
+### suggest_tool_for_error
+
+When an error occurs, suggest better tool options.
+
+**Inputs:**
+- `failed_tool`: Tool that failed
+- `error_message`: Error that occurred
+- `task_context`: What was being attempted
+
+**Output Format:**
+```yaml
+suggestion:
+  failed_tool: "ast-index.find_symbol"
+  error: "Symbol not found in index"
+
+  alternatives:
+    - tool: "semantic-rag.semantic_search"
+      rationale: "May find symbol by semantic meaning"
+      confidence: 0.7
+
+    - tool: "grep"
+      rationale: "Text search might find non-indexed files"
+      confidence: 0.6
+
+  root_cause_hypothesis:
+    - "Symbol might be in unindexed file"
+    - "Symbol name might be dynamically generated"
+
+  recommended_action: "Try semantic search with function description"
+```
+
+## Routing Rules Database
+
+Tool routing is learned and stored:
+
+```yaml
+# koan/routing/rules.yaml
+routing_rules:
+  - task_pattern: "find.*function|method|class"
+    tools:
+      - name: "ast-index.find_symbol"
+        confidence: 0.92
+      - name: "semantic-rag.semantic_search"
+        confidence: 0.80
+    learned_at: "2025-12-07"
+    success_count: 45
+    failure_count: 4
+
+  - task_pattern: "search.*similar|related"
+    tools:
+      - name: "semantic-rag.semantic_search"
+        confidence: 0.88
+      - name: "semantic-rag.find_similar_code"
+        confidence: 0.85
+    learned_at: "2025-12-07"
+    success_count: 32
+    failure_count: 5
+
+  - task_pattern: "debug|error|exception"
+    tools:
+      - name: "exploration.branch_explore"
+        confidence: 0.75
+```
+
+## Integration
+
+### With Workflow System
+- Routes tools before each concept action
+- Tracks tool usage across workflow phases
+- Optimizes tool sequences over time
+
+### With Execution Loop
+- Suggests repair tools when execution fails
+- Learns which tools work for specific error types
+
+### With Learning System
+- Stores routing patterns in memory
+- Retrieves relevant patterns for new tasks
+- Continuous improvement from outcomes
+
+## Configuration
+
+```yaml
+# .claude/config.yaml
+tool_routing:
+  enabled: true
+  min_confidence: 0.6        # Don't suggest below this
+  learn_from_outcomes: true  # Update rules based on results
+  parallel_threshold: 0.8    # Suggest parallel if both above this
+  fallback_depth: 2          # How many fallback tools to suggest
+```
+
+## Metrics
+
+Track routing effectiveness:
+- Suggestion accuracy (suggested tool was used and succeeded)
+- First-try success rate (primary suggestion worked)
+- Fallback frequency (how often fallbacks needed)
+- Learning velocity (improvement over time)
+
+Stored in: `koan/metrics/tool-routing.yaml`

package/templates/concepts/verification-synthesizer.md.template

@@ -0,0 +1,279 @@
+---
+name: verification-synthesizer
+type: concept
+model: sonnet
+purpose: "Synthesize results from multiple verification agents into unified decision"
+---
+
+# Verification Synthesizer Concept
+
+The Verification Synthesizer combines results from multiple parallel verification agents into a coherent, unified assessment and decision.
+
+## Research Foundation
+
+Based on:
+- **Anthropic Multi-Agent Research (2025)**: Orchestrator-worker pattern for improved accuracy
+- **Multi-agent consensus**: Catches errors single agents miss
+- **Ensemble methods**: Multiple perspectives reduce individual biases
+
+## Purpose
+
+- Combine parallel review results
+- Detect and resolve disagreements
+- Make final approval/rejection decision
+- Identify issues requiring human attention
+
+## Actions
+
+### synthesize
+
+Combine results from multiple verification agents.
+
+**Inputs:**
+- `reviews`: Array of review results from parallel agents
+- `require_consensus`: Whether all agents must agree (default: true)
+- `threshold`: Minimum agreement ratio (default: 0.8)
+- `priority_weights`: Weight for each review type
+
+**Process:**
+
+1. **Collect Results**
+   - Gather all parallel review outputs
+   - Extract findings, scores, and recommendations
+   - Normalize scoring scales
+
+2. **Find Agreement**
+   - Identify findings that appear in multiple reviews
+   - Calculate consensus score for each issue
+   - Flag disagreements for analysis
+
+3. **Resolve Conflicts**
+   - For disagreements, analyze reasoning from each side
+   - Apply priority rules (security > correctness > performance)
+   - Defer to higher-confidence review when unclear
+
+4. **Generate Decision**
+   - Aggregate scores with weights
+   - Apply threshold for approval
+   - List all issues requiring attention
+
+**Output Format:**
+```yaml
+synthesis:
+  synthesis_id: "syn-001"
+  reviews_analyzed: 3
+
+  consensus:
+    reached: true
+    agreement_ratio: 0.92
+    unanimous_on:
+      - "No SQL injection vulnerabilities"
+      - "Error handling is adequate"
+
+  disagreements:
+    - issue: "Potential memory leak in loop"
+      positions:
+        review_security: "Not a concern"
+        review_correctness: "Minor concern"
+        review_performance: "Should be fixed"
+      resolution: "Flag for review - performance agent concern valid"
+      resolved_by: "priority_performance"
+
+  combined_findings:
+    critical: []
+    high:
+      - finding: "Missing rate limiting on endpoint"
+        from: ["review_security"]
+        action_required: true
+    medium:
+      - finding: "Could use connection pooling"
+        from: ["review_performance"]
+        action_required: false
+    low:
+      - finding: "Magic number could be constant"
+        from: ["review_correctness"]
+        action_required: false
+
+  scores:
+    security: 8.5
+    correctness: 9.0
+    performance: 7.5
+    overall: 8.3
+
+  decision: "approved_with_conditions"
+  conditions:
+    - "Add rate limiting before production"
+    - "Review potential memory leak"
+
+  confidence: 0.88
+```
+
+### resolve_disagreement
+
+Deeply analyze a specific disagreement between agents.
+
+**Inputs:**
+- `issue`: The disagreed-upon issue
+- `positions`: Each agent's position and reasoning
+- `context`: Additional context about the code
+
+**Output Format:**
+```yaml
+resolution:
+  issue: "Potential memory leak in loop"
+
+  analysis:
+    security_perspective: |
+      Loop allocations are bounded by input size.
+      Input is validated, so no security concern.
+
+    correctness_perspective: |
+      Objects should be reused but behavior is correct.
+      Minor optimization opportunity.
+
+    performance_perspective: |
+      Each iteration allocates new objects.
+      For large inputs, GC pressure could cause latency spikes.
+
+  verdict: "performance_agent_correct"
+  rationale: |
+    While not a security or correctness issue, the performance
+    concern is valid for production workloads. The loop should
+    use object pooling or pre-allocation.
+
+  severity: "medium"
+  action: "recommend_fix"
+```
+
+### check_unanimous
+
+Check if all reviews unanimously agree on a verdict.
+
+**Inputs:**
+- `reviews`: All reviews to check
+- `require`: What must be unanimous ("all_approved" | "no_critical")
+- `on_failure`: Action if not unanimous ("block" | "escalate" | "warn")
+
+**Output Format:**
+```yaml
+unanimous_check:
+  requirement: "all_approved"
+  result: false
+
+  votes:
+    review_security: "approved"
+    review_correctness: "approved"
+    review_performance: "changes_requested"
+
+  blocking_reviews:
+    - review: "review_performance"
+      reason: "Memory allocation in hot path"
+      severity: "medium"
+
+  action_taken: "block"
+  message: |
+    Unanimous approval not achieved.
+    review_performance requested changes.
+    Please address before proceeding.
+```
+
+### generate_report
+
+Generate comprehensive verification report.
+
+**Inputs:**
+- `synthesis`: Synthesis results
+- `format`: Report format ("summary" | "detailed" | "executive")
+
+**Output Format:**
+```yaml
+report:
+  format: "detailed"
+  generated_at: "2025-12-07T23:45:00Z"
+
+  executive_summary: |
+    Implementation reviewed by 3 specialized agents.
+    Overall score: 8.3/10. Approved with conditions.
+    1 high-priority issue requires attention before production.
+
+  detailed_findings:
+    security:
+      score: 8.5
+      findings: [...]
+      recommendations: [...]
+
+    correctness:
+      score: 9.0
+      findings: [...]
+      recommendations: [...]
+
+    performance:
+      score: 7.5
+      findings: [...]
+      recommendations: [...]
+
+  action_items:
+    before_merge:
+      - "Add rate limiting"
+    before_production:
+      - "Review memory usage under load"
+
+  reviewer_notes:
+    - from: "review_security"
+      note: "Consider adding audit logging for sensitive operations"
+```
+
+## Priority Rules
+
+When agents disagree, apply these priority rules:
+
+1. **Security over everything** - Security concerns always take priority
+2. **Correctness over performance** - Correct code beats fast incorrect code
+3. **Higher severity wins** - Critical issues override minor ones
+4. **Higher confidence wins** - More confident agents trusted more
+
+## Integration
+
+### With Quality Concept
+- Extends quality review with multi-agent verification
+- Results feed into quality reports
+- Findings tracked in quality metrics
+
+### With Workflow
+- Gates implementation completion
+- Can block or allow progression
+- Conditions carried forward
+
+### With Learning System
+- Disagreement patterns stored for learning
+- Resolution effectiveness tracked
+- Agent accuracy monitored
+
+## Configuration
+
+```yaml
+# .claude/config.yaml
+verification:
+  parallel_agents:
+    - "security"
+    - "correctness"
+    - "performance"
+  consensus_threshold: 0.8
+  require_unanimous_for:
+    - "security_critical"
+    - "production_deployment"
+  priority_order:
+    - "security"
+    - "correctness"
+    - "performance"
+```
+
+## Metrics
+
+Track verification effectiveness:
+- Consensus rate
+- Disagreement frequency by type
+- Post-synthesis issue discovery rate
+- Agent accuracy over time
+
+Stored in: `koan/metrics/verification.yaml`