feat(workflows_mcp): add three-level nested workflow handling with pause/resume support

Introduced a new feature allowing the orchestration of three-level nested workflows, including pause and resume functionality. This change addresses a bug where the parent workflow's remaining blocks would not execute after a child workflow resumes from a pause state.

Additional changes include:
- Updated orchestrator logic to handle nested workflows with proper checkpointing and iteration result serialization.
- Enhanced YAML templates for workflow composition, allowing sub-workflows to be saved in hierarchical directories.
- Added new test cases to ensure the correct execution of three-level nested workflows, particularly focusing on scenarios involving pauses and resumes.

Author: ibacalu

src/workflows_mcp/engine/orchestrator.py

@@ -501,6 +501,55 @@ async def resume_for_each(
         )
         iteration_results[current_key] = resumed_result
 
+        # Check if resumed iteration is STILL paused (nested workflow paused again)
+        # This handles the case where a nested workflow (e.g., parent with for_each)
+        # resumes one child but then pauses on the next child in its own for_each.
+        if resumed_result.paused:
+            # Validate pause_prompt is present
+            if not resumed_result.pause_prompt:
+                raise RuntimeError(f"Block {current_key} marked as paused but pause_prompt is None")
+
+            # Create checkpoint for the still-paused iteration
+            # No iteration completed beyond what was already completed
+            all_completed_keys = list(completed_keys)  # Only previously completed
+
+            # Serialize completed iteration results for checkpoint (ADR-010)
+            completed_iteration_results = {}
+            for comp_key in all_completed_keys:
+                if comp_key in iteration_results:
+                    exec_result = iteration_results[comp_key]
+                    completed_iteration_results[comp_key] = {
+                        "inputs": exec_result.inputs if hasattr(exec_result, "inputs") else {},
+                        "output": (exec_result.output.model_dump() if exec_result.output else None),
+                        "metadata": exec_result.metadata.model_dump(),
+                        "paused": exec_result.paused,
+                    }
+
+            for_each_checkpoint = {
+                "type": "for_each_iteration",
+                "for_each_block_id": block_id,
+                "current_iteration_key": current_key,
+                "current_iteration_index": current_idx,
+                "completed_iterations": all_completed_keys,
+                "completed_iteration_results": completed_iteration_results,
+                "remaining_iteration_keys": remaining_keys,  # Still need to process these
+                "all_iterations": all_iterations,
+                "executor_type": executor_type,
+                "inputs_template": inputs_template,
+                "mode": mode,
+                "max_parallel": max_parallel,
+                "continue_on_error": continue_on_error,
+                "iteration_count": iteration_count,
+                "wave": wave,
+                "depth": depth,
+                "paused_iteration_checkpoint": resumed_result.pause_checkpoint_data,
+            }
+            raise ExecutionPaused(
+                prompt=resumed_result.pause_prompt,
+                checkpoint_data=for_each_checkpoint,
+                execution=context,
+            )
+
         # Execute remaining iterations (sequential execution)
         for idx_offset, key in enumerate(remaining_keys):
             idx = current_idx + 1 + idx_offset

src/workflows_mcp/templates/agents/workflow-creator/layer1/summary.yaml

@@ -24,14 +24,20 @@ inputs:
     description: "(Optional) Number of validation attempts made"
     default: 1
 
+  output_dir:
+    type: str
+    description: "Output directory for workflow files"
+    default: "~/.workflows"
+    required: false
+
 blocks:
   - id: save_final_workflow
     type: CreateFile
-    description: "Save final workflow to desired location"
+    description: "Save final workflow to hierarchical location"
     inputs:
       create_parents: true
       overwrite: true
-      path: "~/.workflows/{{inputs.workflow_name}}.yaml"
+      path: "{{inputs.output_dir}}/{{inputs.workflow_name}}/main.yaml"
       content: "{{ read_file(inputs.workflow_path) }}"
 
   - id: generate_summary

src/workflows_mcp/templates/agents/workflow-creator/layer2/decompose.yaml

@@ -39,6 +39,12 @@ inputs:
     description: "Current recursion depth"
     default: 0
 
+  output_dir:
+    type: str
+    description: "Output directory for sub-workflow files"
+    default: "~/.workflows"
+    required: false
+
 blocks:
   - id: check_depth
     description: "Guard against excessive nesting"
@@ -121,6 +127,7 @@ blocks:
         recursion_depth: "{{inputs.current_depth + 1}}"
         max_recursion_depth: "{{inputs.max_depth}}"
         max_validation_attempts: 5
+        output_dir: "{{inputs.output_dir}}"
 
   - id: collect_results
     description: "Summarize generated sub-workflows"

src/workflows_mcp/templates/agents/workflow-creator/layer2/workflow.yaml

@@ -43,6 +43,18 @@ inputs:
     default: 1
     required: false
 
+  sub_workflows:
+    type: list
+    description: "(Optional) List of sub-workflows to compose (from analyze_complexity)"
+    default: []
+    required: false
+
+  has_sub_workflows:
+    type: bool
+    description: "(Optional) Whether sub-workflows were generated"
+    default: false
+    required: false
+
 blocks:
   - id: system_prompt
     description: "Log the current iteration"
@@ -90,6 +102,23 @@ blocks:
         ```
         Without profile or provider, the block WILL FAIL at runtime.
 
+        # Workflow Composition (using sub-workflows)
+        When sub-workflows are available, you MUST compose them using Workflow blocks:
+        {% raw %}
+        ```yaml
+        - id: run_sub_workflow
+          type: Workflow
+          inputs:
+            workflow: "sub-workflow-name"  # Exact name from available sub-workflows
+            inputs:
+              param1: "{{inputs.some_param}}"
+              param2: "{{blocks.previous_block.outputs.result}}"
+        ```
+        {% endraw %}
+        - Use Workflow blocks to call pre-generated sub-workflows
+        - Pass appropriate inputs from parent workflow inputs or block outputs
+        - Use sub-workflow outputs via {% raw %}{{blocks.run_sub_workflow.outputs.field}}{% endraw %}
+
         # Output Format
         JSON: {workflow: {name, description, inputs: [...], blocks: [...], outputs: [...]}, explanation, clarifications}
         Note: In this representation, inputs, blocks, and outputs are arrays (lists), not objects.
@@ -117,6 +146,40 @@ blocks:
         {{read_file(inputs.user_requests) | fromjson | prettyjson}}
         ```
 
+        {%- if inputs.has_sub_workflows and inputs.sub_workflows | length > 0 %}
+        ## IMPORTANT: Available Sub-Workflows for Composition
+        The following sub-workflows have been generated. You MUST compose them using Workflow blocks:
+
+        {% for sw in inputs.sub_workflows %}
+        ### `{{ sw.name }}`
+        **Purpose**: {{ sw.purpose }}
+        {% if sw.inputs and sw.inputs | length > 0 %}
+        **Inputs**:
+        {% for inp in sw.inputs %}
+        - `{{ inp.name }}` ({{ inp.type }}): {{ inp.description }}
+        {% endfor %}
+        {% endif %}
+        {% if sw.outputs and sw.outputs | length > 0 %}
+        **Outputs**:
+        {% for out in sw.outputs %}
+        - `{{ out.name }}` ({{ out.type }}): {{ out.description }}
+        {% endfor %}
+        {% endif %}
+
+        {% endfor %}
+        **Usage Example**:
+        {% raw %}
+        ```yaml
+        - id: call_sub_workflow
+          type: Workflow
+          inputs:
+            workflow: "sub-workflow-name"
+            inputs:
+              param: "{{inputs.some_param}}"
+        ```
+        {% endraw %}
+        {% endif %}
+
         {%- if inputs.index == 1 %}
         # Design New Workflow
         Create a workflow based on the user's requirements:
@@ -126,6 +189,9 @@ blocks:
         1. **Inputs**: All workflow input parameters
         2. **Blocks**: Compute/Processing steps (following DAG rules - no cycles)
         3. **Outputs**: Workflow outputs
+        {% if inputs.has_sub_workflows %}
+        4. **CRITICAL**: Use Workflow blocks to compose the available sub-workflows listed above
+        {% endif %}
 
         Generate the initial workflow design now.
         {% else %}
@@ -652,6 +718,8 @@ blocks:
         feedback: "{{blocks.request_approval.outputs.response}}"
         workspace: "{{inputs.workspace}}"
         index: "{{inputs.index + 1}}"
+        sub_workflows: "{{inputs.sub_workflows}}"
+        has_sub_workflows: "{{inputs.has_sub_workflows}}"
 
 outputs:
   diagram_path:

src/workflows_mcp/templates/agents/workflow-creator/workflow-creator.yaml

@@ -40,6 +40,12 @@ inputs:
     description: "Maximum depth for recursive sub-workflow generation"
     default: 2
 
+  output_dir:
+    type: str
+    description: "Output directory for workflow files. Workflows save to <output_dir>/<name>/main.yaml"
+    default: "~/.workflows"
+    required: false
+
 blocks:
   - id: bootstrap_context
     type: Workflow
@@ -89,6 +95,7 @@ blocks:
         workspace: "{{inputs.workspace}}/sub-workflows"
         current_depth: "{{inputs.recursion_depth}}"
         max_depth: "{{inputs.max_recursion_depth}}"
+        output_dir: "{{inputs.output_dir}}/{{blocks.generate_requirements.outputs.response.name}}"
 
   - id: generate_workflow
     description: "Generate main workflow (after complexity analysis and optional sub-workflow generation)"
@@ -105,6 +112,9 @@ blocks:
         executor_docs_path: "{{blocks.bootstrap_context.outputs.executor_docs_path}}"
         examples: "{{blocks.bootstrap_context.outputs.examples}}"
         workspace: "{{inputs.workspace}}/generate-workflow"
+        # Pass sub-workflow info for composition
+        sub_workflows: "{{blocks.analyze_complexity.outputs.sub_workflows | default([])}}"
+        has_sub_workflows: "{{blocks.generate_sub_workflows.succeeded | default(false)}}"
 
   - id: transform_design
     description: "Transform design JSON to valid workflow YAML format"
@@ -142,6 +152,7 @@ blocks:
         workspace: "{{inputs.workspace}}"
         workflows_mcp_path: "{{blocks.bootstrap_context.outputs.workspace}}"
         iterations: "{{blocks.recursive_validation.outputs.iterations}}"
+        output_dir: "{{inputs.output_dir}}"
 
 outputs:
   workflow_name: