@dragonflymcp/plugin 1.0.0

package/templates/commands/global-remember.md.template

@@ -0,0 +1,187 @@
+# Global Remember Command
+
+Store knowledge in global memory that persists across all projects.
+
+## Usage
+
+```
+/global-remember "<knowledge>" [options]
+```
+
+## Options
+
+| Option | Description | Example |
+|--------|-------------|---------|
+| `--category` | Memory category | `preferences`, `patterns`, `technologies`, `learnings`, `workflows` |
+| `--tech` | Technology tag | `postgresql`, `typescript`, `react` |
+| `--tag` | Additional tags | `error-handling`, `performance` |
+| `--source` | Source project | Current project by default |
+
+## Process
+
+When you run this command:
+
+1. **Parse Knowledge**
+   - Extract the key insight
+   - Identify category and tags
+
+2. **Check for Duplicates**
+   - Search existing global memory
+   - If similar exists, offer to update or create new
+
+3. **Store in Global Memory**
+   - Create/update file in `~/.zen/global-memory/`
+   - Add metadata (timestamp, source project)
+
+4. **Confirm Storage**
+   - Display what was stored
+   - Show how to recall it
+
+## Examples
+
+### Store a Preference
+
+```
+/global-remember "Always use single quotes in TypeScript" --category=preferences
+```
+
+Creates/updates `~/.zen/global-memory/preferences.yaml`:
+```yaml
+coding_style:
+  quotes: single
+  quotes_note: "Always use single quotes in TypeScript"
+  added: 2025-01-15
+```
+
+### Store a Pattern
+
+```
+/global-remember "Use Result type for error handling in TypeScript" --category=patterns --tag=error-handling
+```
+
+Creates `~/.zen/global-memory/patterns/result-type.yaml`:
+```yaml
+name: Result Type Pattern
+category: error-handling
+language: typescript
+description: Use Result type for error handling in TypeScript
+added: 2025-01-15
+source_project: current-project
+
+pattern: |
+  type Result<T, E = Error> =
+    | { success: true; value: T }
+    | { success: false; error: E };
+
+  function createUser(data: UserData): Result<User, ValidationError> {
+    if (!data.email) {
+      return { success: false, error: new ValidationError('Email required') };
+    }
+    return { success: true, value: new User(data) };
+  }
+
+usage: |
+  Always check success before accessing value:
+  const result = createUser(data);
+  if (result.success) {
+    console.log(result.value);
+  } else {
+    console.error(result.error);
+  }
+```
+
+### Store a Technology Gotcha
+
+```
+/global-remember "PostgreSQL JSONB is faster than JSON for queries" --category=technologies --tech=postgresql
+```
+
+Updates `~/.zen/global-memory/technologies/postgresql.yaml`:
+```yaml
+technology: PostgreSQL
+gotchas:
+  - title: JSON vs JSONB Performance
+    issue: JSON stores as text, JSONB as binary
+    solution: Always use JSONB unless preserving whitespace
+    added: 2025-01-15
+```
+
+### Store a Cross-Project Learning
+
+```
+/global-remember "API rate limiting should be per-user AND per-endpoint" --category=learnings
+```
+
+Updates `~/.zen/global-memory/learnings/api-design.yaml`:
+```yaml
+category: API Design
+learnings:
+  - id: GL004
+    insight: API rate limiting should be per-user AND per-endpoint
+    context: Learned from current project
+    recommendation: Implement both layers in middleware
+    added: 2025-01-15
+    source: current-project
+```
+
+### Store a Workflow Optimization
+
+```
+/global-remember "Write failing test before fixing bugs" --category=workflows
+```
+
+Updates `~/.zen/global-memory/workflows/debugging.yaml`:
+```yaml
+workflow: Debugging
+optimizations:
+  - name: Test-first bug fixing
+    steps:
+      - Reproduce the bug
+      - Write a failing test that captures the bug
+      - Fix the code
+      - Verify test passes
+    rationale: Prevents regression and documents expected behavior
+    added: 2025-01-15
+```
+
+## Automatic Suggestions
+
+The system may suggest promoting project learnings to global memory:
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+Potential Global Learning Detected
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+This learning from the current project may be useful globally:
+
+"Always validate webhook signatures before processing"
+
+This applies to: webhooks, security, API integration
+
+Would you like to add this to global memory?
+[Y] Yes, add to global  [N] Keep project-only  [E] Edit first
+```
+
+## Storage Location
+
+All global memory is stored in:
+```
+~/.zen/global-memory/
+├── preferences.yaml
+├── patterns/
+│   └── *.yaml
+├── technologies/
+│   └── *.yaml
+├── learnings/
+│   └── *.yaml
+└── workflows/
+    └── *.yaml
+```
+
+## Privacy
+
+- Global memory is stored locally only
+- No data is sent to external services
+- You control what gets stored
+- Can be backed up or synced manually

package/templates/commands/health.md.template

@@ -0,0 +1,107 @@
+---
+name: health
+description: "Display context health status and safety warnings"
+---
+
+# /health Command
+
+Display current context health status to help Claude and users understand the state of the conversation context.
+
+## Purpose
+
+This command helps:
+1. Claude understand if context has been compressed
+2. Users see token usage and warnings
+3. Identify when extra verification is needed before operations
+
+## What to Do
+
+1. Read `koan/health/status.yaml`
+2. Read `koan/anchors/rules.anchor.yaml`
+3. Read `koan/anchors/directory.anchor.yaml`
+4. Display a formatted summary
+
+## Output Format
+
+```
+Context Health Status
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Tokens: {used} / {total} ({percent}%) [{zone}]
+Session: {interactions} interactions, {checkpoints} checkpoints
+Compression: {compression_status}
+
+Grounding Status:
+{✓|✗} Directory verified: {working_directory}
+{✓|✗} Rules loaded: {rule_count} rules
+{✓|✗} Safety constraints active
+
+Confidence: {confidence_level}
+
+{warnings_section}
+
+{recommendations_section}
+```
+
+## Example Output (Healthy)
+
+```
+Context Health Status
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Tokens: 45,000 / 200,000 (22.5%) [GREEN]
+Session: 12 interactions, 1 checkpoint
+Compression: None this session
+
+Grounding Status:
+✓ Directory verified: /Users/kolb/project
+✓ Rules loaded: 7 rules (4 safety, 3 workflow)
+✓ Safety constraints active
+
+Confidence: HIGH
+
+Recommendations:
+• Continue normally - context is healthy
+• Consider checkpoint at next workflow milestone
+```
+
+## Example Output (After Compression)
+
+```
+Context Health Status
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Tokens: 165,000 / 200,000 (82.5%) [RED]
+Session: 87 interactions, 2 checkpoints
+Compression: 1 compression 5 turns ago
+
+Grounding Status:
+✓ Directory verified: /Users/kolb/project
+✓ Rules loaded: 7 rules
+✓ Safety constraints active
+
+Confidence: MEDIUM
+
+⚠️  WARNINGS:
+• Context was compressed. Some details from early conversation may be summarized.
+• High token usage - consider /checkpoint before major operations.
+
+Recommendations:
+• Re-read koan/anchors/rules.anchor.yaml before destructive operations
+• Verify assumptions about file paths and previous decisions
+• Create checkpoint before next major change
+```
+
+## When to Use
+
+- Before destructive operations (rm, git reset, etc.)
+- When Claude seems confused about prior context
+- At the start of a new work session
+- After long conversations (50+ interactions)
+- When /compact or auto-compact has run
+
+## Related Commands
+
+- `/checkpoint` - Create state checkpoint
+- `/trace` - View action provenance
+- `/costs` - View token/cost usage

package/templates/commands/help.md.template

@@ -0,0 +1,253 @@
+Display context-aware help for Zen WYSIWID workflows and commands.
+
+When the user runs this command, you should:
+
+1. **Determine Help Context**
+   - If no argument: Show overview of all commands
+   - If topic provided: Show detailed help for that topic
+   - If in workflow: Show current state and available actions
+
+2. **Available Topics**
+   - `commands` - List all slash commands
+   - `concepts` - Explain the 10 concepts
+   - `workflow` - How workflows work
+   - `sync` - Synchronization rules
+   - `state` - Current workflow state
+   - `troubleshooting` - Common issues and fixes
+
+## Usage
+
+```
+/help              # Overview and quick start
+/help commands     # List all commands
+/help concepts     # Explain concepts
+/help workflow     # How workflows work
+/help state        # Current workflow state
+/help troubleshooting  # Common issues
+```
+
+## Overview Response (no arguments)
+
+When user runs `/help` with no arguments:
+
+```
+Zen WYSIWID Architecture - Quick Reference
+
+WHAT YOU SEE IS WHAT IT DOES
+
+Core Workflow:
+  Story -> Architecture -> Implementation -> Quality -> Version
+
+Getting Started:
+  /feature "description"   Create a new feature
+  /workflow "description"  Run complete workflow automatically
+  /sync                    Check current sync state
+
+Key Commands:
+  /costs                   Show session costs
+  /trace <id>              Trace workflow history
+  /health                  Check session health
+  /checkpoint              Save current state
+
+Need More Help?
+  /help commands           All available commands
+  /help concepts           How concepts work
+  /help workflow           Workflow details
+  /help troubleshooting    Common issues
+```
+
+## Commands List Response
+
+When user runs `/help commands`:
+
+```
+Zen Commands Reference
+
+WORKFLOW COMMANDS
+  /feature <description>   Create feature story, evaluate syncs
+  /workflow <description>  Run complete workflow automatically
+  /sync                    Evaluate synchronization rules
+
+STATE & CONTEXT
+  /checkpoint              Save session state
+  /restore                 Restore from checkpoint
+  /health                  Check context usage
+  /trace <id>              Trace provenance chain
+
+COST & PERFORMANCE
+  /costs                   Show session costs
+  /predict-cost <desc>     Estimate feature cost
+  /slo                     View SLO metrics
+
+MEMORY
+  /remember <fact>         Store in semantic memory
+  /recall <query>          Retrieve from memory
+  /global-remember         Store across projects
+  /global-recall           Recall cross-project
+
+ANALYSIS
+  /replay <id>             Replay failed workflow
+  /explore <question>      Explore codebase
+  /profile                 Profile project
+  /retrospective           Review workflow quality
+
+UTILITIES
+  /cache                   Manage concept cache
+  /classify <desc>         Classify task type
+  /estimate <desc>         Estimate effort
+  /pr-review               Review pull request
+```
+
+## Concepts Help Response
+
+When user runs `/help concepts`:
+
+```
+Zen Concepts (10 Total)
+
+CORE WORKFLOW CONCEPTS
+  story          Captures user requirements (Sonnet)
+                 Actions: create, update, clarify, cancel
+
+  architecture   Designs technical approach (Opus)
+                 Actions: design, revise, validate
+
+  implementation Generates code from specs (Sonnet)
+                 Actions: generate, refactor, fix
+
+  quality        Reviews code and runs tests (Sonnet)
+                 Actions: review, test, benchmark
+
+  version        Manages git operations (Sonnet)
+                 Actions: commit, tag, release
+
+  context        Manages context window (Sonnet)
+                 Actions: compress, snapshot, restore
+
+INTEGRATION CONCEPTS
+  code-analysis  Gathers codebase context via MCP (Sonnet)
+                 Actions: context, impact, profile
+
+  security       Validates security at each phase (Sonnet)
+                 Actions: threat_model, validate, scan
+
+  verification   Multi-pass independent review (Sonnet)
+                 Actions: verify_architecture, verify_implementation
+
+  documentation  Generates docs at each phase (Sonnet)
+                 Actions: generate, update, validate
+
+KEY PRINCIPLE:
+  Concepts NEVER call other concepts directly.
+  Synchronization rules orchestrate the workflow.
+```
+
+## State Help Response
+
+When user runs `/help state`:
+
+First, check current state by reading koan/ files:
+
+```
+Current Workflow State
+
+ACTIVE FLOWS
+  flow-001: "Add user authentication"
+    Status: in_progress
+    Phase: implementation
+    Story: story-001 (ready)
+    Architecture: arch-001 (completed)
+    Implementation: impl-001 (in_progress)
+
+RECENT ACTIONS
+  1. story.create -> completed (2 min ago)
+  2. architecture.design -> completed (1 min ago)
+  3. implementation.generate -> in_progress
+
+NEXT STEPS
+  - Implementation completes
+  - Sync triggers: impl-to-quality-review
+  - Parallel: impl-to-quality-test
+
+CONTEXT USAGE
+  Current: 35%
+  Status: healthy
+  Checkpoints: 1
+
+ACTIONS YOU CAN TAKE
+  /sync --execute          Continue workflow
+  /trace flow-001          See full history
+  /checkpoint              Save current state
+```
+
+## Troubleshooting Response
+
+When user runs `/help troubleshooting`:
+
+```
+Zen Troubleshooting Guide
+
+COMMON ISSUES
+
+1. "Sync rule not firing"
+   Cause: Prerequisites not met
+   Fix: Check koan/ state files
+   - /trace <id> to see what's missing
+   - Ensure previous concept completed successfully
+
+2. "Context too high (>90%)"
+   Cause: Long workflow without compression
+   Fix: Create checkpoint and restore
+   - /checkpoint "before continuing"
+   - /restore if needed
+
+3. "MCP server unavailable"
+   Cause: MCP servers not running
+   Fix: Workflow continues without code analysis
+   - Check: mcp-servers/ for server status
+   - MCP is optional - workflow gracefully degrades
+
+4. "Architecture has high risk"
+   Cause: Design detected risky patterns
+   Fix: Review and approve or revise
+   - Read koan/architecture/arch-{id}.yaml
+   - User decision required
+
+5. "Quality review failed"
+   Cause: Code issues found
+   Fix: Check review findings
+   - Read koan/reviews/review-{id}.yaml
+   - Fix issues and re-run quality
+
+6. "Missing state file"
+   Cause: Concept didn't complete
+   Fix: Re-run previous step
+   - Check koan/ for existing state
+   - /replay <id> to restart from failure
+
+DIAGNOSTIC COMMANDS
+  /health                  Check overall health
+  /trace <id>              Trace specific flow
+  /costs                   Check spending
+  /sync --dry-run          Preview sync evaluation
+
+GETTING HELP
+  - Read .claude/synchronizations/*.yaml for workflow logic
+  - Check koan/provenance/ for action history
+  - Review CLAUDE.md for project context
+```
+
+## Context-Aware Behavior
+
+When providing help, check:
+
+1. **Active Workflow**: If there's an in-progress flow, offer relevant next steps
+2. **Recent Errors**: If koan/health/ shows issues, suggest fixes
+3. **Context Usage**: If high (>75%), suggest checkpoint
+4. **MCP Status**: If unavailable, note graceful degradation
+
+## Related Commands
+
+- `/health` - More detailed health status
+- `/trace` - Detailed provenance tracking
+- `/sync` - Manual sync evaluation