@dragonflymcp/plugin 1.0.0

package/templates/concepts/react-fallback.md.template

@@ -0,0 +1,286 @@
+# 🔄 ReAct Fallback Concept
+
+## Model Assignment
+
+**Model**: Sonnet 4.5 (adaptive reasoning)
+**Cost per Action**: ~$0.002
+**Never Calls**: Other concepts directly (works through sync rules)
+
+## Activation Sequence
+
+When invoked, I execute the ReAct fallback concept:
+
+1. ✅ Load ReAct fallback concept template
+2. ✅ Activate Sonnet 4.5 model (adaptive reasoning)
+3. ✅ Analyze blocked synchronization state
+4. ✅ Execute Reason-Act-Observe loop
+5. ✅ Save state file in koan/fallback/
+
+---
+
+## Purpose
+
+The ReAct Fallback concept handles edge cases where pure declarative synchronization rules fail or get blocked. It uses the Reason-Act-Observe pattern to adaptively resolve issues that cannot be handled by static rules.
+
+## Core Principle: Hybrid Approach
+
+**Default**: Declarative synchronization (89% success rate)
+**Fallback**: ReAct loop for unpredictable situations (remaining 11%)
+
+Research shows:
+- Declarative wins for structured workflows (89% vs 78%)
+- BUT edge cases need imperative handling
+- Hybrid approach combines strengths of both
+
+## When to Trigger
+
+ReAct fallback is triggered when:
+- Sync rule evaluation fails after max retries
+- Sync rule cannot find matching condition
+- Circular dependency detected
+- External dependency unavailable
+- Ambiguous state that rules cannot handle
+- User explicitly requests exploration mode
+
+## ReAct Pattern
+
+```
+LOOP (max 5 iterations):
+  1. THOUGHT: Analyze why sync failed
+  2. ACTION: Take corrective action
+  3. OBSERVATION: Check if issue resolved
+  4. IF resolved: BREAK
+  5. IF max iterations: Send to DLQ
+
+OUTCOME:
+  - Success: Resume declarative workflow
+  - Partial: Document workaround, continue
+  - Failed: Add to dead letter queue
+```
+
+## Actions
+
+### handle_blocked(sync_id, context)
+
+Handles a blocked synchronization using ReAct loop.
+
+**Inputs**:
+- `sync_id`: ID of the blocked sync rule
+- `context`: Current workflow state, error details, previous attempts
+
+**Process**:
+1. **THOUGHT**: Analyze the blocking condition
+   - Read sync rule definition
+   - Read current workflow state
+   - Identify why condition not met
+   - Consider alternative paths
+
+2. **ACTION**: Take corrective action
+   - Fix missing files/dependencies
+   - Update workflow state
+   - Retry with different parameters
+   - Invoke alternative sync path
+
+3. **OBSERVATION**: Verify action result
+   - Check if blocking condition resolved
+   - Measure progress toward goal
+   - Detect new issues introduced
+
+4. **DECIDE**: Next step
+   - Continue loop if not resolved
+   - Exit if resolved
+   - Escalate if max iterations reached
+
+**Output Format** (YAML with Progressive Disclosure):
+
+```yaml
+# === SUMMARY (first 5 lines - quick scanning) ===
+fallback_id: "fb-001"
+status: "resolved"
+iterations: 3
+resolution: "Found missing dependency at alternative path"
+
+# === FULL DETAILS (load only if needed) ===
+details:
+  sync_id: "code-analysis.context:completed -> architecture.design"
+  blocked_reason: "Missing file: src/config/settings.ts"
+
+  iterations:
+    - iteration: 1
+      thought: "Expected settings file at src/config/settings.ts not found"
+      action: "Search for settings files in codebase"
+      observation: "Found settings.config.ts at root level"
+      result: "partial_progress"
+
+    - iteration: 2
+      thought: "Settings file exists but at different location"
+      action: "Update sync context to use settings.config.ts"
+      observation: "Sync rule now has valid file reference"
+      result: "partial_progress"
+
+    - iteration: 3
+      thought: "File reference fixed, can now execute sync"
+      action: "Trigger sync rule with updated context"
+      observation: "Sync executed successfully"
+      result: "resolved"
+
+  resolution:
+    status: "resolved"
+    action_taken: "Updated file reference in sync context"
+    workaround: "Use root-level settings.config.ts instead of src/config/settings.ts"
+
+  next_step:
+    action: "resume_workflow"
+    sync_to_execute: "architecture.design"
+
+  metadata:
+    created_at: "2026-01-30T16:00:00Z"
+    concept: "react-fallback"
+    model: "sonnet"
+    cost: 0.000145
+```
+
+## State Location
+
+Fallback executions are saved to: `koan/fallback/fb-{id}.yaml`
+
+## Integration with Synchronizations
+
+The ReAct fallback concept is triggered by:
+- Sync evaluation failure (via `sync-blocked` event)
+- Maximum retry exhaustion
+- Explicit user request (`/react` command)
+
+The ReAct fallback concept triggers (via synchronizations):
+- Resume workflow when resolved
+- DLQ entry when unresolvable
+- User notification when manual intervention needed
+
+## Example Scenarios
+
+### Scenario 1: Missing Dependency
+
+```
+Sync Rule: code-analysis:completed -> architecture.design
+Block: File not found at expected path
+
+ReAct Loop:
+  T1: Expected file missing
+  A1: Search for similar files
+  O1: Found at different path
+
+  T2: Path mismatch in sync rule
+  A2: Update context with actual path
+  O2: Context updated
+
+  T3: Ready to proceed
+  A3: Execute sync with updated context
+  O3: SUCCESS - Resume workflow
+```
+
+### Scenario 2: Circular Dependency
+
+```
+Sync Rule: A:completed -> B:start
+          B:completed -> A:update
+Block: Circular dependency detected
+
+ReAct Loop:
+  T1: Circular dependency between A and B
+  A1: Analyze dependency graph
+  O1: Both waiting on each other
+
+  T2: Need to break cycle
+  A2: Check if either can proceed without the other
+  O2: B can start with partial A state
+
+  T3: Start B with available data
+  A3: Mark A as "partial_complete", trigger B
+  O3: SUCCESS - Cycle broken
+```
+
+### Scenario 3: External Service Unavailable
+
+```
+Sync Rule: quality.test:completed -> version.commit
+Block: MCP test server unavailable
+
+ReAct Loop:
+  T1: MCP server not responding
+  A1: Check fallback options in error-policy
+  O1: Manual test path available
+
+  T2: Can fallback to manual testing
+  A2: Execute tests using bash instead of MCP
+  O2: Tests ran successfully
+
+  T3: Tests passed without MCP
+  A3: Proceed to version.commit
+  O3: SUCCESS - Fallback worked
+```
+
+## Cost Optimization
+
+**Why Sonnet?**
+- Adaptive reasoning required for edge cases
+- No fixed pattern to follow (unlike implementation)
+- Must analyze complex state and make decisions
+- Fast enough for interactive debugging (2-3 seconds)
+- Cheaper than Opus for non-critical reasoning
+
+**When NOT to use this concept:**
+- For normal workflow (use declarative sync rules)
+- When pattern is known (add new sync rule instead)
+- For trivial errors (use error-policy retry)
+
+## Decision Tree
+
+```
+Sync Failed?
+├─ Is error transient? → error-policy (retry)
+├─ Is error permanent? → error-policy (escalate)
+├─ Is error degraded? → error-policy (fallback)
+└─ Is state ambiguous? → react-fallback (this concept)
+```
+
+## Never Do This
+
+- ❌ Use for normal workflow (defeats purpose of declarative)
+- ❌ Call other concepts directly
+- ❌ Make architecture decisions (not the right concept)
+- ❌ Perform git operations
+- ❌ Infinite loops (max 5 iterations)
+
+## Always Do This
+
+- ✅ Use Sonnet model exclusively
+- ✅ Document the resolution for future learning
+- ✅ Save state to koan/fallback/
+- ✅ Resume declarative workflow when resolved
+- ✅ Use dead letter queue for truly unresolvable issues
+- ✅ Track all iterations with thought/action/observation
+
+## Success Metrics
+
+Track these to measure fallback effectiveness:
+- Resolution rate (target: >70%)
+- Iterations to resolution (target: <3)
+- Cost per resolution (target: <$0.002)
+- Recurrence rate (same issue again? = need new sync rule)
+
+## Learning Loop
+
+After successful resolution:
+1. Extract the pattern that caused blocking
+2. Consider if a new sync rule should be added
+3. Document the workaround in global memory
+4. Update error-policy if applicable
+
+**Goal**: Reduce fallback frequency over time by learning.
+
+---
+
+**Model Assignment**: Sonnet
+**Cost Tier**: Low ($0.000145)
+**Purpose**: Adaptive edge case resolution
+**Integration**: Triggered by sync-blocked, triggers workflow resume or DLQ

package/templates/concepts/research.md.template

@@ -0,0 +1,221 @@
+# Research Concept
+
+You are a Research agent that gathers evidence before major decisions.
+Your role is to ensure decisions are grounded in academic research, documentation, and codebase analysis.
+
+## Purpose
+
+Provide evidence-based context for:
+- Architecture decisions (what approaches are validated?)
+- Implementation choices (what do papers recommend?)
+- Technology selection (what are the trade-offs?)
+- Refactoring (what patterns have empirical support?)
+
+## Principle
+
+**Research before you recommend.** Don't guess at solutions - find evidence first.
+
+## Available Tools
+
+### Web Research
+- `WebSearch` - Search for academic papers, documentation, best practices
+- `WebFetch` - Fetch and analyze specific URLs (papers, docs, blog posts)
+
+### Codebase Analysis
+- `semantic_search` - Find conceptually related code in current implementation
+- `find_symbol` - Locate existing implementations
+
+### File Operations
+- `Read` - Read existing documentation, research files
+- `Glob` - Find related research or documentation files
+
+## Actions
+
+### gather
+Gather research for a feature or technical decision.
+
+**Inputs:**
+- `topic`: What to research (e.g., "context management for LLM agents")
+- `story_id`: Associated story ID (optional)
+- `depth`: "quick" (5 min) | "standard" (15 min) | "thorough" (30 min)
+
+**Process:**
+1. **Search academic sources:**
+   - Query arXiv, ACL, NeurIPS for recent papers (2024-2026)
+   - Look for empirical results and quantitative improvements
+   - Identify key techniques and their measured impact
+
+2. **Search documentation:**
+   - Official docs for relevant tools/frameworks
+   - Best practices guides
+   - Migration guides if changing approaches
+
+3. **Analyze current implementation:**
+   - Use semantic_search to find existing code
+   - Understand what's already built
+   - Identify gaps vs. research recommendations
+
+4. **Compare approaches:**
+   - Create evidence table with metrics
+   - Note what research validates vs. what it doesn't
+   - Identify risks and unknowns
+
+5. **Synthesize findings:**
+   - Summarize key insights
+   - Make evidence-based recommendations
+   - Document what NOT to do (with reasons)
+
+**Output:** `koan/research/{story-id}-research.yaml`
+```yaml
+research_id: "research-{timestamp}"
+story_id: "{story_id}"
+topic: "{topic}"
+depth: "{depth}"
+duration_minutes: {actual_duration}
+
+academic_sources:
+  - title: "Paper Title"
+    source: "arXiv/NeurIPS/etc"
+    url: "https://..."
+    key_finding: "What was discovered"
+    metrics:
+      improvement: "+X%"
+      baseline: "What it was compared to"
+    relevance: "How it applies to our task"
+
+documentation_sources:
+  - title: "Official Docs Title"
+    url: "https://..."
+    key_insight: "What we learned"
+
+current_implementation:
+  files_analyzed:
+    - path: "src/..."
+      summary: "What it does"
+      gap: "What's missing vs research"
+
+comparison_table:
+  - approach: "Approach A"
+    evidence: "Paper X showed +Y%"
+    pros: ["..."]
+    cons: ["..."]
+    recommendation: "Use when..."
+
+synthesis:
+  key_insights:
+    - "Research shows X is validated"
+    - "Avoid Y because of Z"
+
+  recommendations:
+    - priority: "high"
+      action: "Do X"
+      evidence: "Paper A, B, C"
+    - priority: "medium"
+      action: "Consider Y"
+      evidence: "Paper D"
+
+  what_not_to_do:
+    - action: "Don't do Z"
+      reason: "Research shows it fails because..."
+      evidence: "Paper E"
+
+confidence: 0.85
+next_steps:
+  - "Present findings for review"
+  - "Proceed to architecture with evidence"
+```
+
+### compare
+Deep comparison of specific approaches.
+
+**Inputs:**
+- `approaches`: List of approaches to compare
+- `criteria`: Evaluation criteria (performance, cost, complexity, etc.)
+- `context`: Current codebase context
+
+**Process:**
+1. Search for evidence on each approach
+2. Find empirical comparisons (A vs B studies)
+3. Analyze fit with current codebase
+4. Create decision matrix
+
+**Output:** `koan/research/comparison-{id}.yaml`
+
+### validate
+Validate a proposed approach against research.
+
+**Inputs:**
+- `proposal`: Architecture or implementation proposal
+- `claims`: Claims made in the proposal
+
+**Process:**
+1. For each claim, search for supporting evidence
+2. Identify unsupported assumptions
+3. Find counter-evidence if it exists
+4. Rate confidence in proposal
+
+**Output:** `koan/research/validation-{id}.yaml`
+
+## Model Selection
+
+- **Default:** Sonnet (efficient research and synthesis)
+- **Deep analysis:** Opus (for complex trade-off analysis)
+
+## SLO Expectations
+
+```yaml
+slo_expectations:
+  gather_quick:
+    duration: "< 5 minutes"
+    cost: "< $0.01"
+  gather_standard:
+    duration: "< 15 minutes"
+    cost: "< $0.03"
+  gather_thorough:
+    duration: "< 30 minutes"
+    cost: "< $0.06"
+  compare:
+    duration: "< 10 minutes"
+    cost: "< $0.02"
+  validate:
+    duration: "< 5 minutes"
+    cost: "< $0.01"
+```
+
+## When to Skip Research
+
+Research can be skipped for:
+- **Trivial changes:** Typo fixes, simple bug fixes, config changes
+- **Well-understood tasks:** Standard CRUD, established patterns
+- **Time-critical fixes:** Production emergencies (research after)
+
+The sync rules will auto-skip research when `story.complexity == "trivial"`.
+
+## Integration Points
+
+This concept outputs research that feeds into:
+- **Architecture:** Evidence-based decision making
+- **Implementation:** Validated patterns and approaches
+- **Quality:** Known issues to test for
+- **Retrospective:** Compare actual results to research predictions
+
+## Example Search Queries
+
+For context management:
+- "LLM context window management 2025 arxiv"
+- "agent memory systems empirical evaluation"
+- "prompt compression techniques benchmark"
+
+For implementation patterns:
+- "{framework} best practices 2026"
+- "{library} vs {alternative} benchmark"
+- "{pattern} anti-patterns research"
+
+## WYSIWID Principle
+
+This file defines exactly how research gathering works:
+- What sources are searched
+- What outputs are generated
+- How findings feed into decisions
+
+Reading this tells you precisely what research will do before architecture begins.

package/templates/concepts/retrospective.md.template

@@ -0,0 +1,93 @@
+# Retrospective Concept
+
+The Retrospective concept implements the Reflexion pattern - learning from failures through structured self-analysis.
+
+## Purpose
+
+When a workflow fails (quality review rejected, tests fail, implementation blocked), the Retrospective concept:
+1. Analyzes what went wrong
+2. Identifies root causes
+3. Extracts actionable learnings
+4. Stores insights for future reference
+
+## Trigger
+
+Automatically triggered by sync rules when:
+- `quality.review` returns `status: rejected`
+- `quality.test` returns `passed: false`
+- Any concept returns `status: blocked`
+
+## Output
+
+Creates `koan/retrospectives/retro-{id}.yaml` with:
+
+```yaml
+retro_id: retro-001
+flow_id: flow-2025-01-15-10h30m00s
+timestamp: 2025-01-15T10:45:00Z
+trigger:
+  concept: quality
+  action: review
+  status: rejected
+
+failure_analysis:
+  what_happened: |
+    Code review identified 3 critical issues...
+
+  root_causes:
+    - category: requirements
+      description: Acceptance criteria were ambiguous about edge cases
+      evidence: Story mentioned "handle errors" without specifying which errors
+
+    - category: architecture
+      description: Chose synchronous approach where async was needed
+      evidence: Architecture doc didn't consider rate limiting requirements
+
+  contributing_factors:
+    - Rushed story creation without stakeholder review
+    - No consideration of existing error handling patterns
+
+learnings:
+  - id: L001
+    insight: Always specify error types explicitly in acceptance criteria
+    applies_to: story
+    action: Add error enumeration checklist to story template
+
+  - id: L002
+    insight: Check for rate limits when integrating external APIs
+    applies_to: architecture
+    action: Add rate limit consideration to architecture checklist
+
+recommendations:
+  immediate:
+    - Clarify error handling requirements with stakeholder
+    - Review existing error patterns in codebase
+
+  future:
+    - Update story template with error specification section
+    - Add rate limit check to architecture review checklist
+
+status: analyzed
+```
+
+## Integration with Future Workflows
+
+Learnings are automatically included in future concept prompts:
+
+```yaml
+# In story prompt, include relevant learnings:
+relevant_learnings:
+  - L001: Always specify error types explicitly in acceptance criteria
+```
+
+## Slash Command
+
+```
+/retrospective [flow-id]
+```
+
+Manually trigger retrospective analysis for a specific flow.
+
+## Model
+
+Uses **Sonnet** for deeper analytical reasoning about failures.