@dragonflymcp/plugin 1.0.0

package/templates/koan/README.md

@@ -0,0 +1,58 @@
+# Koan - State Storage
+
+This directory contains all state for your Zen WYSIWID architecture.
+
+## Structure
+
+- `stories/` - Story concept state (requirements, acceptance criteria)
+- `architecture/` - Architecture decisions and technical designs
+- `implementations/` - Code artifacts and implementation records
+- `reviews/` - Quality reviews and test results
+- `provenance/` - Action tracking and flow analysis
+  - `flows/` - Complete workflow traces
+  - `actions/` - Individual action logs
+- `session-state/` - Current session context snapshots and checkpoints
+- `anchors/` - Immutable context that survives compression
+- `health/` - Context health monitoring and grounding logs
+- `memory/` - Semantic memory storage
+  - `semantic/` - Long-term facts and knowledge
+  - `procedural/` - How-to knowledge and workflows
+  - `episodes/` - Session summaries
+
+## File-Based State
+
+All state is stored as YAML or Markdown files for:
+- Easy inspection and debugging
+- Git-trackable history
+- Human-readable format
+- LLM-friendly structure
+
+## Provenance Tracking
+
+Every action creates a provenance entry with:
+- `action_id` - Unique identifier
+- `concept` - Which concept performed the action
+- `model` - Which AI model was used (haiku/sonnet)
+- `triggered_by` - Parent action (or null if user-initiated)
+- `cost` - Token usage and cost in USD
+- `flow_id` - Workflow identifier linking related actions
+
+Use the `/trace <action_id>` command to explore provenance chains.
+
+## Safety Features
+
+- `anchors/rules.anchor.yaml` - Immutable rules that survive compression
+- `anchors/safety.anchor.yaml` - Safety constraints and blocked patterns
+- `health/status.yaml` - Context health monitoring
+- `health/grounding.log` - Log of dangerous command interceptions
+
+## Semantic Memory
+
+Store and retrieve persistent knowledge:
+- `/remember "fact"` - Store a memory
+- `/recall query` - Retrieve memories
+- `/checkpoint` - Save session state
+- `/restore` - Restore from checkpoint
+
+Memory is organized by type (semantic, procedural) and category
+(architecture, conventions, patterns, workflows, debugging).

package/templates/memory/index.yaml.template

@@ -0,0 +1,48 @@
+# Zen Semantic Memory Index
+# Provides fast lookup for stored memories
+
+version: 1
+created_at: "${TIMESTAMP}"
+last_updated: "${TIMESTAMP}"
+
+stats:
+  total_memories: 0
+  by_type:
+    semantic: 0
+    procedural: 0
+    episodic: 0
+  by_category:
+    architecture: 0
+    conventions: 0
+    patterns: 0
+    workflows: 0
+    debugging: 0
+    preferences: 0
+
+# Recent additions for quick access
+recent_additions: []
+# Example:
+# - id: "mem-001"
+#   summary: "API uses cursor pagination"
+#   added: "2025-01-06T10:00:00Z"
+
+# Tag index for fast retrieval
+tags: {}
+# Example:
+# auth: [mem-001, mem-015]
+# api: [mem-002, mem-008]
+
+# Category to file mapping
+category_files:
+  architecture: "semantic/architecture.yaml"
+  conventions: "semantic/conventions.yaml"
+  patterns: "semantic/patterns.yaml"
+  workflows: "procedural/workflows.yaml"
+  debugging: "procedural/debugging.yaml"
+  preferences: "semantic/preferences.yaml"
+
+# Memory maintenance
+maintenance:
+  last_consolidation: null
+  last_cleanup: null
+  memories_to_review: []

package/templates/memory/procedural/debugging.yaml.template

@@ -0,0 +1,24 @@
+# Zen Procedural Memory - Debugging
+# Stores debugging approaches, known issues, and solutions
+
+type: procedural
+category: debugging
+created_at: "${TIMESTAMP}"
+last_updated: "${TIMESTAMP}"
+
+# Debugging memories
+memories: []
+
+# Example memory format:
+# - id: "mem-006"
+#   content: "Auth failures: check token expiry first"
+#   confidence: high
+#   source: "Discovered during debugging session 2025-01-05"
+#   tags: [auth, debugging, tokens]
+#   created_at: "2025-01-05T16:00:00Z"
+#   symptoms:
+#     - "401 Unauthorized errors"
+#     - "User suddenly logged out"
+#   solution: "Check JWT exp claim, refresh token if expired"
+#   related_files:
+#     - src/auth/token.ts

package/templates/memory/procedural/workflows.yaml.template

@@ -0,0 +1,22 @@
+# Zen Procedural Memory - Workflows
+# Stores how to do common tasks and operations
+
+type: procedural
+category: workflows
+created_at: "${TIMESTAMP}"
+last_updated: "${TIMESTAMP}"
+
+# Workflow memories
+memories: []
+
+# Example memory format:
+# - id: "mem-005"
+#   content: "To deploy to staging: npm run deploy:staging"
+#   confidence: high
+#   source: "User demonstrated in session 2025-01-05"
+#   tags: [deploy, staging, npm]
+#   created_at: "2025-01-05T15:00:00Z"
+#   steps:
+#     - "Ensure tests pass: npm test"
+#     - "Build: npm run build"
+#     - "Deploy: npm run deploy:staging"

package/templates/memory/semantic/architecture.yaml.template

@@ -0,0 +1,21 @@
+# Zen Semantic Memory - Architecture
+# Stores architectural decisions, system design, and technical constraints
+
+type: semantic
+category: architecture
+created_at: "${TIMESTAMP}"
+last_updated: "${TIMESTAMP}"
+
+# Architecture memories
+memories: []
+
+# Example memory format:
+# - id: "mem-001"
+#   content: "Authentication uses JWT with RS256 signing"
+#   confidence: high
+#   source: "User stated in session 2025-01-05"
+#   tags: [auth, jwt, security]
+#   created_at: "2025-01-05T10:30:00Z"
+#   related_files:
+#     - src/auth/jwt.ts
+#   supersedes: null

package/templates/memory/semantic/conventions.yaml.template

@@ -0,0 +1,18 @@
+# Zen Semantic Memory - Conventions
+# Stores coding style, naming conventions, and formatting preferences
+
+type: semantic
+category: conventions
+created_at: "${TIMESTAMP}"
+last_updated: "${TIMESTAMP}"
+
+# Convention memories
+memories: []
+
+# Example memory format:
+# - id: "mem-002"
+#   content: "Use kebab-case for file names"
+#   confidence: high
+#   source: "User stated in session 2025-01-05"
+#   tags: [naming, files, style]
+#   created_at: "2025-01-05T11:00:00Z"

package/templates/memory/semantic/patterns.yaml.template

@@ -0,0 +1,21 @@
+# Zen Semantic Memory - Patterns
+# Stores common code patterns and design patterns used in the project
+
+type: semantic
+category: patterns
+created_at: "${TIMESTAMP}"
+last_updated: "${TIMESTAMP}"
+
+# Pattern memories
+memories: []
+
+# Example memory format:
+# - id: "mem-003"
+#   content: "Error handling uses Result<T, E> pattern"
+#   confidence: medium
+#   source: "Observed in codebase analysis"
+#   tags: [error-handling, patterns, typescript]
+#   created_at: "2025-01-05T12:00:00Z"
+#   examples:
+#     - file: src/utils/result.ts
+#       description: "Result type definition"

package/templates/memory/semantic/preferences.yaml.template

@@ -0,0 +1,18 @@
+# Zen Semantic Memory - Preferences
+# Stores user preferences and personal working style
+
+type: semantic
+category: preferences
+created_at: "${TIMESTAMP}"
+last_updated: "${TIMESTAMP}"
+
+# Preference memories
+memories: []
+
+# Example memory format:
+# - id: "mem-004"
+#   content: "User prefers smaller, focused commits"
+#   confidence: high
+#   source: "User stated in session 2025-01-05"
+#   tags: [git, commits, workflow]
+#   created_at: "2025-01-05T14:00:00Z"

package/templates/prompts/architecture.yaml.template

@@ -0,0 +1,349 @@
+# Zen Prompt Template: Architecture Concept
+# Version: 1.0.0
+# Model: opus (recommended for deep reasoning)
+#
+# This prompt designs technical solutions with explicit trade-off analysis
+# and structured decision-making.
+
+concept: architecture
+version: "1.0.0"
+recommended_model: opus
+
+# ============================================================================
+# PROMPTS
+# ============================================================================
+
+prompts:
+  # Primary action: Design architecture for a story
+  design:
+    system: |
+      You are a senior software architect with expertise in system design,
+      trade-off analysis, and technical decision-making.
+
+      ## Core Principles
+      1. **Explicit Trade-offs**: Every decision has pros and cons - document them
+      2. **Multiple Options**: Always consider 2-3 approaches before selecting
+      3. **Risk Awareness**: Identify what could go wrong and how to mitigate
+      4. **Pragmatism**: Balance ideal solutions with practical constraints
+
+      ## Reasoning Process (Chain-of-Thought)
+      Before designing, work through these steps explicitly:
+
+      ### Step 1: Understand Requirements
+      - What are the functional requirements?
+      - What are the non-functional requirements (performance, security, scale)?
+      - What constraints exist (tech stack, timeline, team skills)?
+
+      ### Step 2: Identify Key Decisions
+      - What are the architectural decisions that must be made?
+      - What patterns or approaches could apply?
+
+      ### Step 3: Evaluate Options
+      - For each decision, what are 2-3 viable options?
+      - What are the pros/cons of each?
+      - How do they align with requirements?
+
+      ### Step 4: Select and Document
+      - Choose the option that best balances requirements
+      - Document the rationale clearly
+      - Note risks and mitigations
+
+      ## Output Format
+      Respond with valid YAML:
+
+      ```yaml
+      arch_id: "arch-{number}"
+      story_id: "story-{number}"
+      status: "designing" | "completed" | "needs_revision"
+
+      # Summary for quick scanning (first 5 lines loaded by sync rules)
+      summary:
+        approach: "Brief description of selected approach"
+        risk_level: "low" | "medium" | "high"
+        estimated_complexity: "simple" | "moderate" | "complex"
+        key_decision: "The most important choice made"
+
+      # Detailed design
+      reasoning:
+        requirements_analysis: |
+          Analysis of functional and non-functional requirements...
+        constraints_identified:
+          - constraint: "Must use existing database"
+            impact: "Limits data model flexibility"
+
+      approaches_considered:
+        - name: "Approach A"
+          description: "..."
+          pros:
+            - "Pro 1"
+          cons:
+            - "Con 1"
+          fit_score: 0.0-1.0  # How well does it fit requirements?
+
+      selected_approach:
+        name: "Approach A"
+        rationale: "Why this approach was selected..."
+        confidence: 0.0-1.0  # How confident in this choice?
+
+      components:
+        - name: "ComponentName"
+          responsibility: "What this component does"
+          interface: "Key methods or endpoints"
+          dependencies: ["OtherComponent"]
+
+      technical_decisions:
+        - decision: "Use PostgreSQL for storage"
+          rationale: "ACID compliance needed for financial data"
+          alternatives_rejected:
+            - name: "MongoDB"
+              reason: "Eventual consistency not acceptable"
+
+      risks:
+        - risk: "Database could become bottleneck at scale"
+          probability: "medium"
+          impact: "high"
+          mitigation: "Implement read replicas and caching layer"
+
+      implementation_guidance:
+        - "Start with ComponentA as it has no dependencies"
+        - "ComponentB requires database migrations first"
+
+      open_questions:
+        - "Should we use connection pooling? Depends on expected load."
+      ```
+
+      ## Guidelines
+      - ALWAYS show your reasoning process explicitly
+      - Consider security implications for every design
+      - Identify at least 2 approaches before selecting
+      - Flag any decisions that need user input as high-risk
+      - Include implementation order guidance
+
+    user: |
+      Design the technical architecture for this story:
+
+      ## Story
+      {{#if story_yaml}}
+      ```yaml
+      {{story_yaml}}
+      ```
+      {{else}}
+      Title: {{story.title}}
+      Description: {{story.description}}
+      Acceptance Criteria:
+      {{#each story.acceptance_criteria}}
+      - {{this.criterion}}
+      {{/each}}
+      {{/if}}
+
+      {{#if existing_architecture}}
+      ## Existing System Context
+      {{existing_architecture}}
+      {{/if}}
+
+      {{#if tech_stack}}
+      ## Tech Stack Constraints
+      {{tech_stack}}
+      {{/if}}
+
+      {{#if previous_decisions}}
+      ## Previous Architectural Decisions
+      {{#each previous_decisions}}
+      - {{this.decision}}: {{this.rationale}}
+      {{/each}}
+      {{/if}}
+
+  # Revise architecture based on feedback
+  revise:
+    system: |
+      You are revising an existing architecture design based on feedback.
+
+      ## Rules
+      - Preserve decisions that weren't criticized
+      - Update version number
+      - Document what changed and why
+      - Re-evaluate risks after changes
+
+    user: |
+      Current architecture:
+      ```yaml
+      {{arch_yaml}}
+      ```
+
+      Feedback to address:
+      {{#each feedback}}
+      - {{this}}
+      {{/each}}
+
+      Revise the architecture to address this feedback.
+
+  # Review architecture for quality
+  review:
+    system: |
+      You are reviewing an architecture design for quality, completeness,
+      and potential issues.
+
+      ## Review Checklist
+      - [ ] All acceptance criteria addressed?
+      - [ ] Trade-offs clearly documented?
+      - [ ] Risks identified with mitigations?
+      - [ ] Security considerations addressed?
+      - [ ] Performance implications considered?
+      - [ ] Implementation guidance clear?
+
+      ## Output Format
+      ```yaml
+      review_status: "approved" | "needs_revision"
+      strengths:
+        - "Well-considered approach to..."
+      concerns:
+        - concern: "Missing consideration for..."
+          severity: "blocking" | "major" | "minor"
+          suggestion: "Consider adding..."
+      questions:
+        - "Have you considered...?"
+      ```
+
+    user: |
+      Review this architecture design:
+
+      ```yaml
+      {{arch_yaml}}
+      ```
+
+      Original story requirements:
+      ```yaml
+      {{story_yaml}}
+      ```
+
+# ============================================================================
+# EXAMPLES (Few-Shot Learning)
+# ============================================================================
+
+examples:
+  design:
+    - input:
+        title: "Add user authentication with OAuth"
+        acceptance_criteria:
+          - "Support Google and GitHub login"
+          - "Remember users for 30 days"
+          - "Secure token storage"
+      output: |
+        arch_id: "arch-001"
+        story_id: "story-001"
+        status: "completed"
+
+        summary:
+          approach: "JWT with refresh tokens using passport.js"
+          risk_level: "medium"
+          estimated_complexity: "moderate"
+          key_decision: "Stateless JWT over server sessions"
+
+        reasoning:
+          requirements_analysis: |
+            Functional: OAuth with Google/GitHub, persistent login
+            Non-functional: Security (token storage), UX (seamless login)
+            Constraints: Must work with existing Express backend
+          constraints_identified:
+            - constraint: "Existing Express.js backend"
+              impact: "Use passport.js ecosystem for consistency"
+
+        approaches_considered:
+          - name: "Server-side sessions with Redis"
+            description: "Traditional session management with Redis store"
+            pros:
+              - "Simple to implement"
+              - "Easy token revocation"
+              - "Server-controlled expiry"
+            cons:
+              - "Requires Redis infrastructure"
+              - "Sticky sessions or shared store needed"
+              - "Harder to scale horizontally"
+            fit_score: 0.6
+
+          - name: "JWT with refresh tokens"
+            description: "Stateless access tokens with rotating refresh tokens"
+            pros:
+              - "Stateless - easy horizontal scaling"
+              - "No additional infrastructure"
+              - "Mobile-friendly"
+            cons:
+              - "Token revocation requires blocklist"
+              - "More complex token rotation logic"
+            fit_score: 0.8
+
+        selected_approach:
+          name: "JWT with refresh tokens"
+          rationale: |
+            Stateless architecture aligns with our scaling goals.
+            passport.js provides battle-tested OAuth strategies.
+            Short-lived access tokens (15min) + refresh rotation
+            balances security with UX.
+          confidence: 0.85
+
+        components:
+          - name: "AuthController"
+            responsibility: "Handle OAuth callbacks and token issuance"
+            interface: "GET /auth/{provider}, GET /auth/{provider}/callback"
+            dependencies: ["TokenService", "UserService"]
+          - name: "TokenService"
+            responsibility: "JWT creation, validation, refresh rotation"
+            interface: "createTokenPair(), validateAccess(), refreshTokens()"
+            dependencies: []
+          - name: "AuthMiddleware"
+            responsibility: "Protect routes, extract user from token"
+            interface: "requireAuth(), optionalAuth()"
+            dependencies: ["TokenService"]
+
+        technical_decisions:
+          - decision: "Use httpOnly cookies for token storage"
+            rationale: "Prevents XSS token theft; automatic inclusion in requests"
+            alternatives_rejected:
+              - name: "localStorage"
+                reason: "Vulnerable to XSS attacks"
+          - decision: "15-minute access token expiry"
+            rationale: "Limits damage window if token compromised"
+            alternatives_rejected:
+              - name: "1-hour expiry"
+                reason: "Too long exposure window for sensitive operations"
+
+        risks:
+          - risk: "Refresh token theft enables persistent access"
+            probability: "low"
+            impact: "high"
+            mitigation: "Rotate refresh tokens on each use; detect reuse"
+          - risk: "OAuth provider outage blocks new logins"
+            probability: "low"
+            impact: "medium"
+            mitigation: "Support multiple providers; add email/password later"
+
+        implementation_guidance:
+          - "1. Set up passport.js with Google strategy"
+          - "2. Implement TokenService with JWT signing"
+          - "3. Add AuthMiddleware to protected routes"
+          - "4. Add GitHub strategy (similar pattern)"
+          - "5. Implement token refresh endpoint"
+          - "6. Add refresh token rotation and reuse detection"
+
+        open_questions: []
+
+# ============================================================================
+# VALIDATION
+# ============================================================================
+
+validation:
+  required_fields:
+    - arch_id
+    - story_id
+    - status
+    - summary
+    - approaches_considered
+    - selected_approach
+    - components
+    - risks
+
+  minimum_approaches: 2
+  minimum_components: 1
+  minimum_risks: 1
+
+  high_risk_requires_approval: true