@dragonflymcp/plugin 1.0.0

package/templates/commands/workflow.md.template

@@ -0,0 +1,375 @@
+Execute a complete feature workflow automatically from story to deployment.
+
+This command runs the full WYSIWID workflow by evaluating synchronization rules
+after each concept completes and automatically invoking the next concept.
+
+## Usage
+
+```
+/workflow "Add OAuth authentication"
+/workflow deep "Feature requiring careful analysis"
+```
+
+## Reasoning Modes
+
+### Standard Mode (default)
+- Architecture: Opus (deep reasoning)
+- All other concepts: Sonnet
+
+### Deep Mode (`deep` prefix)
+When the description starts with "deep":
+- **Architecture**: Opus with tree-of-thought exploration
+- **Verification**: Multi-pass with Opus for consensus
+- **Story**: Enhanced requirements analysis
+- **Implementation**: More thorough code review before generation
+
+**Detection:**
+```python
+if description.lower().startswith("deep"):
+    mode = "deep"
+    description = description.split(" ", 1)[1]  # Remove prefix
+elif description.lower().startswith("quick"):
+    mode = "quick"
+    description = description.split(" ", 1)[1]
+else:
+    mode = "standard"
+```
+
+**Deep Mode Differences:**
+| Concept | Standard | Deep |
+|---------|----------|------|
+| Story | Sonnet | Sonnet + deeper analysis |
+| Architecture | Opus (5 steps) | Opus + tree-of-thought (10 steps) |
+| Verification | Sonnet (if triggered) | Opus + 3-pass consensus |
+| Implementation | Sonnet | Sonnet + pre-review |
+| Quality | Sonnet | Sonnet + extended coverage |
+
+## Process
+
+When you run this command, you should:
+
+1. **Recall Relevant Memories** (automatic, fast)
+   - Extract keywords from the feature description
+   - Search `koan/memory/semantic/*.yaml` for relevant memories:
+     - Architecture patterns that match keywords
+     - Conventions related to the feature area
+     - Past patterns from similar features
+   - Display relevant memories (if any):
+     ```
+     📚 Relevant memories found:
+     - [architecture] "Authentication uses JWT with RS256" (high)
+     - [patterns] "API endpoints follow /api/v1/{resource} convention"
+     ```
+   - Pass memories as context to subsequent concepts
+
+2. **Create Story** (Sonnet)
+   - Invoke Story concept to capture requirements
+   - Include relevant memories as context
+   - Wait for story creation
+   - Read `koan/stories/story-{id}.yaml`
+
+3. **Evaluate Synchronizations**
+   - Read `.claude/synchronizations/feature-development.yaml`
+   - Check `story-to-arch` rule:
+     - `when`: story.create completed
+     - `where`: story.status == 'ready' AND criteria.length > 0
+     - `then`: architecture.design
+
+4. **Continue Workflow Automatically**
+   - After each concept completes, evaluate sync rules
+   - Invoke next concept if rules match
+   - **Auto-remember architecture decisions** after architecture phase
+   - Track flow with flow_id
+   - Log provenance for each step
+
+5. **Complete Workflow Phases**:
+   - Story (Sonnet) → Architecture (Opus) → Implementation (Sonnet) → Quality (Sonnet 2x parallel) → Version (Sonnet)
+   - **Auto-remember workflow summary** after version.commit
+
+6. **Invoke Subagents Using Task Tool**:
+   Each concept MUST be invoked via the Task tool with appropriate subagent_type:
+   ```
+   Task tool invocation:
+     subagent_type: "story-concept"
+     model: "sonnet"
+     prompt: "Create story for: {description}"
+
+   Task tool invocation:
+     subagent_type: "architecture-concept"
+     model: "opus"  # Always Opus for architecture
+     prompt: "Design architecture for story: {story_id}"
+
+   # ... continue for each concept
+   ```
+
+7. **Handle Parallel Execution**:
+   - If multiple rules match with `parallel: true`, invoke all in single message
+   - Wait for all parallel actions to complete
+   - Evaluate next sync rules with all results
+
+## Synchronization Evaluation Logic
+
+For each completed concept action:
+
+```python
+# Pseudocode for sync evaluation
+def evaluate_syncs(completed_concept, completed_action):
+    syncs = read_yaml(".claude/synchronizations/*.yaml")
+
+    for sync in syncs:
+        # Check when condition
+        if sync.when.concept == completed_concept and \
+           sync.when.action == completed_action and \
+           sync.when.status == "completed":
+
+            # Read the output state
+            state = read_latest_output(completed_concept)
+
+            # Evaluate where query
+            if evaluate_query(sync.where.query, state):
+                # Execute then action
+                invoke_concept(
+                    concept=sync.then.concept,
+                    action=sync.then.action,
+                    model=sync.then.model,
+                    inputs=resolve_variables(sync.then.inputs, state)
+                )
+
+                return sync.id  # Return which sync triggered
+
+    return None  # No sync matched
+```
+
+## Query Evaluation
+
+Parse simple expressions from YAML:
+
+- `story.status == 'ready'` → Read story YAML, check status field
+- `architecture.risk != 'high'` → Read architecture YAML, check risk
+- `criteria.length > 0` → Count array items in acceptance_criteria
+
+## Example Execution
+
+```
+User: /workflow "Add dark mode support"
+
+You: I'll execute the complete feature workflow.
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+Recalling Relevant Memories
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+📚 Found 2 relevant memories:
+- [patterns] "Theme switching uses React Context" (high)
+- [conventions] "CSS variables for color tokens" (medium)
+
+These will be included as context throughout the workflow.
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+Phase 1: Story Capture (Sonnet)
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+[Invoke Task tool → story concept → model: sonnet]
+
+✓ Story created: story-042
+  Status: ready
+  Acceptance criteria: 4 defined
+  Memory context: 2 items applied
+  Cost: $0.003
+
+Evaluating synchronizations...
+✓ Matched: story-to-arch
+  Condition: status=='ready' AND criteria.length>0
+  Next: architecture.design (Opus)
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+Phase 2: Architecture Design (Opus)
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+[Invoke Task tool → architecture-concept → model: opus]
+
+✓ Architecture created: arch-042
+  Approach: Context + CSS-in-JS
+  Decisions: 3 documented
+  Risks: 2 (both mitigated)
+  Risk level: low
+  Cost: $0.015
+
+💾 Auto-remembered 2 architecture decisions:
+- "Dark mode uses React Context for theme state"
+- "CSS-in-JS with CSS variables for color tokens"
+
+Evaluating synchronizations...
+✓ Matched: arch-to-impl
+  Condition: decisions.length>0 AND risk!='high'
+  Next: implementation.generate (Sonnet)
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+Phase 3: Implementation (Sonnet)
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+[Invoke Task tool → implementation concept → model: sonnet]
+
+✓ Implementation created: impl-042
+  Files changed: 5 (198 lines)
+  Tests created: 2
+  Status: completed
+  Cost: $0.003
+
+Evaluating synchronizations...
+✓ Matched: impl-to-quality-review
+  Next: quality.review (Sonnet)
+✓ Matched: impl-to-quality-test
+  Next: quality.test (Sonnet)
+
+Both rules have parallel:true → executing simultaneously...
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+Phase 4: Quality Assurance (Sonnet) - PARALLEL EXECUTION
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+[Invoke 2x Task tools in single message → both quality actions]
+
+✓ Review completed: review-042
+  Status: approved
+  Issues: 1 low-severity
+  Cost: $0.003
+
+✓ Tests completed: test-042
+  Passed: 18/18
+  Coverage: 94%
+  Cost: $0.003
+
+Evaluating synchronizations...
+✓ Matched: quality-to-version
+  Condition: review.status=='approved' AND tests.passed
+  Next: version.commit (Sonnet)
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+Phase 5: Version Control (Sonnet)
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+[Invoke Task tool → version concept → model: sonnet]
+
+✓ Commit created: abc123def
+  Branch: feature/story-042-dark-mode
+  Files: 5
+  Message: "feat(theme): add dark mode support"
+  Cost: $0.003
+
+Evaluating synchronizations...
+No further syncs matched. Workflow complete!
+
+💾 Auto-remembered workflow summary:
+- Feature: "Add dark mode support"
+- Approach: "React Context + CSS-in-JS"
+- Key files: 5 changed (ThemeContext.tsx, useTheme.ts, etc.)
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+Workflow Complete ✅
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Flow: flow-2025-11-09-22h00m00s
+Total actions: 7
+Total cost: ~$0.030
+Time: 18 minutes
+Memories created: 3
+
+Breakdown:
+- Story (Sonnet):          $0.003   (10%)
+- Architecture (Opus):     $0.015   (50%)
+- Implementation (Sonnet): $0.003   (10%)
+- Quality 2x (Sonnet):     $0.006   (20%)
+- Version (Sonnet):        $0.003   (10%)
+
+Next steps:
+- Review code: See impl-042
+- View trace: /trace flow-2025-11-09-22h00m00s
+- Push changes: git push origin feature/story-042-dark-mode
+```
+
+## Error Handling
+
+If a concept fails or returns blocked status:
+
+```
+✗ Architecture blocked: arch-042
+  Blocker: Unclear requirements for authentication flow
+
+Evaluating synchronizations...
+✓ Matched: arch-blocked-to-story-clarify
+  Next: story.clarify
+
+Pausing workflow for clarification...
+```
+
+## Manual Intervention
+
+At any point, you can:
+- `/trace <flow-id>` - See progress
+- `/sync` - Manually evaluate and trigger next step
+- Continue the workflow manually if needed
+
+## Parallel Execution
+
+**When multiple sync rules match with `parallel: true`**:
+
+1. **Detection**: Check if multiple rules match same completion
+   ```yaml
+   impl-to-quality-review: parallel: true
+   impl-to-quality-test:   parallel: true
+   ```
+
+2. **Execution**: Invoke all concepts in **single message**
+   ```
+   Send ONE message with multiple Task tool calls:
+   - Task(quality.review, model=sonnet)
+   - Task(quality.test, model=sonnet)
+   ```
+
+3. **Wait**: Collect all results before proceeding
+
+4. **Benefits**:
+   - 50% faster (review+test run simultaneously, not sequentially)
+   - Same cost (both actions run anyway)
+   - Better resource utilization
+
+**Requirements for Safe Parallelization**:
+- ✅ Actions read from same completed concept
+- ✅ Neither action modifies what the other reads
+- ✅ Neither depends on the other's output
+- ✅ Both can execute independently
+
+**Example**: Quality review and test are perfect candidates:
+- Both read from completed implementation
+- Neither modifies implementation state
+- Neither needs the other's results
+- Both produce independent quality reports
+
+## Performance
+
+Expected duration by feature complexity:
+- Simple feature: 5-10 minutes (3-4 min with parallel quality)
+- Medium feature: 15-20 minutes (13-16 min with parallel quality)
+- Complex feature: 30-45 minutes (26-39 min with parallel quality)
+
+Most time spent in Architecture phase (deep reasoning).
+
+**Parallel Quality Impact**:
+- Traditional: Impl (3min) → Review (2min) → Test (2min) = 7min for impl+quality
+- With Parallel: Impl (3min) → Review+Test (2min) = 5min for impl+quality
+- **Savings**: 2 minutes per feature (29% faster)
+
+## Cost Tracking
+
+Each workflow creates complete provenance:
+- See `koan/provenance/flows/flow-{id}.yaml`
+- Track cumulative cost
+- Analyze model usage
+- Use `/costs` for aggregated analysis
+
+## WYSIWID in Action
+
+The synchronization rules ARE the workflow logic.
+Read `.claude/synchronizations/*.yaml` to see exactly what will happen.
+What you see (the rules) is what it does (the execution).

package/templates/concepts/README.md

@@ -0,0 +1,329 @@
+# Zen Concepts
+
+Concepts are independent, stateful services that perform specific actions. They are the building blocks of the Zen WYSIWID architecture.
+
+## Core Principle: Concepts Never Call Concepts
+
+This is the foundational rule of Zen:
+
+❌ **Wrong**: Architecture concept calls Implementation concept
+✅ **Right**: Architecture completes → Synchronization triggers Implementation
+
+This enforces true modularity and makes system behavior predictable from reading synchronization rules.
+
+## The 10 Concepts
+
+### 1. Story (Sonnet) - Requirements Capture
+- **File**: `story.md`
+- **Model**: Sonnet
+- **Purpose**: Capture and validate user requirements
+- **Actions**: create, validate, query
+- **State**: `koan/stories/`
+- **Never knows**: How to implement, architect, or test
+
+**When to use**: User requests a new feature or bug fix
+
+### 2. Architecture (Opus) - System Design
+- **File**: `architecture.md`
+- **Model**: Opus ⭐
+- **Purpose**: Design technical solutions and make architectural decisions
+- **Actions**: design, evaluate, revise, clarify
+- **State**: `koan/architecture/`
+- **Never knows**: How to write code or run tests
+
+**When to use**: Story is validated and ready for design
+
+**Why Opus?**: Requires deep reasoning, trade-off analysis, pattern synthesis
+
+### 3. Implementation (Sonnet) - Code Generation
+- **File**: `implementation.md`
+- **Model**: Sonnet
+- **Purpose**: Generate code from technical specifications
+- **Actions**: generate, refactor, document
+- **State**: `koan/implementations/`
+- **Never knows**: Architectural decisions (follows specs exactly)
+
+**When to use**: Architecture is complete and risk is acceptable
+
+**Why Sonnet?**: Clear specs make implementation straightforward
+
+### 4. Quality (Sonnet) - Review & Testing
+- **File**: `quality.md`
+- **Model**: Sonnet
+- **Purpose**: Review code, run tests, validate acceptance criteria
+- **Actions**: review, test, validate
+- **State**: `koan/reviews/`
+- **Never knows**: How to fix issues (reports them for Implementation)
+
+**When to use**: Implementation is complete
+
+**Why Sonnet?**: Pattern matching and rule-based validation
+
+### 5. Version (Sonnet) - Git Operations
+- **File**: `version.md`
+- **Model**: Sonnet
+- **Purpose**: Manage version control, commits, branches
+- **Actions**: branch, commit, push, tag
+- **State**: `koan/versions/`
+- **Never knows**: Code quality (commits only after Quality approves)
+
+**When to use**: Quality review passes
+
+**Why Sonnet?**: Straightforward git commands
+
+### 6. Context (Sonnet) - Context Window Management
+- **File**: `context.md`
+- **Model**: Sonnet
+- **Purpose**: Manage Claude Code context window
+- **Actions**: snapshot, estimate, compress, preserve
+- **State**: `koan/session-state/`
+- **Never knows**: Feature logic (focuses on context health)
+
+**When to use**: Workflow boundaries, context warnings
+
+**Why Sonnet?**: Token counting and compression
+
+### 7. Code-Analysis (Sonnet) - Codebase Context
+- **File**: `code-analysis.md`
+- **Model**: Sonnet
+- **Purpose**: Gather codebase context via MCP tools
+- **Actions**: context
+- **State**: `koan/code-analysis/`
+- **Never knows**: How to design or implement (gathers context only)
+
+**When to use**: Before architecture, to understand existing patterns
+
+**Why Sonnet?**: MCP tool orchestration is straightforward
+
+### 8. Verification (Sonnet) - Multi-Pass Review
+- **File**: `verification.md`
+- **Model**: Sonnet
+- **Purpose**: Independent multi-pass verification for accuracy
+- **Actions**: verify_architecture, verify_implementation
+- **State**: `koan/verification/`
+- **Never knows**: How to fix issues (reports findings only)
+
+**When to use**: High-risk architectures, complex implementations
+
+**Why Sonnet?**: Pattern matching and independent review
+
+### 9. Security (Sonnet) - Security Assurance
+- **File**: `security.md`
+- **Model**: Sonnet
+- **Purpose**: Threat modeling, vulnerability scanning, commit gates
+- **Actions**: threat_model, validate_architecture, scan_implementation, verify_commit
+- **State**: `koan/security/`
+- **Never knows**: How to fix vulnerabilities (blocks until fixed)
+
+**When to use**: All features (parallel with story), before commits
+
+**Why Sonnet?**: Security pattern detection and OWASP validation
+
+### 10. Documentation (Sonnet) - Comprehensive Docs
+- **File**: `documentation.md`
+- **Model**: Sonnet
+- **Purpose**: Generate documentation at every workflow phase
+- **Actions**: generate, update_index
+- **State**: `koan/documentation/`
+- **Never knows**: Implementation details (documents from specs)
+
+**When to use**: After each major workflow phase
+
+**Why Sonnet?**: Technical writing from specifications
+
+## Concept Anatomy
+
+Each concept has:
+
+1. **Frontmatter**: Metadata (name, model, state location, cost tier)
+2. **Purpose**: Why this concept exists
+3. **Actions**: What operations it can perform
+4. **Model Rationale**: Why this model was chosen
+5. **Integration Points**: How it fits in workflows
+6. **Anti-Patterns**: Common mistakes to avoid
+7. **Provenance**: How actions are tracked
+8. **Examples**: Usage demonstrations
+
+## Model Assignment Strategy
+
+### Sonnet (9/10 concepts) - Balanced Execution
+- Story capture (template filling)
+- Code analysis (MCP-based codebase exploration)
+- Verification (multi-pass review)
+- Code generation from specs (pattern following)
+- Quality checks (pattern matching)
+- Security scanning (vulnerability detection)
+- Git operations (command execution)
+- Context management (token counting)
+- Documentation generation (comprehensive docs)
+
+**Rationale**: These tasks benefit from balanced performance and capability
+
+### Opus (1/10 concepts) - Deep Reasoning
+- Architecture design (multi-step reasoning)
+- Trade-off evaluation (complex analysis)
+- Novel problem solving (synthesis)
+
+**Rationale**: Investment in deep reasoning prevents costly mistakes downstream
+
+## Cost Breakdown per Feature
+
+```
+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%)
+────────────────────────────────────────
+Total:                   ~$0.045
+```
+
+**Key Insight**: Architecture is the largest investment but prevents rework that would be far more expensive.
+
+## Invocation
+
+Concepts are invoked via Claude Code's Task tool:
+
+```markdown
+I'll use the story concept to capture this requirement.
+[Invokes Task tool with:
+  - subagent_type: "story-concept"
+  - model: "sonnet"
+  - prompt: {inputs}
+]
+```
+
+## State Files
+
+Each concept stores state in `koan/`:
+
+```yaml
+# koan/stories/story-001.yaml
+story_id: "story-001"
+created_at: "2025-11-09T20:00:00Z"
+title: "Add dark mode support"
+description: "..."
+acceptance_criteria: [...]
+status: "ready"
+```
+
+**Benefits:**
+- Human-readable
+- Git-trackable
+- LLM-friendly
+- Easy debugging
+
+## Provenance
+
+Every concept action creates provenance:
+
+```yaml
+# koan/provenance/actions/act-001.yaml
+action_id: "act-001"
+concept: "story"
+model: "sonnet"
+action: "create"
+triggered_by: null  # User-initiated
+```
+
+## Anti-Patterns
+
+### ❌ Concept Calling Concept
+```python
+# DON'T DO THIS
+class ArchitectureConcept:
+    def design(self, story):
+        # ...
+        impl = ImplementationConcept()
+        impl.generate(self)  # ❌ Direct call
+```
+
+✅ **Do this instead:**
+```yaml
+# synchronizations/feature-development.yaml
+- when: {concept: architecture, status: completed}
+  then: {concept: implementation, action: generate}
+```
+
+### ❌ Concept with Knowledge of Others
+```markdown
+# implementation.md
+After generating code, I'll call the quality concept to review it.
+```
+
+✅ **Do this instead:**
+```markdown
+# implementation.md
+After generating code, I'll set status="completed".
+(Quality will be triggered by impl-to-quality synchronization)
+```
+
+### ❌ Wrong Model Assignment
+```yaml
+# Using Opus for routine tasks
+implementation:
+  model: "opus"  # ❌ Overkill for clear specs
+```
+
+✅ **Do this instead:**
+```yaml
+# Use Sonnet for routine tasks
+implementation:
+  model: "sonnet"  # ✅ Clear specs → straightforward code
+```
+
+## Customization
+
+You can customize concepts for your project:
+
+1. **Add actions**: Add new actions to existing concepts
+2. **Adjust state format**: Change YAML structure for your needs
+3. **Change model**: Override model for specific concepts (with justification)
+4. **Add validations**: Enhance quality checks for your domain
+
+**But never:**
+- Remove the "never calls concepts" principle
+- Skip provenance tracking
+- Hide behavior in imperative code
+
+## Validation
+
+Zen enforces concept discipline:
+
+```bash
+# Check for concept-to-concept calls (should find none)
+grep -r "concept.*\..*(" .claude/concepts/
+
+# Verify provenance completeness
+ls koan/provenance/actions/ | wc -l  # Should match action count
+
+# Validate model assignments
+grep "model:" .claude/config.yaml
+```
+
+## Learning Path
+
+1. **Start with Story**: Create a feature with `/feature`
+2. **Observe Architecture**: See how Opus designs the solution
+3. **Watch Implementation**: See how Sonnet generates code from specs
+4. **Review Quality**: See pattern-based validation
+5. **Track Provenance**: Use `/trace` to see the complete chain
+
+## Questions?
+
+- **"When should I add a new concept?"** - When you have a truly independent concern that doesn't belong in existing concepts
+- **"Can concepts share code?"** - No. Duplicate code is better than hidden coupling
+- **"Why can't concepts call each other?"** - Because it makes behavior unpredictable and breaks legibility
+- **"Is Sonnet really sufficient?"** - For routine tasks with clear specs, absolutely. Try it!
+
+## Next Steps
+
+- Read individual concept files for detailed documentation
+- Review `.claude/synchronizations/feature-development.yaml` to see how concepts are orchestrated
+- Try `/feature "Your idea"` and watch the workflow
+- Use `/trace` to see the complete provenance chain