@dragonflymcp/plugin 1.0.0

package/templates/commands/sync.md.template

@@ -0,0 +1,321 @@
+Evaluate synchronization rules and optionally execute the next step in the workflow.
+
+This command reads the latest concept outputs, evaluates sync rules, and shows
+what would trigger next. Useful for manual workflow control and debugging.
+
+## Usage
+
+```
+/sync                    # Show what would trigger next
+/sync --execute          # Evaluate and execute matched rules
+/sync --dry-run          # Show evaluation details without executing
+```
+
+## Process
+
+When you run this command, you should:
+
+1. **Find Latest Outputs**
+   - Scan `koan/*/` directories for most recent files
+   - Identify the last completed concept action
+
+2. **Read State Files with Progressive Disclosure + Cache**
+   - **Phase 2 Optimization**: Use cache for all state file reads (5ms vs 100ms)
+   - **First**: Check cache for concept output (95% hit rate)
+   - **If cached**: Return immediately (sub-10ms access)
+   - **If not cached**: Read ONLY the summary section (first 5 lines)
+   - **Summary provides**: id, status, summary line with key info
+   - **Cost**: ~100 tokens per file (Phase 1) + cache benefits (Phase 2)
+   - **Then**: If sync rule evaluation needs details, read full file
+   - Combined benefit: 95% token reduction + 95% cache hit rate = 5x faster
+
+3. **Read Synchronization Rules**
+   - Load `.claude/synchronizations/feature-development.yaml`
+   - Parse all synchronization rules
+
+4. **Evaluate Rules**
+   - For each sync rule, check:
+     - Does `when` match the latest action?
+     - Does `where` query evaluate to true? (use summary first)
+     - If summary has needed info, don't load full file
+     - Only load full file if evaluation needs detailed fields
+   - Show which rules match and why
+
+5. **Execute (if --execute)**
+   - Invoke the `then` concept
+   - Continue workflow automatically
+
+### Progressive Disclosure Example
+
+**Traditional Approach** (expensive):
+```
+Read koan/stories/story-001.yaml         (2000 tokens)
+Read koan/architecture/arch-001.yaml     (3000 tokens)
+Read koan/implementations/impl-001.yaml  (2500 tokens)
+Read koan/reviews/review-001.yaml        (2000 tokens)
+────────────────────────────────────────────────────
+Total: 9500 tokens just to check status
+```
+
+**Progressive Disclosure** (efficient):
+```
+Read story-001.yaml summary (5 lines)       (100 tokens)
+Read arch-001.yaml summary (5 lines)        (120 tokens)
+Read impl-001.yaml summary (5 lines)        (100 tokens)
+Read review-001.yaml summary (5 lines)      (100 tokens)
+────────────────────────────────────────────────────
+Total: 420 tokens to check status
+Savings: 95% (420 vs 9500 tokens)
+```
+
+If sync rule needs details (rare), then load full file.
+
+## Example: Show Next Step
+
+```
+User: /sync
+
+You: Evaluating synchronization rules...
+
+Last completed action:
+  Concept: story
+  Action: create
+  Status: completed
+  Output: koan/stories/story-001.yaml
+
+Checking synchronization rules:
+
+✓ story-to-arch
+  When: story.create completed ✓
+  Where: story.status == 'ready' ✓
+        story.acceptance_criteria.length > 0 ✓
+  Then: architecture.design (model: sonnet)
+  Status: MATCHED
+
+✗ arch-to-impl
+  When: architecture.design completed ✗
+  Status: SKIPPED (no architecture output yet)
+
+✗ impl-to-quality
+  When: implementation.generate completed ✗
+  Status: SKIPPED (no implementation output yet)
+
+Next step: architecture.design
+Model: sonnet
+Estimated cost: $0.015
+
+Run `/sync --execute` to continue workflow automatically.
+```
+
+## Example: Execute Next Step
+
+```
+User: /sync --execute
+
+You: Evaluating synchronization rules...
+
+Matched: story-to-arch
+  Next: architecture.design
+
+Executing architecture concept...
+
+[Invoke Task tool → architecture concept → model: sonnet]
+
+✓ Architecture created: arch-001
+  Approach: Provider pattern with Confluence API client
+  Decisions: 5 documented
+  Risks: 3 (all mitigated)
+  Cost: $0.015
+
+Evaluating next synchronizations...
+
+Matched: arch-to-impl
+  Next: implementation.generate
+
+Continue? (yes/no)
+```
+
+## Example: Dry Run with Details
+
+```
+User: /sync --dry-run
+
+You: Dry run - showing evaluation details...
+
+Reading state files (progressive disclosure):
+  ✓ koan/stories/story-001.yaml (summary only - 100 tokens)
+  ✓ .claude/synchronizations/feature-development.yaml
+
+Latest action: story.create (completed)
+
+Evaluating rule: story-to-arch
+  Condition: when.concept=='story' ✓
+  Condition: when.action=='create' ✓
+  Condition: when.status=='completed' ✓
+
+  Reading story-001.yaml summary:
+    story_id: "story-001"
+    status: "ready" ✓
+    summary: "Custom Terraform provider - ready, 9 criteria, 0 ambiguities"
+
+  Query: story.status == 'ready' AND story.acceptance_criteria.length > 0
+  Result: TRUE ✓ (inferred from summary - "9 criteria")
+
+  Would invoke:
+    Concept: architecture
+    Action: design
+    Model: sonnet
+    Inputs:
+      - story_id: story-001
+      - Need full story details → Loading full file now (2000 tokens)
+      - context: "Develop a custom Terraform provider..."
+      - acceptance_criteria: [9 items]
+
+No execution (dry-run mode).
+
+Token efficiency: 100 tokens for evaluation + 2000 for full load = 2100 total
+vs 2000 tokens if we loaded full file immediately
+```
+
+## Query Evaluation Logic with Progressive Disclosure
+
+The sync engine evaluates `where` queries by:
+
+1. **Reading state file summaries first**
+   ```yaml
+   # koan/stories/story-001.yaml (summary only - first 5 lines)
+   story_id: "story-001"
+   status: "ready"
+   title: "Custom Terraform Provider"
+   summary: "Custom provider - ready, 9 criteria, 0 ambiguities, auth required"
+   ```
+
+2. **Parsing query expressions**
+   ```
+   story.status == 'ready' AND
+   story.acceptance_criteria.length > 0
+   ```
+
+3. **Evaluating conditions from summary**
+   - `story.status` → read from summary → "ready"
+   - `== 'ready'` → compare → TRUE
+   - `.length` → infer from summary "9 criteria" → 9
+   - `> 0` → compare → TRUE
+   - `AND` → logical operation → TRUE
+
+4. **Load full file only if needed**
+   - If query needs fields not in summary (rare), load full file
+   - Example: Query checks specific acceptance_criteria text
+   - Most sync rules only need status, id → use summary only
+
+5. **Determining match**
+   - All conditions TRUE → rule matches
+   - Invoke `then` action
+
+### Query Optimization
+
+**Can evaluate from summary** (95% of queries):
+```
+story.status == 'ready'
+architecture.estimated_risk != 'high'
+implementation.status == 'completed'
+review.status == 'approved'
+```
+
+**Needs full file** (rare):
+```
+story.acceptance_criteria[0].text.contains("OAuth")
+architecture.decisions.filter(d => d.rationale.includes("security"))
+```
+
+## Supported Query Operators
+
+```
+Comparison:
+  ==, !=        Equal, not equal
+  <, >, <=, >=  Less than, greater than
+
+Logical:
+  AND, OR, NOT  Boolean logic
+
+Properties:
+  .field        Access field
+  .length       Count array items
+  .filter()     Array filtering (basic)
+
+Functions:
+  string.contains("text")
+  string.startsWith("prefix")
+  array.includes("item")
+```
+
+## Use Cases
+
+### 1. Check Current Workflow State
+```
+/sync --dry-run
+```
+See what step you're on and what's next.
+
+### 2. Continue Workflow After Manual Work
+```
+# You manually fixed something
+/sync --execute
+```
+Resume automatic workflow.
+
+### 3. Debug Why Workflow Stopped
+```
+/sync
+```
+See which rule didn't match and why.
+
+### 4. Preview Next Step Before Executing
+```
+/sync  # Review
+/sync --execute  # Proceed
+```
+
+## Integration with Other Commands
+
+```bash
+# Start workflow
+/workflow "Add feature"
+
+# Pause and check status
+/sync
+
+# Resume
+/sync --execute
+
+# See full history
+/trace <flow-id>
+
+# Check costs
+/costs
+```
+
+## Troubleshooting
+
+**Rule not matching?**
+```
+/sync --dry-run
+```
+Shows exact evaluation of each condition.
+
+**Want to skip a step?**
+Manually invoke the next concept, then `/sync` to continue.
+
+**Multiple rules match?**
+Execute them in order defined in YAML.
+
+**Blocked by condition?**
+Fix the state file, then `/sync --execute` again.
+
+## Architecture Note
+
+The sync engine is **Claude itself** reading and interpreting YAML rules.
+No external process needed - pure .claude functionality.
+The declarative rules guide Claude's decision-making automatically.
+
+This embodies WYSIWID: Read the sync rules to predict behavior.

package/templates/commands/task.md.template

@@ -0,0 +1,86 @@
+# /task - Task Management Command
+
+Manage tasks for GitOps-based Kanban tracking. Tasks are stored in `koan/tasks/` and can be visualized in Kanflow.
+
+## Usage
+
+```
+/task create "Task title" [--type feature|bug|chore|spike] [--priority low|medium|high|critical]
+/task list [--status todo|in_progress|done|blocked] [--type feature|bug|chore]
+/task update <task-id> --status <new-status>
+/task show <task-id>
+/task delete <task-id>
+```
+
+## Actions
+
+### Create Task
+Create a new task in `koan/tasks/`:
+
+```yaml
+# Generated: koan/tasks/task-{id}.yaml
+task_id: "task-001"
+title: "Implement user authentication"
+status: "todo"
+priority: "high"
+type: "feature"
+```
+
+### List Tasks
+Display tasks filtered by status or type:
+
+```
+/task list --status in_progress
+/task list --type bug
+/task list  # All tasks
+```
+
+### Update Task Status
+Progress a task through the workflow:
+
+```
+/task update task-001 --status in_progress
+/task update task-001 --status done
+```
+
+### Show Task Details
+View full task information including subtasks and provenance:
+
+```
+/task show task-001
+```
+
+## GitOps Flow
+
+1. Tasks are YAML files in `koan/tasks/`
+2. Status changes update the YAML file
+3. Kanflow polls/watches for changes
+4. Dashboard reflects current state
+
+## Integration with Zen Workflow
+
+Tasks can link to Zen workflow artifacts:
+
+```yaml
+provenance:
+  story_id: "story-001"
+  architecture_id: "arch-001"
+```
+
+## Subtask Management
+
+Add subtasks for granular progress tracking:
+
+```
+/task subtask task-001 add "Design API endpoints"
+/task subtask task-001 complete sub-001
+```
+
+## Labels and Filtering
+
+Add labels for organization:
+
+```
+/task label task-001 add "backend" "api"
+/task list --label backend
+```

package/templates/commands/trace.md.template

@@ -0,0 +1,86 @@
+Trace provenance chain for an action, story, or flow.
+
+When the user runs this command, you should:
+
+1. Read the provenance files from koan/provenance/
+2. Build the complete chain of actions
+3. Show the workflow visually with costs and timing
+
+Usage:
+- `/trace story-001` - Trace all actions for a story
+- `/trace flow-abc123` - Trace all actions in a flow
+- `/trace act-042` - Trace from a specific action
+
+Process:
+1. Identify what the user wants to trace (story ID, flow ID, or action ID)
+2. Read relevant provenance files from koan/provenance/
+3. Build the dependency chain (triggered_by relationships)
+4. Present in chronological order with:
+   - Action ID and timestamp
+   - Concept and model used
+   - Status and cost
+   - Triggered by relationship
+   - Synchronization rule used
+
+Example output:
+```
+Tracing flow: flow-2025-11-09-20h00m00s
+Story: story-001 "Add dark mode support"
+Total cost: $0.0165
+Duration: 15m 30s
+
+Timeline:
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+[20:00:00] act-001 | story.create | sonnet | $0.000175
+  Status: completed
+  Output: story-001 (status: ready)
+  Triggered by: user
+  ↓
+
+[20:05:00] act-002 | architecture.design | sonnet | $0.015000 ⭐
+  Status: completed
+  Output: arch-001 (approach: Context + CSS-in-JS)
+  Triggered by: act-001 via story-to-arch
+  ↓
+
+[20:10:00] act-003 | implementation.generate | sonnet | $0.000175
+  Status: completed
+  Output: impl-001 (5 files, 198 lines)
+  Triggered by: act-002 via arch-to-impl
+  ↓
+
+[20:15:00] act-004 | quality.review | sonnet | $0.000175
+  Status: completed (approved)
+  Output: review-001 (1 low-severity issue)
+  Triggered by: act-003 via impl-to-quality-review
+  │
+[20:16:00] act-005 | quality.test | sonnet | $0.000175
+  Status: completed (18/18 passed)
+  Output: test-001 (94% coverage)
+  Triggered by: act-003 via impl-to-quality-test
+  ↓
+
+[20:20:00] act-006 | version.commit | sonnet | $0.000175
+  Status: completed
+  Output: commit abc123def
+  Triggered by: act-004 via quality-to-version
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Summary:
+- Total actions: 6
+- Model usage: 1 sonnet, 5 sonnet
+- Total cost: $0.0165
+- Sonnet cost: $0.015 (91% of total)
+- Cost efficiency: 83% savings vs all-sonnet
+
+Synchronizations triggered:
+- story-to-arch
+- arch-to-impl
+- impl-to-quality-review (parallel)
+- impl-to-quality-test (parallel)
+- quality-to-version
+```
+
+This command demonstrates the power of provenance tracking - you can see exactly how the system arrived at the current state and understand the cost/benefit of each decision.

package/templates/commands/visualize.md.template

@@ -0,0 +1,216 @@
+# Visualize Command
+
+Generate visual diagrams from WYSIWID synchronization rules and workflow state.
+
+## Usage
+
+```
+/visualize [type] [options]
+```
+
+## Types
+
+### `workflow` (default)
+Generate a Mermaid flowchart of the synchronization rules.
+
+```
+/visualize workflow
+```
+
+### `state`
+Visualize the current state of a flow.
+
+```
+/visualize state flow-2025-01-15-10h30m00s
+```
+
+### `concepts`
+Show relationships between concepts.
+
+```
+/visualize concepts
+```
+
+### `memory`
+Visualize the memory graph.
+
+```
+/visualize memory
+```
+
+## Process
+
+When you run this command:
+
+1. **Read Configuration**
+   - Load `.claude/synchronizations/*.yaml`
+   - Parse sync rules and conditions
+
+2. **Generate Diagram**
+   - Convert rules to Mermaid syntax
+   - Add styling based on concept types
+   - Include conditions as labels
+
+3. **Output**
+   - Display Mermaid code block
+   - Can be rendered in any Mermaid-compatible viewer
+
+## Example Output
+
+### Workflow Visualization
+
+```mermaid
+%%{init: {'theme': 'base', 'themeVariables': { 'primaryColor': '#4a90d9'}}}%%
+flowchart LR
+    subgraph Capture
+        S[Story<br/>Sonnet]
+    end
+
+    subgraph Design
+        P[Planning<br/>Sonnet]
+        A[Architecture<br/>Opus]
+    end
+
+    subgraph Build
+        I[Implementation<br/>Sonnet]
+    end
+
+    subgraph Verify
+        V1[Verification 1<br/>Sonnet]
+        V2[Verification 2<br/>Sonnet]
+        VC[Consensus<br/>Sonnet]
+    end
+
+    subgraph Quality
+        QR[Review<br/>Sonnet]
+        QT[Test<br/>Sonnet]
+    end
+
+    subgraph Release
+        VE[Version<br/>Sonnet]
+    end
+
+    subgraph Learn
+        R[Retrospective<br/>Sonnet]
+    end
+
+    S -->|"ready & complex"| P
+    S -->|"ready & simple"| A
+    P -->|"ready"| A
+    A -->|"risk != low"| V1
+    A -->|"risk == low"| I
+    V1 --> V2
+    V2 --> VC
+    VC -->|"approved"| I
+    VC -->|"blocked"| A
+    I --> QR & QT
+    QR & QT -->|"passed"| VE
+    QR -->|"rejected"| R
+    QT -->|"failed"| R
+    R -.->|"learnings"| S
+
+    class sonnet fill:#90EE90
+    classDef sonnet fill:#87CEEB
+    classDef opus fill:#DDA0DD
+
+    class sonnet
+    class P,V1,V2,R sonnet
+    class A opus
+```
+
+### State Visualization
+
+```mermaid
+%%{init: {'theme': 'base'}}%%
+flowchart TD
+    subgraph "flow-2025-01-15-10h30m00s"
+        S[Story ✓<br/>story-042]
+        A[Architecture ✓<br/>arch-042]
+        I[Implementation ⏳<br/>impl-042]
+        Q[Quality<br/>pending]
+        V[Version<br/>pending]
+    end
+
+    S --> A --> I -.-> Q -.-> V
+
+    classDef completed fill:#90EE90
+    classDef inprogress fill:#FFD700
+    classDef pending fill:#D3D3D3
+
+    class S,A completed
+    class I inprogress
+    class Q,V pending
+```
+
+### Concepts Visualization
+
+```mermaid
+%%{init: {'theme': 'base'}}%%
+flowchart TB
+    subgraph Core["Core Concepts"]
+        story["Story<br/>Requirements"]
+        arch["Architecture<br/>Design"]
+        impl["Implementation<br/>Code"]
+        quality["Quality<br/>Verification"]
+        version["Version<br/>Release"]
+    end
+
+    subgraph Intelligence["Intelligence Layer"]
+        plan["Planning<br/>Chain-of-Thought"]
+        verify["Verification<br/>Multi-Agent"]
+        retro["Retrospective<br/>Reflexion"]
+        tot["Tree-of-Thoughts<br/>Exploration"]
+    end
+
+    subgraph Memory["Memory Layer"]
+        semantic["Semantic Memory<br/>Long-term"]
+        checkpoint["Checkpoints<br/>Session"]
+        learnings["Learnings<br/>Active"]
+    end
+
+    story --> plan
+    plan --> arch
+    arch --> verify
+    verify --> impl
+    impl --> quality
+    quality --> version
+
+    quality -.->|"failure"| retro
+    retro -.->|"insights"| learnings
+    learnings -.->|"inform"| story
+
+    arch -.->|"complex"| tot
+    tot -.->|"decision"| arch
+
+    story --> semantic
+    arch --> semantic
+    impl --> semantic
+
+    checkpoint --> story & arch & impl
+```
+
+## Styling Guide
+
+| Concept | Color | Model |
+|---------|-------|-------|
+| Story | Green | Sonnet |
+| Architecture | Purple | Opus |
+| Implementation | Green | Sonnet |
+| Quality | Green | Sonnet |
+| Version | Green | Sonnet |
+| Planning | Blue | Sonnet |
+| Verification | Blue | Sonnet |
+| Retrospective | Blue | Sonnet |
+
+## Integration
+
+The visualizations can be:
+1. Displayed in the terminal (as Mermaid code)
+2. Rendered in VS Code with Mermaid extension
+3. Exported to PNG/SVG using mermaid-cli
+4. Embedded in documentation
+
+## Automatic Updates
+
+When sync rules change, re-run `/visualize workflow` to see the updated flow.
+This ensures the diagram always matches the actual behavior (WYSIWID).