@exaudeus/workrail 0.0.5 → 0.0.7

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@exaudeus/workrail",
-  "version": "0.0.5",
+  "version": "0.0.7",
   "description": "MCP server for structured workflow orchestration and step-by-step task guidance",
   "license": "MIT",
   "bin": {

package/workflows/workflow-for-workflows.json

@@ -1,73 +1,276 @@
 {
   "id": "workflow-for-workflows",
-  "name": "Workflow for Creating New Workflows",
-  "version": "0.0.1",
-  "description": "A meta-workflow to guide the creation, validation, and deployment of new, reusable workflow templates.",
+  "name": "Progressive Workflow Creation Guide",
+  "version": "0.0.2",
+  "description": "An adaptive meta-workflow that guides users through creating high-quality workflow templates with personalized learning paths. Offers three experience-based approaches: Basic (step-by-step with detailed explanations), Intermediate (balanced guidance with examples), and Advanced (comprehensive features with expert context). All paths can produce sophisticated workflows - the difference is in explanation depth and feature introduction timing.",
+  "clarificationPrompts": [
+    "What's your experience level with workflow creation? (New to this / Some experience / Very experienced)",
+    "What type of workflow are you creating? (e.g., coding, analysis, content creation, process management)",
+    "What recurring problem or task should this workflow solve?",
+    "Who is the intended audience for this workflow? (e.g., beginners, experts, specific roles)",
+    "Are there any specific constraints or requirements for this workflow?"
+  ],
   "preconditions": [
     "User has a clear idea of the recurring task or problem the new workflow should solve.",
-    "The 'workflow-lookup' MCP server is running and accessible.",
-    "The agent has access to 'create_file', 'edit_file', and 'run_terminal_cmd' tools."
+    "The agent has access to 'create_file', 'edit_file', 'run_terminal_cmd', 'workflow_validate_json', and 'workflow_validate' tools."
   ],
   "metaGuidance": [
+    "PROGRESSIVE LEARNING: Adapt to user experience level. Use learningPath variable for guidance depth - detailed for 'basic', balanced for 'intermediate', expert for 'advanced'.",
+    "QUALITY FOCUS: All learning paths can produce sophisticated workflows. The difference is in HOW features are taught, not WHICH features are available. Introduce advanced features when the use case demands it, regardless of path.",
     "The goal is to create a *reusable template*, not a single-use script. Use placeholders like [User provides X] where appropriate.",
     "Prompts should define goals and roles for the agent, not a rigid script. This allows the agent to use its intelligence to best achieve the task.",
     "At each step, the agent should confirm with the user before proceeding with a file modification or command.",
     "Maintain a clear distinction between the workflow being created and this meta-workflow.",
-    "Save progress frequently by confirming file edits."
+    "Save progress frequently by confirming file edits.",
+    "TOOL INTEGRATION: Leverage MCP tools throughout - Use 'workflow_list' and 'workflow_get' for template discovery, 'workflow_validate_json' for comprehensive validation, and 'workflow_validate' for step-by-step output validation.",
+    "When validation fails, the MCP tools provide detailed error messages and actionable suggestions - use these to guide improvements rather than guessing at fixes.",
+    "PATH-SPECIFIC GUIDANCE: Tailor explanation depth by learningPath. Basic: detailed explanations. Intermediate: balanced with examples. Advanced: comprehensive with expert context.",
+        "FEATURE TEACHING: Introduce features progressively within each path. Even basic users should learn about conditional steps and context variables when their workflow needs them - just with more explanation of why and how."
   ],
   "steps": [
     {
-      "id": "phase-1-discovery",
-      "title": "Phase 1: Assisted Discovery & Ideation",
-      "prompt": "We will begin by defining the problem with data and finding a suitable template.\n\n**1. Define the Goal (User's Role):**\n   - Please state your initial hypothesis for the problem this workflow solves and its primary failure mode.\n\n**2. Guided Data Gathering (Agent's Goal):**\n   - Your goal is to help the user validate their hypothesis. Prompt them to use their tools (`grep`, `git log`, etc.) to find evidence. Ask for things like:\n     - Key excerpts from bug reports or incident post-mortems.\n     - Common themes in PR review comments.\n     - Examples of 'TODO' or 'HACK' comments in the relevant codebase.\n\n**3. Synthesize & Find Template (Agent's Goal):**\n   - Your goal is to synthesize the gathered data into a refined problem statement.\n   - Once the problem is clear, find the most suitable existing workflow to use as a template by using `workflow_list` and `workflow_get`.",
+      "id": "phase-0-discovery",
+      "title": "Phase 0: Comprehensive Discovery & Requirements Analysis",
+      "prompt": "Before we build, let's understand the 'why'. This phase ensures your new workflow solves the right problem for the right people.\n\n**STEP 1: Define the Core Problem & Goal**\n\n- **Problem Statement**: Describe the specific, recurring task or problem this new workflow will solve.\n- **Primary Objective**: What is the single most important outcome or key message of completing this workflow?\n- **Critical Failure Mode**: What is the most critical error or negative outcome this workflow is designed to prevent?\n\n**STEP 2: Understand the Users & Context**\n\n- **Target Audience**: Who is this workflow for? Describe their role, expertise level, and what they need to succeed.\n- **Usage Context**: In what situation will this workflow be used? (e.g., during code review, content planning, incident response, customer onboarding).\n\n**STEP 3: Gather Materials & Define Success**\n\n- **Supporting Materials**: What supporting documents, data, or examples are available that could inform the design?\n- **Constraints & Requirements**: Are there any specific constraints, required tools, or other requirements to consider?\n- **Success Metrics**: How will you measure if this workflow is successful? What does a high-quality result look like?\n\n**Agent Guidance**: Synthesize this information and confirm your understanding before proceeding. Use `workflow_list` and `workflow_get` to find suitable templates based on the problem *structure*, not necessarily the domain.",
+      "guidance": [
+        "BE SPECIFIC: Vague goals lead to vague workflows. The more precise you are here, the better the final product.",
+        "THINK ABOUT THE USER: A workflow for an expert looks very different from one for a novice. Empathize with your audience.",
+        "PROVIDE EXAMPLES: If you have examples of the problem or desired outcome, share them now.",
+        "TEMPLATE STRATEGY: Focus on structural similarity, not domain similarity, when recommending templates. A good 'bug investigation' workflow might be a great template for a 'customer complaint' workflow."
+      ],
+      "askForFiles": true,
+      "requireConfirmation": true
+    },
+    {
+      "id": "phase-1-assessment",
+      "title": "Phase 1: Personalized Learning Path Selection",
+      "prompt": "Excellent! With a clear understanding of your goals, let's choose the best way to build your workflow.\n\nPlease select your experience level with workflow creation to get a personalized-path:\n\n🌱 **Basic Path - \"Learn by Doing with Explanation\"**\n   - New to workflows or want thorough understanding\n   - Step-by-step guidance with detailed explanations\n   - Progressive introduction of advanced features with context\n   - Focus: Understanding concepts and building confidence\n\n🚀 **Intermediate Path - \"Balanced Guidance with Examples\"**\n   - Some experience with automation or process design\n   - Structured approach with practical examples\n   - Feature recommendations based on your use case\n   - Focus: Efficient workflow creation with best practices\n\n🏆 **Advanced Path - \"Full Features with Expert Context\"**\n   - Experienced with workflow/automation tools\n   - Comprehensive feature access from the start\n   - Architectural guidance and performance considerations\n   - Focus: Sophisticated workflow engineering\n\n**Agent Guidance**: Based on the user's selection, set the `learningPath` context variable to 'basic', 'intermediate', or 'advanced'.",
+      "guidance": [
+        "PATH EXPLANATION: Clearly explain what each learning path offers so users can make an informed choice based on the discovery from Phase 0.",
+        "QUALITY FOCUS: All paths should result in high-quality workflows. The difference is in teaching approach, not final capability."
+      ],
+      "requireConfirmation": true
+    },
+    {
+      "id": "phase-2-basic",
+      "runCondition": {"var": "learningPath", "equals": "basic"},
+      "title": "Phase 2: Guided Workflow Creation (Basic Path)",
+      "prompt": "Let's create your workflow step-by-step with detailed explanations! 🌱\n\n**UNDERSTANDING WORKFLOWS:**\nA workflow is like a recipe that guides someone (or an AI) through a complex task. It has:\n- **Metadata**: Name, description, and settings\n- **Steps**: The actual instructions to follow\n- **Features**: Special capabilities like conditional logic\n\n**STEP 1: Create Your Workflow File**\nAgent: Ask the user for a filename (e.g., `my-workflow.json`) and create the file using the template from Phase 1. Explain each field as you add it.\n\n**STEP 2: Build the Structure Together**\nWe'll go through each part of your workflow:\n\n1. **Basic Info** (`id`, `name`, `version`, `description`)\n   - Agent: Explain why each field matters and help craft clear, descriptive content\n\n2. **Setup Requirements** (`preconditions`)\n   - Agent: Explain what preconditions are and why they prevent problems\n\n3. **Global Rules** (`metaGuidance`)\n   - Agent: Explain the difference between global rules and step-specific instructions\n\n4. **The Action Steps** (`steps`)\n   - Agent: Start with simple linear steps, but explain that workflows can also have:\n     - **Conditional steps**: \"Do this IF condition is true\"\n     - **Context variables**: Information that flows between steps\n     - **Validation**: Automatic quality checks\n   - If the user's workflow needs these features, introduce them with clear examples\n\n**LEARNING FOCUS:** Understanding what each piece does and why it's useful.",
+      "guidance": [
+        "EXPLAIN EVERYTHING: This user is learning. Explain the purpose of each JSON field and workflow concept.",
+        "PROGRESSIVE FEATURES: Start with basics, introduce advanced features (conditional steps, context variables) when the use case needs them - with full explanations.",
+        "USE ANALOGIES: Compare workflow concepts to familiar things (recipes, instruction manuals, etc.).",
+        "ENCOURAGE QUESTIONS: Invite the user to ask about anything that's unclear.",
+        "QUALITY TEACHING: Even though this is the basic path, don't compromise on workflow quality - just explain more."
+      ],
+      "validationCriteria": [
+        {
+          "type": "regex",
+          "pattern": "\"id\":\\s*\"[a-zA-Z0-9_-]+\"",
+          "message": "Workflow must have a valid id field with alphanumeric characters, underscores, or hyphens"
+        },
+        {
+          "type": "regex",
+          "pattern": "\"name\":\\s*\"[^\"]{3,}\"",
+          "message": "Workflow must have a descriptive name (at least 3 characters)"
+        },
+        {
+          "type": "regex",
+          "pattern": "\"description\":\\s*\"[^\"]{20,}\"",
+          "message": "Workflow must have a meaningful description (at least 20 characters)"
+        },
+        {
+          "type": "regex",
+          "pattern": "\"steps\":\\s*\\[",
+          "message": "Workflow must have a steps array with at least one step"
+        }
+      ]
+    },
+    {
+      "id": "phase-2-intermediate",
+      "runCondition": {"var": "learningPath", "equals": "intermediate"},
+      "title": "Phase 2: Structured Workflow Development (Intermediate Path)",
+      "prompt": "Let's build your workflow with a structured approach and best practices! 🚀\n\n**STEP 1: Initialize Workflow File**\nAgent: Request a filename and create the workflow file using the template from Phase 1. Use efficient, clear explanations.\n\n**STEP 2: Core Structure Development**\nWe'll build your workflow systematically:\n\n1. **Metadata & Identity** (`id`, `name`, `version`, `description`)\n   - Focus on discoverability and clear communication\n   - Best practice: Make names searchable and descriptions actionable\n\n2. **Operational Requirements** (`preconditions`, `metaGuidance`)\n   - Define what's needed before starting\n   - Establish global rules for consistency\n\n3. **Enhanced Features** (based on your workflow type):\n   - **Clarification Prompts**: Gather better input upfront\n   - **Validation Criteria**: Automatic quality checks\n   - **Context Variables**: When you need information to flow between steps\n   - **Conditional Logic**: For workflows with decision points\n\n4. **Step Architecture**\n   - Design clear, actionable steps\n   - Add confirmation gates for critical actions\n   - Include file sharing when collaboration is needed\n\n**FEATURE RECOMMENDATIONS:**\nAgent: Based on the workflow type, recommend specific features. For example:\n- Coding workflows → validation criteria + confirmation gates\n- Analysis workflows → context variables + clarification prompts\n- Process workflows → conditional steps + clear guidance\n\n**EFFICIENCY FOCUS:** Building professionally structured workflows with appropriate features.",
+      "guidance": [
+        "STRUCTURED APPROACH: Follow a logical sequence with clear reasoning for each decision.",
+        "FEATURE RECOMMENDATIONS: Suggest appropriate features based on workflow type and use case.",
+        "BEST PRACTICES: Share proven patterns and explain why they work.",
+        "PRACTICAL EXAMPLES: Use real-world scenarios to illustrate concepts.",
+        "BALANCED DEPTH: Provide enough detail to understand without overwhelming with basics."
+      ],
+      "validationCriteria": [
+        {
+          "type": "regex",
+          "pattern": "\"id\":\\s*\"[a-zA-Z0-9_-]+\"",
+          "message": "Workflow must have a valid id field with alphanumeric characters, underscores, or hyphens"
+        },
+        {
+          "type": "regex",
+          "pattern": "\"name\":\\s*\"[^\"]{3,}\"",
+          "message": "Workflow must have a descriptive name (at least 3 characters)"
+        },
+        {
+          "type": "regex",
+          "pattern": "\"description\":\\s*\"[^\"]{20,}\"",
+          "message": "Workflow must have a meaningful description (at least 20 characters)"
+        },
+        {
+          "type": "regex",
+          "pattern": "\"steps\":\\s*\\[",
+          "message": "Workflow must have a steps array with at least one step"
+        }
+      ]
+    },
+    {
+      "id": "phase-2-advanced",
+      "runCondition": {"var": "learningPath", "equals": "advanced"},
+      "title": "Phase 2: Comprehensive Workflow Architecture (Advanced Path)",
+      "prompt": "Let's architect a sophisticated workflow with full feature utilization! 🏆\n\n**STEP 1: Rapid File Initialization**\nAgent: Create the workflow file with the template foundation. Focus on architectural decisions.\n\n**STEP 2: Architectural Design**\nComprehensive workflow engineering:\n\n1. **Core Architecture** (`id`, `name`, `version`, `description`)\n   - Semantic versioning strategy\n   - Namespace considerations for organizational use\n   - Description as API documentation\n\n2. **Operational Design** (`preconditions`, `metaGuidance`, `contextVariables`)\n   - Comprehensive precondition modeling\n   - Sophisticated metaGuidance for complex scenarios\n   - Context variable architecture for data flow\n\n3. **Advanced Feature Implementation**:\n   - **Complex Conditional Logic**: Nested conditions, multiple variable evaluation\n   - **Validation Architecture**: Multi-layered validation with custom criteria\n   - **User Experience Design**: Clarification prompts, confirmation patterns, file sharing\n   - **Performance Considerations**: Step efficiency, resource optimization\n\n4. **Enterprise-Grade Features**:\n   - **Error Handling**: Comprehensive failure modes\n   - **Scalability**: Design for reuse and extension\n   - **Maintainability**: Clear separation of concerns\n   - **Integration**: API-ready for workflow orchestration systems\n\n**ARCHITECTURAL DECISIONS:**\nAgent: Discuss trade-offs and design patterns. Consider:\n- When to use conditional vs. separate workflows\n- Context variable scope and lifecycle\n- Validation strategy (fail-fast vs. comprehensive)\n- Step granularity for optimal user experience\n\n**MASTERY FOCUS:** Creating enterprise-grade workflows with sophisticated architecture.",
       "guidance": [
-        "Focus on finding the root cause of the problem, not just the symptoms.",
-        "A good template is one that solves a problem of similar *structure*, even if the domain is different."
+        "ARCHITECTURAL THINKING: Focus on design patterns, scalability, and maintainability.",
+        "FULL FEATURE ACCESS: Leverage the complete feature set appropriately for the use case.",
+        "PERFORMANCE AWARENESS: Consider efficiency and resource implications.",
+        "ENTERPRISE PATTERNS: Apply proven enterprise workflow patterns.",
+        "EXPERT CONTEXT: Assume understanding of complex concepts, focus on sophisticated applications."
+      ],
+      "validationCriteria": [
+        {
+          "type": "regex",
+          "pattern": "\"id\":\\s*\"[a-zA-Z0-9_-]+\"",
+          "message": "Workflow must have a valid id field with alphanumeric characters, underscores, or hyphens"
+        },
+        {
+          "type": "regex",
+          "pattern": "\"name\":\\s*\"[^\"]{3,}\"",
+          "message": "Workflow must have a descriptive name (at least 3 characters)"
+        },
+        {
+          "type": "regex",
+          "pattern": "\"description\":\\s*\"[^\"]{20,}\"",
+          "message": "Workflow must have a meaningful description (at least 20 characters)"
+        },
+        {
+          "type": "regex",
+          "pattern": "\"steps\":\\s*\\[",
+          "message": "Workflow must have a steps array with at least one step"
+        }
       ]
     },
     {
-      "id": "phase-2-authoring",
-      "title": "Phase 2: Structured Authoring & Drafting",
-      "prompt": "Now we will create the first draft of the new workflow file.\n\n**1. Create the File (Agent's Goal):**\n   - Ask the user for a filename for the new workflow (e.g., `my-new-workflow.json`).\n   - Use the `create_file` tool to create this file, using the template JSON from Phase 1 as the initial content.\n\n**2. Iterative Drafting (Collaborative Task):**\n   - Guide the user through the JSON structure in a specific order: `id`, `name`, `version`, `description`, `preconditions`, `metaGuidance`, and finally the `steps`.\n   - For each section, the user will provide the high-level content, and your goal as the agent is to translate it into correctly formatted JSON and use the `edit_file` tool to update the file.",
+      "id": "phase-3-basic",
+      "runCondition": {"var": "learningPath", "equals": "basic"},
+      "title": "Phase 3: Learning Through Validation (Basic Path)",
+      "prompt": "Great! Your workflow draft is complete. Now let's make sure it works perfectly! 🌱\n\n**UNDERSTANDING VALIDATION:**\nValidation is like proofreading - it catches mistakes before they cause problems. Our validation tool will check:\n- **Syntax**: Is the JSON format correct?\n- **Structure**: Are all required fields present?\n- **Logic**: Do the conditions and references make sense?\n\n**STEP 1: Run Your First Validation**\nAgent: Use `workflow_validate_json` to check the workflow. Explain what the tool is doing and why each check matters.\n\n**STEP 2: Learning from Errors (Don't worry - errors are normal!)**\nAgent: If there are errors (and there usually are!):\n1. **Explain each error type** in simple terms\n2. **Show exactly where** the problem is\n3. **Explain why** it's a problem\n4. **Guide the fix** step-by-step\n5. **Rerun validation** to see progress\n\n**COMMON ERROR TYPES YOU MIGHT SEE:**\n- **Missing quotes**: JSON needs quotes around text\n- **Missing commas**: JSON items need separators\n- **Invalid references**: Steps referencing things that don't exist\n- **Logic errors**: Conditions that don't make sense\n\n**LEARNING GOAL:** Understanding what makes a workflow valid and why each rule exists.\n\nRemember: Every error is a learning opportunity! Professional developers deal with validation errors all the time.",
+      "guidance": [
+        "EDUCATIONAL APPROACH: Treat each error as a teaching moment. Explain what went wrong and why the rule exists.",
+        "STEP-BY-STEP FIXES: Guide through each fix individually, don't overwhelm with multiple changes.",
+        "ENCOURAGE LEARNING: Emphasize that errors are normal and part of the learning process.",
+        "EXPLAIN THE WHY: Help user understand the reasoning behind validation rules.",
+        "BUILD CONFIDENCE: Celebrate when validation passes and acknowledge progress."
+      ],
+      "requireConfirmation": true
+    },
+    {
+      "id": "phase-3-intermediate",
+      "runCondition": {"var": "learningPath", "equals": "intermediate"},
+      "title": "Phase 3: Systematic Validation & Quality Assurance (Intermediate Path)",
+      "prompt": "Time to validate and refine your workflow with systematic quality checks! 🚀\n\n**VALIDATION STRATEGY:**\nWe'll use a layered approach to ensure your workflow is both technically correct and professionally robust.\n\n**STEP 1: Comprehensive Validation**\nAgent: Execute `workflow_validate_json` for complete structural and logical validation.\n\n**STEP 2: Error Pattern Analysis**\nAgent: When issues are found:\n1. **Categorize errors** by type (syntax, logic, reference, etc.)\n2. **Identify patterns** that might indicate systemic issues\n3. **Prioritize fixes** (critical syntax errors first, then logic improvements)\n4. **Apply fixes systematically** using `edit_file`\n5. **Re-validate incrementally** to confirm progress\n\n**QUALITY CHECKPOINTS:**\n- **Structural Integrity**: All required fields, proper JSON formatting\n- **Logical Consistency**: Step references, condition logic, context variables\n- **Best Practice Compliance**: Naming conventions, description quality\n- **Feature Integration**: Proper use of advanced features\n\n**PROFESSIONAL PATTERNS:**\n- Group related fixes together for efficiency\n- Document any trade-offs or design decisions\n- Test edge cases in conditional logic\n- Ensure error messages are actionable\n\n**EFFICIENCY FOCUS:** Systematic error resolution with pattern recognition for faster iteration.",
+      "guidance": [
+        "SYSTEMATIC APPROACH: Handle errors methodically, grouping similar issues for efficient resolution.",
+        "PATTERN RECOGNITION: Help user identify common error patterns and prevention strategies.",
+        "PROFESSIONAL STANDARDS: Apply industry best practices for validation and quality assurance.",
+        "EFFICIENT ITERATION: Balance thoroughness with practical development speed.",
+        "QUALITY FOCUS: Ensure the workflow meets professional standards beyond just 'working'."
+      ],
+      "requireConfirmation": true
+    },
+    {
+      "id": "phase-3-advanced",
+      "runCondition": {"var": "learningPath", "equals": "advanced"},
+      "title": "Phase 3: Advanced Validation & Architectural Review (Advanced Path)",
+      "prompt": "Execute comprehensive validation with performance and architectural considerations! 🏆\n\n**ENTERPRISE VALIDATION APPROACH:**\nMulti-layered validation encompassing syntax, logic, performance, and architectural integrity.\n\n**STEP 1: Comprehensive Technical Validation**\nAgent: Deploy `workflow_validate_json` for complete validation coverage.\n\n**STEP 2: Advanced Error Analysis & Resolution**\nAgent: For any issues identified:\n1. **Root Cause Analysis**: Trace errors to architectural decisions\n2. **Impact Assessment**: Evaluate consequences for scalability and maintainability\n3. **Strategic Resolution**: Fix underlying patterns, not just symptoms\n4. **Performance Optimization**: Consider validation implications for execution efficiency\n5. **Architectural Refinement**: Ensure fixes align with overall design principles\n\n**ENTERPRISE QUALITY GATES:**\n- **Architectural Consistency**: Design patterns, separation of concerns\n- **Performance Implications**: Validation overhead, execution efficiency\n- **Scalability Considerations**: Context variable scope, conditional complexity\n- **Maintainability Factors**: Code clarity, documentation completeness\n- **Integration Readiness**: API compatibility, orchestration system compliance\n\n**ADVANCED VALIDATION CONSIDERATIONS:**\n- **Complex Conditional Logic**: Nested condition validation, variable scope\n- **Context Variable Architecture**: Data flow integrity, lifecycle management\n- **Performance Optimization**: Validation caching, step efficiency\n- **Error Handling Strategy**: Graceful failure modes, recovery patterns\n\n**ARCHITECTURAL REFINEMENT:**\nUse validation feedback to refine architectural decisions and optimize for enterprise deployment.\n\n**MASTERY INDICATORS:** Zero validation errors, optimized performance, enterprise-ready architecture.",
+      "guidance": [
+        "ARCHITECTURAL PERSPECTIVE: View validation through the lens of overall system design and long-term maintainability.",
+        "PERFORMANCE AWARENESS: Consider validation overhead and execution efficiency implications.",
+        "ENTERPRISE STANDARDS: Apply enterprise-grade quality gates and compliance requirements.",
+        "STRATEGIC THINKING: Fix root causes and patterns, not just individual errors.",
+        "OPTIMIZATION FOCUS: Use validation as an opportunity to refine and optimize the workflow architecture."
+      ],
+      "requireConfirmation": true
+    },
+    {
+      "id": "phase-4-basic",
+      "runCondition": {"var": "learningPath", "equals": "basic"},
+      "title": "Phase 4: Simple Testing & Improvement (Basic Path)",
+      "prompt": "Excellent! Your workflow is technically sound. Now let's make sure it's clear and easy to use! 🌱\n\n**WHY TEST WORKFLOWS?**\nTesting helps us find problems before real users do. It's like having friends read your writing before you publish it!\n\n**STEP 1: Choose What to Test**\nUser: Pick one important step from your workflow - maybe the most complex one or the one users will struggle with most.\n\n**STEP 2: Simple Persona Testing**\nAgent: Let's test your chosen step by imagining different types of users:\n\n**👶 The Beginner User:**\n- Would someone new to this topic understand the instructions?\n- Are there any technical words that need explanation?\n- Are the steps clear and specific enough?\n\n**⚡ The Busy User:**\n- Could someone in a hurry misunderstand this?\n- Is it too long or wordy?\n- Could we make it clearer or more direct?\n\n**STEP 3: Make It Better**\nAgent: Based on what we find:\n1. **Explain each problem** in simple terms\n2. **Suggest specific improvements**\n3. **Make the changes** using `edit_file`\n4. **Check our work** with `workflow_validate`\n\n**LEARNING GOAL:** Understanding how to make instructions clear for everyone.\n\nRemember: Good workflows work for both experts and beginners!",
       "guidance": [
-        "When writing prompts, use clear placeholders like `[User provides X]` to indicate where customization is needed.",
-        "Remember: `metaGuidance` is for global rules, while step `prompts` are for specific actions."
+        "SIMPLE APPROACH: Focus on clarity and basic usability rather than complex edge cases.",
+        "EDUCATIONAL FOCUS: Explain why each test matters and what good instructions look like.",
+        "ENCOURAGE EMPATHY: Help user think about different types of people who might use their workflow.",
+        "PRACTICAL IMPROVEMENTS: Focus on concrete, actionable changes that clearly improve usability.",
+        "BUILD CONFIDENCE: Celebrate improvements and explain how testing makes workflows better."
       ]
     },
     {
-      "id": "phase-3-validation",
-      "title": "Phase 3: Syntactic & Structural Validation",
-      "prompt": "The first draft is complete. Now, we must ensure it is technically valid.\n\n**1. Run Validation (Agent's Goal):**\n   - Your goal is to validate the new workflow file. Announce your plan to use the `run_terminal_cmd` tool to execute `workflow-lookup validate [filename]`.\n\n**2. Analyze & Fix (Agent's Goal):**\n   - If validation fails, your goal is to fix it. Parse the error, explain the issue, propose a fix, and use `edit_file` to correct it. Repeat until validation passes.",
+      "id": "phase-4-intermediate",
+      "runCondition": {"var": "learningPath", "equals": "intermediate"},
+      "title": "Phase 4: Systematic Testing & Quality Refinement (Intermediate Path)",
+      "prompt": "Your workflow is validated and ready for comprehensive testing! Let's ensure it's robust and professional. 🚀\n\n**PROFESSIONAL TESTING STRATEGY:**\nSystematic evaluation across multiple user scenarios and edge cases.\n\n**STEP 1: Critical Step Selection**\nUser: Identify 1-2 critical steps that are either complex, have high impact, or involve user decision-making.\n\n**STEP 2: Multi-Persona Analysis**\nAgent: Evaluate selected steps through strategic perspectives:\n\n**🎓 Domain Expert Perspective:**\n- Does the step leverage domain knowledge appropriately?\n- Are there implied assumptions that should be explicit?\n- Could an expert efficiently navigate without losing important context?\n\n**⚡ Efficiency-Focused User:**\n- Can the step be completed quickly without sacrificing quality?\n- Are there unnecessary bottlenecks or redundant confirmations?\n- Is the cognitive load appropriate for the task complexity?\n\n**🔍 Quality-Conscious User:**\n- Does the step provide sufficient guidance for high-quality outcomes?\n- Are validation points appropriate and actionable?\n- Does the step prevent common mistakes effectively?\n\n**STEP 3: Strategic Refinements**\nAgent: Based on analysis:\n1. **Prioritize improvements** by impact and feasibility\n2. **Implement targeted enhancements** using `edit_file`\n3. **Validate consistency** with `workflow_validate`\n4. **Document rationale** for key design decisions\n\n**PROFESSIONAL FOCUS:** Balancing efficiency, quality, and usability for real-world deployment.",
       "guidance": [
-        "Validation errors are expected on the first run. Treat them as a checklist, not a failure.",
-        "Fix one error at a time and re-run validation to avoid introducing new issues."
+        "STRATEGIC THINKING: Focus on improvements that have the highest impact on workflow effectiveness.",
+        "PROFESSIONAL STANDARDS: Apply industry best practices for user experience and process design.",
+        "BALANCED APPROACH: Consider trade-offs between different user needs and workflow goals.",
+        "SYSTEMATIC PROCESS: Use structured analysis to ensure comprehensive coverage of potential issues.",
+        "PRACTICAL DEPLOYMENT: Focus on refinements that matter for real-world workflow usage."
       ]
     },
     {
-      "id": "phase-4-refinement",
-      "title": "Phase 4: Structured Red-Teaming",
-      "prompt": "The workflow is now technically valid. Next, we will rigorously test its logic against multiple personas.\n\n**1. Select a Step (User's Role):**\n   - Please choose a critical step from the new workflow to test.\n\n**2. Structured Simulation (Agent's Goal):**\n   - Your goal is to analyze the selected prompt from the following three perspectives:\n     - **The Novice Persona:** Is there jargon or assumed knowledge that would confuse a newcomer?\n     - **The Rushed Expert Persona:** How could a busy expert misinterpret or shortcut this step? Can it be made more concise?\n     - **The Adversarial LLM Persona:** What ambiguity could be exploited to produce a plausible but incorrect result?\n   - For each persona, provide your findings and suggest specific revisions. Use `edit_file` to implement approved changes.",
+      "id": "phase-4-advanced",
+      "runCondition": {"var": "learningPath", "equals": "advanced"},
+      "title": "Phase 4: Enterprise Testing & Architectural Refinement (Advanced Path)",
+      "prompt": "Execute sophisticated testing with enterprise-grade analysis and optimization! 🏆\n\n**ENTERPRISE TESTING FRAMEWORK:**\nComprehensive evaluation encompassing usability, performance, scalability, and architectural integrity.\n\n**STEP 1: Strategic Component Selection**\nUser: Identify critical workflow components for analysis - focus on high-complexity steps, decision points, or integration touchpoints.\n\n**STEP 2: Advanced Multi-Dimensional Analysis**\nAgent: Execute comprehensive evaluation framework:\n\n**🏗️ Architectural Perspective:**\n- Evaluate step design patterns and consistency\n- Assess scalability implications and resource efficiency\n- Analyze integration points and API compatibility\n- Review error handling and recovery mechanisms\n\n**⚡ Performance & Efficiency Analysis:**\n- Identify potential execution bottlenecks\n- Evaluate context variable usage and lifecycle\n- Assess conditional logic complexity and optimization opportunities\n- Review validation overhead and optimization potential\n\n**🎯 Enterprise User Experience:**\n- Analyze workflows for enterprise deployment scenarios\n- Evaluate multi-user collaboration patterns\n- Assess compliance and audit trail requirements\n- Review customization and configuration flexibility\n\n**🔧 Maintenance & Evolution Considerations:**\n- Evaluate long-term maintainability and extensibility\n- Assess version management and backward compatibility\n- Review documentation and knowledge transfer requirements\n- Analyze monitoring and observability integration\n\n**STEP 3: Strategic Architectural Refinement**\nAgent: Based on comprehensive analysis:\n1. **Architect strategic improvements** addressing systemic opportunities\n2. **Optimize for enterprise deployment** with sophisticated enhancements\n3. **Validate architectural integrity** using `workflow_validate`\n4. **Document architectural decisions** and optimization rationale\n\n**MASTERY OUTCOME:** Enterprise-ready workflow optimized for scalability, maintainability, and sophisticated deployment scenarios.",
       "guidance": [
-        "When simulating personas, be critical. The goal is to find flaws now so that users don't find them later.",
-        "Focus on clarity and ambiguity. If a prompt *can* be misinterpreted, assume it *will* be."
+        "ARCHITECTURAL EXCELLENCE: Focus on sophisticated design patterns and enterprise-grade considerations.",
+        "PERFORMANCE OPTIMIZATION: Identify and address efficiency opportunities across all dimensions.",
+        "ENTERPRISE READINESS: Ensure the workflow meets sophisticated organizational deployment requirements.",
+        "STRATEGIC REFINEMENT: Make improvements that enhance long-term value and architectural integrity.",
+        "COMPREHENSIVE ANALYSIS: Apply enterprise-grade evaluation frameworks for thorough assessment."
       ]
     },
     {
-      "id": "phase-5-deployment",
-      "title": "Phase 5: Finalization & Deployment",
-      "prompt": "The workflow has been drafted, validated, and refined. It is ready for deployment.\n\n**1. Final Review (Collaborative Task):**\n   - Let's perform a final review of the workflow's `name` and `description` to ensure they are clear and easily discoverable.\n\n**2. Deploy (Agent's Goal):**\n   - Once final approval is given, your goal is to move the workflow file into the primary `workflows/` directory. Announce your plan to use the `run_terminal_cmd` tool with the `mv` command to accomplish this.",
+      "id": "phase-5-completion",
+      "title": "Phase 5: Celebration & Growth",
+      "prompt": "🎉 **WORKFLOW CREATION COMPLETE!** 🎉\n\n**STEP 1: Final Review**\nAgent: Review the workflow's `name` and `description`, then run final validation with `workflow_validate_json`.\n\n**STEP 2: Path-Specific Celebration**\n\nAgent: Provide appropriate celebration based on learning path:\n\n**🌱 BASIC PATH:**\nCongratulations! You've created your first workflow with advanced features!\nLearned: Workflow structure, conditional steps, validation, clear guidance.\nNext: Try intermediate path for advanced patterns and sophisticated testing.\n\n**🚀 INTERMEDIATE PATH:**\nExcellent work! You've created a professionally structured workflow!\nMastered: Efficient authoring, strategic features, systematic validation, design patterns.\nNext: Create domain workflows, contribute templates, explore advanced logic.\n\n**🏆 ADVANCED PATH:**\nOutstanding! You've demonstrated workflow architecture mastery!\nAchieved: Sophisticated design, enterprise validation, advanced patterns, expert engineering.\nNext: Lead design, contribute advanced templates, mentor others, explore innovations.\n\n**STEP 3: Completion**\nAgent: Confirm workflow is deployment-ready. For basic/intermediate users, offer level-up opportunities for future workflows.\n\n**UNIVERSAL TRUTH:** Workflow mastery continues with each template. Every workflow is an opportunity to improve!",
       "guidance": [
-        "The `name` and `description` are how others will discover this workflow. Make them descriptive and concise.",
-        "Before moving the file, do a final `ls` to confirm the target directory exists."
+        "ADAPTIVE CELEBRATION: Match the celebration intensity and language to the user's learning path and achievement level.",
+        "GROWTH ORIENTATION: Always provide clear next steps that encourage continued learning and skill development.",
+        "PATH-SPECIFIC GUIDANCE: Tailor advice to the user's demonstrated skill level and learning journey.",
+        "LEVEL-UP OPPORTUNITIES: For basic and intermediate users, gently suggest trying higher complexity paths for future workflows.",
+        "UNIVERSAL PRINCIPLES: End with shared wisdom that applies to all workflow creators regardless of skill level."
+      ],
+      "validationCriteria": [
+        {
+          "type": "length",
+          "min": 500,
+          "message": "Final workflow should be comprehensive (at least 500 characters)"
+        },
+        {
+          "type": "regex",
+          "pattern": "\"steps\":\\s*\\[[^\\]]+\\]",
+          "message": "Final workflow must have at least one complete step"
+        }
       ]
     },
     {
-      "id": "phase-6-feedback-loop",
-      "title": "Phase 6: Establishing a Continuous Improvement Loop",
-      "prompt": "A great workflow evolves. Let's create a mechanism for future feedback.\n\n**1. Create Feedback File (Agent's Goal):**\n   - Your goal is to create a companion feedback file. Announce your plan to use `create_file` to create a file named `[workflow-id].feedback.md` in a `workflow-feedback/` directory.\n\n**2. Populate Feedback Template (Agent's Goal):**\n   - Use `edit_file` to add a basic feedback template to the new file, including sections for 'Success Stories', 'Pain Points', and 'Suggestions for Improvement'.\n\n**3. Link to Feedback (Agent's Goal):**\n   - Announce your plan to add a new `metaGuidance` entry to the *workflow we just created*. The guidance should say: 'After using this workflow, please record your experience in `workflow-feedback/[workflow-id].feedback.md`.' Use `edit_file` to add this.",
+      "id": "level-up-opportunity",
+      "runCondition": {"var": "learningPath", "not_equals": "advanced"},
+      "title": "🚀 Ready to Level Up?",
+      "prompt": "**OPTIONAL: Explore the Next Level**\n\nYou've successfully completed your workflow! Would you like to explore what the next learning path offers for your future workflows?\n\n**FOR BASIC PATH GRADUATES:**\nThe **Intermediate Path** offers:\n- More efficient workflow creation process\n- Advanced feature recommendations based on use case\n- Professional design patterns and best practices\n- Systematic validation and testing approaches\n\n**FOR INTERMEDIATE PATH GRADUATES:**\nThe **Advanced Path** offers:\n- Comprehensive feature utilization from the start\n- Enterprise-grade architectural considerations\n- Performance optimization and scalability patterns\n- Sophisticated testing and validation frameworks\n\n**Remember:** You can always return to your comfortable level - this is just an invitation to explore new possibilities when you're ready!\n\n**Agent Guidance:** If the user expresses interest, provide a brief preview of what they would experience in the next path level. If not interested, celebrate their current achievement and encourage them to practice at their current level.",
       "guidance": [
-        "Ensure the feedback filename (`[workflow-id].feedback.md`) exactly matches the workflow's `id` for easy association.",
-        "The link in the `metaGuidance` should be a relative path to ensure it works for all users."
+        "OPTIONAL EXPLORATION: Make it clear this is purely optional and they've already succeeded.",
+        "NO PRESSURE: Emphasize they can always return to their comfort level.",
+        "PREVIEW VALUE: Show concrete benefits of advancing without making current level seem inadequate.",
+        "RESPECT CHOICE: Whether they advance or stay, celebrate their decision and provide appropriate support."
       ]
     }
   ]