@exaudeus/workrail 0.1.1 → 0.1.3

package/workflows/workflow-for-workflows.json

@@ -15,37 +15,130 @@
         "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.",
+        "fun adaptToPath(content) = 'Deliver {content} with appropriate depth based on learningPath: basic=detailed explanations, intermediate=efficient guidance, advanced=expert context.'",
+        "fun createWorkflowFile(template) = 'After getting filename, create file using {template}. Use adaptToPath() for explanations as you guide through structure.'",
+        "fun runValidation(depth) = 'Execute workflow_validate_json for validation. Use adaptToPath() for error explanations: basic=step-by-step teaching, intermediate=systematic analysis, advanced=architectural review.'",
+        "fun agentInstruct(action) = 'Agent: {action}. Confirm with user before proceeding with file modifications.'",
+        "fun useEditFile(purpose) = 'Use edit_file for {purpose}. Explain changes and validate with workflow_validate.'",
+        "fun teachFeature(feature, context) = 'Introduce {feature} progressively. Use adaptToPath() for explanation depth. Even basic users learn advanced features when {context} demands it.'",
+        "fun gatherDiscovery(focus) = 'Ask 2-3 focused questions about {focus}. Store responses in context.discoveryData. Be conversational and build on previous answers.'",
+        "fun analyzeGaps() = 'Review discoveryData for missing critical information. Identify next area to explore. Set context.questionFocus for next iteration.'",
+        "fun checkConvergence() = 'Evaluate if discovery is sufficient: clear problem, user needs, success criteria defined. Set context.discoveryComplete=true if ready.'",
+        "fun analyzeComplexity(data) = 'Score workflow complexity 1-10 based on {data}. Consider: number of steps, decision branches, integrations, error handling needs.'",
+        "fun suggestSteps(outline) = 'Expand {outline} into full step with prompt, agentRole, guidance using AI pattern recognition from similar workflows.'",
+        "fun visualizeWorkflow() = 'Generate Mermaid diagram showing complete workflow flow, decision points, loops, and context variable usage.'",
+        "fun getSchema() = 'Use workflow_get_schema to retrieve current schema. Reference when building workflow structure to ensure compliance.'",
+        "PROGRESSIVE LEARNING: adaptToPath() throughout - detailed for basic, balanced for intermediate, expert for advanced.",
+        "QUALITY FOCUS: All paths produce sophisticated workflows. Difference is in teaching approach, not final capability.",
         "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.",
+        "agentInstruct() before file modifications or commands.",
         "Maintain a clear distinction between the workflow being created and this meta-workflow.",
         "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."
+        "TOOL INTEGRATION: Use workflow_list/workflow_get for discovery, runValidation() for comprehensive checks, workflow_validate for step validation.",
+        "When validation fails, use detailed error messages to guide improvements rather than guessing at fixes.",
+        "teachFeature() progressively within each path based on use case needs.",
+        "When you see function calls like adaptToPath() or createWorkflowFile(), refer to the function definitions above for full instructions.",
+        "Phase 6 DSL Optimization: For intermediate/advanced users with complex workflows, consider Function Reference Pattern to reduce duplication.",
+        "SCHEMA FIRST: Always getSchema() at start of Phase 2 to ensure compliance with current workflow schema version and structure."
     ],
     "steps": [
         {
-            "id": "phase-0-discovery",
-            "title": "Phase 0: Comprehensive Discovery & Requirements Analysis",
-            "prompt": "**STEP 1: Define the Core Problem & Goal**\n\n- **Problem Statement**: What is the specific, recurring task or problem this new workflow will solve?\n- **Primary Objective**: What is the single most important outcome you want users to achieve by 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? What is their role, expertise level, and what do they need to succeed?\n- **Usage Context**: In what situation or environment 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 can you provide that could inform the design?\n- **Constraints & Requirements**: Are there any specific constraints, required tools, or other absolute 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**: After gathering the user's answers, your goal is to synthesize them into a refined problem statement. Use `workflow_list` and `workflow_get` to find suitable templates based on the problem *structure*, not necessarily the domain, and present your findings for confirmation.",
-            "agentRole": "You are a workflow requirements analyst and discovery specialist with expertise in understanding complex business processes and user needs. Your primary goal is to ask the user the questions below to understand their needs. Do not answer these questions yourself. Wait for the user's detailed response, then synthesize their answers and confirm your understanding before proceeding. Your role is to ask insightful questions, synthesize information effectively, and identify suitable workflow patterns that can be adapted to new use cases.",
+            "id": "phase-0-discovery-loop",
+            "type": "loop",
+            "title": "Phase 0: Adaptive Discovery & Requirements Analysis",
+            "loop": {
+                "type": "while",
+                "condition": {
+                    "and": [
+                        {"var": "discoveryComplete", "not_equals": true},
+                        {"var": "discoveryIteration", "lt": 5}
+                    ]
+                },
+                "maxIterations": 5
+            },
+            "body": [
+                {
+                    "id": "discovery-iteration",
+                    "title": "Discovery Iteration: Gathering Requirements",
+                    "prompt": "gatherDiscovery(current focus area)\n\n**Current Focus:** Understanding the workflow requirements\n\nAgent: For iteration 1, ask the 3 core questions about problem, users, and success. For later iterations, ask targeted follow-ups based on context.questionFocus and context.focusedQuestions.\n\n**Core Questions (Iteration 1):**\n1. What specific, recurring task or problem will this workflow solve?\n2. Who will use this workflow and approximately how often?\n3. What does a successful outcome look like?\n\n**Follow-up Areas (Iterations 2+):**\n- Technical: Integration points, tools, error handling\n- Process: Decision branches, approvals, handoffs\n- Scale: Frequency, user count, growth expectations\n- Constraints: Time limits, compliance, resources",
+                    "agentRole": "You are an adaptive discovery specialist. For iteration 1, ask the core questions. For subsequent iterations, analyze context.discoveryData to identify gaps and ask targeted follow-ups. Store all responses in context.discoveryData. Be conversational and acknowledge previous answers.",
+                    "guidance": [
+                        "ITERATION 1: Focus on problem, users, and success criteria only",
+                        "ITERATION 2+: Based on problem type, explore: technical requirements OR process flows OR creative iterations OR data handling",
+                        "BUILD CONTEXT: Reference previous answers when asking follow-ups",
+                        "STAY FOCUSED: Maximum 3 questions per iteration to avoid overwhelming",
+                        "CONVERGENCE: After each iteration, analyzeGaps() and checkConvergence()"
+                    ],
+                    "requireConfirmation": false
+                },
+                {
+                    "id": "discovery-analysis",
+                    "title": "Analyzing Discovery Progress",
+                    "prompt": "analyzeGaps() to identify what's still needed.\n\n**AI-Powered Analysis:**\n- Pattern recognition: Based on similar workflows, what requirements are commonly missed?\n- Implicit needs: What hasn't been stated but is likely needed?\n- Optimization opportunities: Where could this workflow benefit from advanced features?\n\nReview the discovery data collected so far and determine:\n1. What critical information is still missing?\n2. Which area should we explore next?\n3. Are we ready to proceed to synthesis?\n\ncheckConvergence() to determine if we have enough information.\n\nAgent: Use pattern recognition to suggest unexplored areas. Set context.questionFocus for next iteration OR set context.discoveryComplete=true if ready. Increment context.discoveryIteration.",
+                    "agentRole": "You are a discovery analyst. Review all collected data, identify critical gaps, and determine the next area to explore. Common follow-up areas: integration points, error handling, decision branches, constraints, scale/frequency, evolution needs.",
+                    "guidance": [
+                        "CHECK COMPLETENESS: Problem clarity, user needs, success criteria, basic constraints",
+                        "IDENTIFY GAPS: What's critical but missing? Focus on one area at a time",
+                        "SET FOCUS: Update questionFocus with specific area (e.g., 'integration requirements', 'error handling', 'decision points')",
+                        "GENERATE QUESTIONS: Set context.focusedQuestions with 2-3 specific questions for next iteration",
+                        "KNOW WHEN TO STOP: Don't over-analyze; 80% complete is often enough"
+                    ],
+                    "requireConfirmation": false
+                }
+            ]
+        },
+        {
+            "id": "discovery-synthesis",
+            "title": "Discovery Synthesis & Template Matching",
+            "prompt": "Excellent! I now have a comprehensive understanding of your workflow needs.\n\n**Discovery Summary:**\nAgent: Summarize the key findings from context.discoveryData in a structured format.\n\n**Next Steps:**\n1. I'll synthesize this into a refined problem statement\n2. Use workflow_list and workflow_get to find suitable templates\n3. getSchema() to ensure we build on the latest workflow structure\n4. Present recommendations based on structural patterns\n\nAgent: Create a concise problem statement. Search for workflows with similar patterns (not necessarily same domain). A 'bug investigation' workflow might be perfect for a 'customer complaint' workflow if they share similar structures.",
+            "agentRole": "You are a workflow synthesis expert. Compile all discovery data into a clear, actionable problem statement. Use workflow_list and workflow_get to find templates based on structural similarity. Present 2-3 best matches with explanations.",
             "guidance": [
-                "BE SPECIFIC: Vague goals lead to vague workflows. The more precise the user's answers are here, the better the final product.",
-                "THINK ABOUT THE USER: A workflow for an expert looks very different from one for a novice. Encourage the user to be detailed about their audience.",
-                "REQUEST EXAMPLES: If the user mentions examples of the problem or desired outcome, ask them to share them.",
-                "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."
+                "SYNTHESIZE: Create clear, one-paragraph problem statement",
+                "PATTERN MATCH: Focus on workflow structure, not domain",
+                "RECOMMEND: Present 2-3 template options with rationale",
+                "CONFIRM: Get user agreement before proceeding to learning path selection"
             ],
             "askForFiles": true,
             "requireConfirmation": true
         },
+        {
+            "id": "phase-1-25-complexity-analysis",
+            "title": "Phase 1.25: Workflow Complexity Analysis",
+            "prompt": "Based on the discovery data, I'll analyze the workflow complexity to recommend the best learning path.\n\nanalyzeComplexity(discoveryData)\n\n**Complexity Factors Being Evaluated:**\n- Problem domain complexity (technical depth required)\n- Number of potential decision points\n- Integration requirements (tools, systems, APIs)\n- Error handling and recovery needs\n- Data transformation requirements\n- User expertise vs. task complexity gap\n\n**Scoring Guide:**\n- 1-3: Simple, linear workflows (Basic path ideal)\n- 4-7: Moderate complexity with some branching (Intermediate path recommended)\n- 8-10: Complex with multiple integrations/decisions (Advanced path beneficial)\n\nAgent: Calculate complexity score and set context.complexityScore. Determine context.recommendedPath based on score AND user experience. Explain reasoning.",
+            "agentRole": "You are a workflow complexity analyst. Evaluate the discovered requirements objectively. Consider technical complexity, decision density, integration needs, and error handling requirements. Balance complexity score with user's stated experience level.",
+            "guidance": [
+                "OBJECTIVE SCORING: Don't over-complicate simple workflows",
+                "FACTOR WEIGHTS: Integrations and branching logic add more complexity than step count",
+                "PATH MATCHING: Score 1-3→basic, 4-7→intermediate, 8-10→advanced, but adjust for user experience",
+                "EXPLAIN REASONING: Always explain why you scored as you did",
+                "SET CONTEXT: Store complexityScore, recommendedPath, and complexityFactors in context"
+            ],
+            "requireConfirmation": false
+        },
+        {
+            "id": "phase-0-5-research",
+            "title": "Phase 0.5: Deep Research & Inspiration Gathering",
+            "prompt": "adaptToPath('Enhance your workflow with external knowledge! I'll generate a research prompt for deep analysis on your workflow type's best practices, patterns, and examples. Copy-paste it into ChatGPT/Claude/Gemini, then share the results. We'll synthesize key insights into your workflow ideas.')",
+            "agentRole": "You are a research specialist with expertise in generating targeted research prompts and synthesizing external knowledge. Generate a tailored prompt like: 'Research top 10 best practices for [workflow type] workflows, focusing on [problem]. Include real-world examples, step patterns, and innovations. Output in structured format: {insights: [], patterns: [], suggestedSteps: []}'. After user provides results, synthesize into workflow recommendations and store in context.researchInsights.",
+            "guidance": [
+                "Make research optional for basic path; mandatory for intermediate/advanced.",
+                "Store synthesized results in context variable 'researchInsights'.",
+                "Generate research prompts that target external best practices and innovations.",
+                "Focus on structural patterns that can be adapted to the user's specific domain."
+            ],
+            "runCondition": {
+                "or": [
+                    {"var": "learningPath", "equals": "intermediate"},
+                    {"var": "learningPath", "equals": "advanced"}
+                ]
+            },
+            "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\ud83c\udf31 **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\ud83d\ude80 **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\ud83c\udfc6 **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'.",
+            "prompt": "Excellent! With a clear understanding of your goals, let's choose the best way to build your workflow.\n\n**Complexity Analysis Results:**\nAgent: Display the complexity score, recommended path, and key factors from context.\n\nPlease select your experience level with workflow creation:\n\n\ud83c\udf31 **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\ud83d\ude80 **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\ud83c\udfc6 **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\nagentInstruct(set learningPath context variable to user's selection. Highlight which path matches the complexity analysis recommendation.)",
             "agentRole": "You are a workflow education specialist and learning path advisor with expertise in adapting technical instruction to different experience levels. Your role is to help users choose the most appropriate learning approach based on their background and goals.",
             "guidance": [
                 "PATH EXPLANATION: Clearly explain what each learning path offers so users can make an informed choice based on the discovery from Phase 0.",
@@ -53,6 +146,19 @@
             ],
             "requireConfirmation": true
         },
+        {
+            "id": "phase-1-5-ideation",
+            "title": "Phase 1.5: Brainstorm & Ideate Workflow Elements",
+            "prompt": "teachFeature(brainstorming, using researchInsights). Based on your goals and any research insights gathered, let's brainstorm innovative workflow elements!\n\nI'll generate 3-5 creative ideas for:\n- Unique step sequences that could make your workflow more effective\n- Advanced features that could enhance user experience\n- Innovative patterns adapted from other domains\n- Potential safeguards or quality checks\n\nAfter presenting ideas, we'll discuss pros/cons and refine based on your feedback.",
+            "agentRole": "You are an ideation expert specializing in workflow innovation. Use research insights (if available) and cross-domain thinking to propose creative, non-generic workflow designs. Present ideas with clear benefits and trade-offs. Store refined ideas in context.ideationNotes.",
+            "guidance": [
+                "Integrate 'researchInsights' if available from Phase 0.5",
+                "Propose both conventional and unconventional approaches",
+                "Explain how each idea addresses the user's specific goals",
+                "Store refined/selected ideas in 'ideationNotes' context variable"
+            ],
+            "requireConfirmation": true
+        },
         {
             "id": "phase-2-basic",
             "runCondition": {
@@ -60,14 +166,15 @@
                 "equals": "basic"
             },
             "title": "Phase 2: Guided Workflow Creation (Basic Path)",
-            "prompt": "Let's create your workflow step-by-step with detailed explanations! \ud83c\udf31\n\n**STEP 1: Create Your Workflow File**\nFirst, what would you like to name your new workflow file? (e.g., `my-workflow.json`)\n\n(Agent: After getting the filename, create the file using the template from Phase 1, then explain each field as you help the user fill it out.)\n\n**STEP 2: Build the Structure Together**\nNow, let's go through each part of your workflow one by one:\n\n1.  **Basic Info** (`id`, `name`, `version`, `description`)\n    - (Agent: For each field, explain why it matters and help the user craft clear, descriptive content.)\n2.  **Setup Requirements** (`preconditions`)\n    - (Agent: Explain what preconditions are, why they prevent problems, and ask the user what's needed.)\n3.  **Global Rules** (`metaGuidance`)\n    - (Agent: Explain the difference between global rules and step-specific instructions, and ask for input.)\n4.  **The Action Steps** (`steps`)\n    - (Agent: Guide the user in creating simple, linear steps first. Then, explain that workflows can also have more advanced features. If their workflow seems to need them, introduce concepts like conditional steps, context variables, and validation with clear examples and ask if they'd like to add them.)\n\n**LEARNING FOCUS:** We'll focus on understanding what each piece does and why it's useful.",
+            "prompt": "Let's create your workflow step-by-step with detailed explanations! \ud83c\udf31\n\n**STEP 0: Schema Foundation**\nFirst, I'll getSchema() to ensure we build on the current workflow structure.\n\n**STEP 1: Create Your Workflow File**\nWhat would you like to name your new workflow file? (e.g., `my-workflow.json`)\n\ncreateWorkflowFile(template from Phase 1)\n\n**STEP 2: Build the Structure Together**\nNow, let's go through each part of your workflow one by one:\n\n1.  **Basic Info** (`id`, `name`, `version`, `description`)\n    - (Agent: For each field, explain why it matters and help the user craft clear, descriptive content.)\n2.  **Setup Requirements** (`preconditions`)\n    - (Agent: Explain what preconditions are, why they prevent problems, and ask the user what's needed.)\n3.  **Global Rules** (`metaGuidance`)\n    - (Agent: Explain the difference between global rules and step-specific instructions, and ask for input.)\n4.  **The Action Steps** (`steps`)\n    - (Agent: Guide the user in creating simple, linear steps first. When user provides step outline, suggestSteps() to expand into full format. Analyze goal/research for needed features (e.g., conditions for branching, loops for repetition) and teachFeature() if appropriate.)\n5.  **Quality Integration**\n    - (Agent: useTools() to read docs like naming-conventions.md and suggest pattern integrations based on ideationNotes if available.)\n\n**AI ASSISTANCE:** When you describe a step briefly, I'll help expand it into a complete step with prompt, agentRole, and guidance!\n\n**LEARNING FOCUS:** We'll focus on understanding what each piece does and why it's useful.",
             "agentRole": "You are a patient and thorough workflow education instructor specializing in teaching beginners. Your goal is to guide the user collaboratively. Ask for one piece of information at a time, explain the concepts, and wait for their input before proceeding. Your expertise lies in breaking down complex concepts into understandable steps, providing clear explanations for why each element matters, and building user confidence through hands-on learning.",
             "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."
+                "QUALITY TEACHING: Even though this is the basic path, don't compromise on workflow quality - just explain more.",
+                "AI ASSIST: When user provides step outline, use suggestSteps() to expand into full format with all required fields"
             ],
             "validationCriteria": [
                 {
@@ -100,14 +207,16 @@
                 "equals": "intermediate"
             },
             "title": "Phase 2: Structured Workflow Development (Intermediate Path)",
-            "prompt": "Let's build your workflow with a structured approach and best practices! \ud83d\ude80\n\n**STEP 1: Initialize Workflow File**\nFirst, what would you like to name your new workflow file?\n\n(Agent: After getting the filename, create the file using the template from Phase 1. Use efficient, clear explanations as you guide the user through the core structure.)\n\n**STEP 2: Core Structure Development**\nWe'll build your workflow systematically. For each section, I will explain its purpose and best practices, then ask for your input:\n\n1.  **Metadata & Identity** (`id`, `name`, `version`, `description`)\n    - Focus on discoverability and clear communication.\n2.  **Operational Requirements** (`preconditions`, `metaGuidance`)\n    - Define what's needed before starting and establish global rules.\n3.  **Step Architecture**\n    - Design clear, actionable steps.\n\n**STEP 3: Enhanced Feature Recommendations**\nBased on your workflow's purpose, I may recommend specific features like:\n- **Clarification Prompts**: To gather better input upfront.\n- **Validation Criteria**: For automatic quality checks.\n- **Context Variables**: When you need information to flow between steps.\n- **Conditional Logic**: For workflows with decision points.\n\n(Agent: As you build the steps, proactively recommend these features where they seem appropriate, explaining the benefits.)\n\n**EFFICIENCY FOCUS:** We'll focus on building a professionally structured workflow with the right features for the job.",
+            "prompt": "Let's build your workflow with a structured approach and best practices! \ud83d\ude80\n\n**STEP 0: Schema & Foundation**\ngetSchema() to ensure compliance with current workflow structure.\n\n**STEP 1: Initialize Workflow File**\nWhat would you like to name your new workflow file?\n\ncreateWorkflowFile(template from Phase 1)\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.\n2.  **Operational Requirements** (`preconditions`, `metaGuidance`)\n    - Define what's needed before starting and establish global rules.\n3.  **Step Architecture with AI Assistance**\n    - Design clear, actionable steps.\n    - When you outline a step, I'll suggestSteps() to expand it professionally.\n    - Analyze goal/research for needed features (e.g., loops for multi-item processing) and teachFeature() proactively.\n4.  **Context Variable Intelligence**\n    - I'll analyze your steps and suggest which context variables you'll need for data flow.\n5.  **Quality Patterns**\n    - useTools() to examine existing workflows and docs to suggest proven patterns from ideationNotes.\n\n**STEP 3: Enhanced Feature Recommendations**\nBased on your workflow's purpose, I may recommend specific features like:\n- **Clarification Prompts**: To gather better input upfront.\n- **Validation Criteria**: For automatic quality checks.\n- **Context Variables**: When you need information to flow between steps.\n- **Conditional Logic**: For workflows with decision points.\n\n(Agent: As you build the steps, proactively recommend these features where they seem appropriate, explaining the benefits. Integrate researchInsights and ideationNotes into recommendations.)\n\n**EFFICIENCY FOCUS:** We'll focus on building a professionally structured workflow with the right features for the job.",
             "agentRole": "You are an experienced workflow development consultant with expertise in efficient workflow creation and best practices. You will act as a collaborator, guiding the user through the creation process efficiently. Your role is to guide users through structured development while recommending appropriate features and maintaining professional standards.",
             "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."
+                "BALANCED DEPTH: Provide enough detail to understand without overwhelming with basics.",
+                "AI OPTIMIZATION: Use suggestSteps() to expand outlines; analyze steps to suggest context variables",
+                "PATTERN MATCHING: Leverage AI to identify similar workflow patterns and suggest optimizations"
             ],
             "validationCriteria": [
                 {
@@ -140,14 +249,16 @@
                 "equals": "advanced"
             },
             "title": "Phase 2: Comprehensive Workflow Architecture (Advanced Path)",
-            "prompt": "Let's architect a sophisticated workflow with full feature utilization. \ud83c\udfc6\n\n**STEP 1: Rapid File Initialization**\nTo begin, what filename shall we use for the new workflow?\n\n(Agent: After getting the filename, create the file with the template foundation. Then, shift the focus to architectural decisions.)\n\n**STEP 2: Architectural Design Discussion**\nLet's discuss the high-level architecture. For each area, I will present advanced considerations and ask for your design choices:\n\n1.  **Core Architecture** (`id`, `name`, `version`, `description`)\n    - (Agent: Discuss semantic versioning strategy, namespace considerations, and treating the description as API documentation.)\n2.  **Operational Design** (`preconditions`, `metaGuidance`, `contextVariables`)\n    - (Agent: Discuss comprehensive precondition modeling, sophisticated metaGuidance for complex scenarios, and context variable architecture for data flow.)\n3.  **Advanced Feature Implementation & Step Design**\n    - (Agent: Discuss trade-offs and design patterns for conditional logic, validation strategy, user experience, performance, and enterprise-grade features like error handling and scalability.)\n\n**MASTERY FOCUS:** Our goal is to collaborate on creating an enterprise-grade workflow with a sophisticated and intentional architecture.",
+            "prompt": "Let's architect a sophisticated workflow with full feature utilization. \ud83c\udfc6\n\n**STEP 0: Schema & Architecture Foundation**\ngetSchema() to ensure we leverage all available features properly.\n\n**STEP 1: Rapid File Initialization**\nWhat filename shall we use for the new workflow?\n\ncreateWorkflowFile(template foundation) and shift to architectural decisions\n\n**STEP 2: Architectural Design with AI Enhancement**\nLet's discuss the high-level architecture:\n\n1.  **Core Architecture** (`id`, `name`, `version`, `description`)\n    - Semantic versioning strategy, namespace considerations, API documentation approach.\n2.  **Operational Design** (`preconditions`, `metaGuidance`, `contextVariables`)\n    - Comprehensive precondition modeling, sophisticated metaGuidance patterns.\n    - AI-powered context variable architecture based on data flow analysis.\n3.  **Advanced Step Design with Optimization**\n    - Trade-offs for conditional logic, validation strategy, performance.\n    - suggestSteps() with enterprise patterns when you provide high-level design.\n    - AI-suggested step ordering for optimal execution flow.\n4.  **Innovation Integration**\n    - useTools() to analyze existing enterprise workflows.\n    - AI-powered pattern recognition for non-obvious optimizations.\n    - Leverage researchInsights for cutting-edge approaches.\n\n**AI ARCHITECTURE ASSISTANT:** I'll analyze your design decisions and suggest:\n- Optimal step sequencing\n- Advanced validation criteria\n- Performance optimizations\n- Scalability considerations\n\n**MASTERY FOCUS:** Creating an enterprise-grade workflow with sophisticated, AI-enhanced architecture.",
             "agentRole": "You are a senior workflow architect and systems design expert with deep expertise in enterprise-grade workflow engineering. Your role is to act as an architectural consultant. You will propose design patterns and discuss trade-offs with the user. Your role is to engage in sophisticated technical discussions, propose advanced design patterns, and help users create workflows that meet enterprise standards for scalability, maintainability, and performance.",
             "guidance": [
                 "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."
+                "EXPERT CONTEXT: Assume understanding of complex concepts, focus on sophisticated applications.",
+                "AI ARCHITECTURE: Use AI to suggest optimal patterns, step ordering, and performance optimizations",
+                "INNOVATION ENGINE: Leverage AI pattern recognition for non-obvious workflow enhancements"
             ],
             "validationCriteria": [
                 {
@@ -174,13 +285,29 @@
             "hasValidation": true
         },
         {
-            "id": "phase-3-basic",
+            "id": "phase-3-4-refinement-loop",
+            "type": "loop",
+            "title": "Phases 3-4: Iterative Validation & Refinement Loop",
+            "loop": {
+                "type": "while",
+                "condition": {
+                    "and": [
+                        {"var": "satisfactionScore", "lt": 9},
+                        {"var": "iterationCount", "lt": 3}
+                    ]
+                },
+                "maxIterations": 3
+            },
+
+            "body": [
+                {
+                    "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! \ud83c\udf31\n\n**UNDERSTANDING VALIDATION:**\nValidation is like proofreading - it catches mistakes before they cause problems. Our validation tool will check for issues with syntax, structure, and logic.\n\n**STEP 1: Run Your First Validation**\nI will now use the `workflow_validate_json` tool to check your workflow. I'll explain what the tool is doing and why each check matters.\n\n(Agent: Run the tool.)\n\n**STEP 2: Learning from Errors (Don't worry - errors are normal!)**\nIf there are errors, I will guide you through them one at a time:\n1.  **Explain the error** in simple terms.\n2.  **Show you where** the problem is in the file.\n3.  **Explain why** it's a problem.\n4.  **Help you fix it** step-by-step.\n5.  Then, we'll **rerun validation** to see our progress.\n\n**LEARNING GOAL:** Our goal is to understand what makes a workflow valid and why each rule exists. Every error is a learning opportunity!",
+            "prompt": "Great! Your workflow draft is complete. Now let's make sure it works perfectly! \ud83c\udf31\n\n**UNDERSTANDING VALIDATION:**\nValidation is like proofreading - it catches mistakes before they cause problems. Our validation tool will check for issues with syntax, structure, and logic.\n\n**STEP 1: Run Your First Validation**\nrunValidation(basic) with detailed explanations\n\n**STEP 2: Learning from Errors (Don't worry - errors are normal!)**\nIf there are errors, I will guide you through them one at a time:\n1.  **Explain the error** in simple terms.\n2.  **Show you where** the problem is in the file.\n3.  **Explain why** it's a problem.\n4.  **Help you fix it** step-by-step.\n5.  Then, we'll **rerun validation** to see our progress.\n\n**LEARNING GOAL:** Our goal is to understand what makes a workflow valid and why each rule exists. Every error is a learning opportunity!",
             "agentRole": "You are a supportive workflow validation instructor with expertise in teaching through problem-solving. Your goal is to run the validation tool and then guide the user through fixing any errors one by one, explaining each concept as you go. Your role is to turn validation errors into learning opportunities, explaining technical concepts in accessible terms while building user confidence in workflow creation.",
             "guidance": [
                 "EDUCATIONAL APPROACH: Treat each error as a teaching moment. Explain what went wrong and why the rule exists.",
@@ -198,7 +325,7 @@
                 "equals": "intermediate"
             },
             "title": "Phase 3: Systematic Validation & Quality Assurance (Intermediate Path)",
-            "prompt": "Time to validate and refine your workflow with systematic quality checks. \ud83d\ude80\n\n**STEP 1: Comprehensive Validation**\nI will now execute `workflow_validate_json` for a complete structural and logical validation of your workflow.\n\n(Agent: Run the tool.)\n\n**STEP 2: Error Pattern Analysis & Resolution**\nWhen issues are found, we will address them systematically:\n1.  **Categorize errors** by type (e.g., syntax, logic, reference).\n2.  **Identify patterns** that might indicate a recurring misunderstanding.\n3.  **Prioritize fixes**, starting with critical syntax errors.\n4.  **Apply fixes efficiently**, grouping related changes.\n5.  **Re-validate incrementally** to confirm progress.\n\n(Agent: Guide the user through this analysis and resolution process, explaining your reasoning at each step.)\n\n**EFFICIENCY FOCUS:** Our goal is systematic error resolution and pattern recognition for faster iteration.",
+            "prompt": "Time to validate and refine your workflow with systematic quality checks. \ud83d\ude80\n\n**STEP 1: Comprehensive Validation**\nrunValidation(intermediate) for systematic analysis\n\n**STEP 2: Error Pattern Analysis & Resolution**\nWhen issues are found, we will address them systematically:\n1.  **Categorize errors** by type (e.g., syntax, logic, reference).\n2.  **Identify patterns** that might indicate a recurring misunderstanding.\n3.  **Prioritize fixes**, starting with critical syntax errors.\n4.  **Apply fixes efficiently**, grouping related changes.\n5.  **Re-validate incrementally** to confirm progress.\n\n(Agent: Guide the user through this analysis and resolution process, explaining your reasoning at each step.)\n\n**EFFICIENCY FOCUS:** Our goal is systematic error resolution and pattern recognition for faster iteration.",
             "agentRole": "You are a workflow quality assurance specialist with expertise in systematic validation and error pattern analysis. Your role is to run the validator, analyze the results for patterns, and then guide the user through a systematic fix process. Your role is to efficiently identify and resolve validation issues while teaching users to recognize and prevent common problems in future workflow development.",
             "guidance": [
                 "SYSTEMATIC APPROACH: Handle errors methodically, grouping similar issues for efficient resolution.",
@@ -216,7 +343,7 @@
                 "equals": "advanced"
             },
             "title": "Phase 3: Advanced Validation & Architectural Review (Advanced Path)",
-            "prompt": "Let's execute a comprehensive validation with an eye for performance and architectural integrity. \ud83c\udfc6\n\n**STEP 1: Comprehensive Technical Validation**\nI will now deploy `workflow_validate_json` for complete validation coverage.\n\n(Agent: Run the tool.)\n\n**STEP 2: Advanced Error Analysis & Architectural Resolution**\nFor any issues found, we will perform a deep analysis:\n1.  **Root Cause Analysis**: Let's trace the errors back to their architectural source.\n2.  **Impact Assessment**: We'll evaluate the consequences for scalability and maintainability.\n3.  **Strategic Resolution**: I will help you fix the underlying patterns, not just the symptoms.\n4.  **Architectural Refinement**: We'll ensure the fixes align with our overall design principles.\n\n(Agent: Lead the user through this discussion, proposing and implementing fixes collaboratively.)\n\n**MASTERY FOCUS:** We will use validation feedback to refine architectural decisions and optimize for enterprise deployment.",
+            "prompt": "Let's execute a comprehensive validation with an eye for performance and architectural integrity. \ud83c\udfc6\n\n**STEP 1: Comprehensive Technical Validation**\nrunValidation(advanced) for architectural review\n\n**STEP 2: Advanced Error Analysis & Architectural Resolution**\nFor any issues found, we will perform a deep analysis:\n1.  **Root Cause Analysis**: Let's trace the errors back to their architectural source.\n2.  **Impact Assessment**: We'll evaluate the consequences for scalability and maintainability.\n3.  **Strategic Resolution**: I will help you fix the underlying patterns, not just the symptoms.\n4.  **Architectural Refinement**: We'll ensure the fixes align with our overall design principles.\n\n(Agent: Lead the user through this discussion, proposing and implementing fixes collaboratively.)\n\n**MASTERY FOCUS:** We will use validation feedback to refine architectural decisions and optimize for enterprise deployment.",
             "agentRole": "You are a principal workflow architect and validation expert with deep expertise in enterprise-grade quality assurance. Your role is to run the validator and then lead an advanced analysis of the errors, connecting them back to architectural decisions. Your role is to conduct sophisticated technical analysis, identify architectural implications of validation issues, and guide strategic resolution that enhances overall workflow design.",
             "guidance": [
                 "ARCHITECTURAL PERSPECTIVE: View validation through the lens of overall system design and long-term maintainability.",
@@ -278,10 +405,19 @@
                 "COMPREHENSIVE ANALYSIS: Apply enterprise-grade evaluation frameworks for thorough assessment."
             ]
         },
+        {
+            "id": "satisfaction-check",
+            "title": "Iteration Satisfaction Check",
+            "prompt": "Let's assess your satisfaction with the workflow so far.\n\n**Rate your satisfaction (1-10):**\n- 10: Perfect! Ready to deploy\n- 8-9: Very good, minor tweaks only\n- 6-7: Good foundation, needs refinement\n- 4-5: Major improvements needed\n- 1-3: Significant rework required\n\nBased on your rating:\n- Score 9+: We'll proceed to completion\n- Score 7-8: For advanced users, checkAutomation(auto-continue)\n- Score <7: We'll iterate again (up to 3 times total)\n\nAgent: Set context.satisfactionScore and increment context.iterationCount",
+            "agentRole": "You are a quality assessment specialist. Guide the user through evaluating their workflow objectively. Store the score in context for loop control.",
+            "requireConfirmation": false
+        }
+            ]
+        },
         {
             "id": "phase-5-completion",
             "title": "Phase 5: Celebration & Growth",
-            "prompt": "\ud83c\udf89 **WORKFLOW CREATION COMPLETE!** \ud83c\udf89\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**\ud83c\udf31 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**\ud83d\ude80 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**\ud83c\udfc6 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!",
+            "prompt": "\ud83c\udf89 **WORKFLOW CREATION COMPLETE!** \ud83c\udf89\n\n**STEP 1: Final Review**\nagentInstruct(review workflow name and description, then runValidation(final))\n\n**STEP 2: Path-Specific Celebration**\n\nagentInstruct(provide adaptToPath(celebration) based on learning path):\n\n**\ud83c\udf31 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**\ud83d\ude80 INTERMEDIATE PATH:**\nExcellent work! You've created a professionally structured workflow!\nMastered: Efficient authoring, strategic features, systematic validation, design patterns.\nNext: Consider Phase 6 optimization, create domain workflows, explore advanced logic.\n\n**\ud83c\udfc6 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: Documentation & Quality Metrics**\ncreateFile(README.md) with usage instructions generated from workflow content.\n\n**Quality Rubric - Rate your workflow:**\n- Clarity: How clear are the instructions? (1-10)\n- Adaptability: How well does it handle edge cases? (1-10)\n- Innovation: How creative is the approach? (1-10)\n- Maintainability: How easy to update? (1-10)\n\nAgent: If any score < 8, suggest specific improvements.\n\n**STEP 4: 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": [
                 "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.",
@@ -303,6 +439,40 @@
             ],
             "hasValidation": true
         },
+        {
+            "id": "phase-5-5-visual-preview",
+            "title": "Phase 5.5: Visual Workflow Preview",
+            "prompt": "Let's visualize your workflow to see the complete flow! 🎨\n\nvisualizeWorkflow() to generate a comprehensive diagram.\n\n**Creating Mermaid Diagram:**\nI'll generate a flowchart showing:\n- Complete step sequence\n- Decision branches (conditional steps)\n- Loop structures\n- Context variable flow\n- Learning path variations\n\nAgent: Use create_diagram to generate a Mermaid flowchart. Include:\n1. All workflow steps as nodes\n2. Conditional branches with decision labels\n3. Loop indicators with iteration info\n4. Context variables as data flow annotations\n5. Different colors for different phases or complexity levels\n\n**Example Structure:**\n```mermaid\nflowchart TD\n    Start([\"🚀 Workflow Start\"])\n    Discovery[\"Phase 0: Discovery Loop<br/>Gather Requirements\"]\n    Complexity[\"Phase 1.25: Complexity Analysis<br/>Score: context.complexityScore\"]\n    PathSelect{{\"Learning Path Selection<br/>Basic/Intermediate/Advanced\"}}\n    ...\n    End([\"✅ Workflow Complete\"])\n```\n\n**Benefits of Visualization:**\n- See the complete workflow structure at a glance\n- Verify logical flow and dependencies\n- Identify optimization opportunities\n- Great for documentation and team sharing",
+            "agentRole": "You are a workflow visualization expert. Create clear, comprehensive Mermaid diagrams that accurately represent the workflow structure, including all paths, conditions, and data flows.",
+            "guidance": [
+                "COMPLETE COVERAGE: Include every step, even conditional ones",
+                "CLEAR LABELING: Use descriptive labels for all nodes and edges",
+                "VISUAL HIERARCHY: Use subgraphs for loops and phases",
+                "DATA FLOW: Show context variable usage with annotations",
+                "ACCESSIBILITY: Ensure diagram is readable and well-organized"
+            ],
+            "requireConfirmation": false
+        },
+        {
+            "id": "phase-6-dsl-optimization",
+            "title": "Phase 6: Optimize with Function Reference Pattern (Advanced)",
+            "prompt": "**WORKFLOW OPTIMIZATION OPPORTUNITY** 🔧\n\nYour workflow is complete and functional! Now let's make it more maintainable and efficient using the **Function Reference Pattern** - an advanced technique for reducing duplication.\n\n**STEP 1: Analyze for Duplication**\nLet's examine your workflow for repeated instruction patterns:\n- Look for similar phrases across multiple step prompts\n- Identify repeated tool usage instructions (edit_file, workflow_validate, etc.)\n- Find common guidance patterns that appear in multiple places\n\n**STEP 2: Identify Function Candidates**\nBased on your workflow, we might create functions like:\n```\nfun createFile(filename) = 'Use edit_file to create {filename}. Explain the structure as you build it.'\nfun runValidation() = 'Execute workflow_validate_json. Explain any errors found and guide through fixes step-by-step.'\nfun adaptToPath(content) = 'Deliver {content} with appropriate depth based on learningPath: basic=detailed explanations, intermediate=efficient guidance, advanced=expert context.'\n```\n\n**STEP 3: Implementation Decision**\nFunction references work best for workflows with:\n✅ 10+ steps with shared patterns\n✅ Repeated instruction blocks\n✅ Long prompts hitting character limits\n✅ Team workflows needing consistency\n\n**Agent Instructions:**\n1. Analyze the created workflow for duplication patterns\n2. If suitable (complex workflow with repeated patterns), propose specific function definitions\n3. Show examples of how 2-3 steps would look with function references\n4. Calculate potential file size reduction\n5. Let user decide whether to implement this optimization\n\nThis is an **optional advanced technique** - the workflow is already complete and functional!",
+            "agentRole": "You are a workflow optimization specialist with expertise in the Function Reference Pattern (DSL approach). Your role is to analyze the completed workflow for duplication opportunities and guide the user through the decision of whether to apply this advanced optimization technique.",
+            "guidance": [
+                "PATTERN RECOGNITION: Look for repeated instruction blocks, tool usage patterns, and similar guidance across steps.",
+                "BENEFIT ANALYSIS: Calculate concrete benefits (file size reduction, consistency improvement, maintenance ease).",
+                "OPTIONAL OPTIMIZATION: Make it clear this is an advanced, optional technique - the workflow already works.",
+                "PRACTICAL EXAMPLES: Show concrete before/after examples from their actual workflow.",
+                "USER CHOICE: Let them decide based on their workflow complexity and maintenance needs."
+            ],
+            "runCondition": {
+                "or": [
+                    {"var": "learningPath", "equals": "intermediate"},
+                    {"var": "learningPath", "equals": "advanced"}
+                ]
+            },
+            "requireConfirmation": true
+        },
         {
             "id": "level-up-opportunity",
             "runCondition": {