refactor: unify int/float types to num and fix composition bug

**Type System Unification:**
- Replace separate INT and FLOAT types with unified NUM type
- Update ValueType and InputType enums in schema.py
- Implement smart num parsing: returns int for whole numbers, float for decimals
- Migrate all 74 workflow files from type: int/float to type: num
- Update type coercion logic in executors_core.py
- Regenerate schema.json with new type definitions

**Bug Fix:**
- Fix composition-output-passing workflow bug
- Replace bash arithmetic $((...)) with Python for proper float handling
- Child calculator now correctly processes float operations
- Verified: 10 * 5 = 50, then 50 + 5 = 55 (was 50 before)

**Updates:**
- Update README.md and CLAUDE.md documentation
- Regenerate 68 test snapshots with correct type handling
- Add 4 new workflow output type test cases
- All 34/35 workflows passing (1 paused as expected)

**BREAKING CHANGE:**
- Workflow YAML files using `type: int` or `type: float` should migrate to `type: num`

Author: ibacalu

README.md

@@ -226,9 +226,33 @@ blocks:
       command: printf "Hello, {{inputs.name}}!"
 
 outputs:
-  greeting: "{{blocks.greet.outputs.stdout}}"
+  greeting:
+    value: "{{blocks.greet.outputs.stdout}}"
+    type: str
+    description: "The greeting message"
 ```
 
+### Workflow Outputs
+
+Workflow outputs support automatic type coercion, allowing you to declare the expected type and get properly typed values:
+
+```yaml
+outputs:
+  output_name:
+    value: "{{blocks.block_id.outputs.field}}"  # Variable expression
+    type: str                                     # Type declaration (optional)
+    description: "Human-readable description"    # Documentation (optional)
+```
+
+**Supported Types:**
+
+- **str** - Text values (default if type not specified)
+- **num** - Numeric values (integer or float - JSON doesn't distinguish)
+- **bool** - Boolean values (true/false)
+- **list** - List/array values
+- **dict** - Dictionary/object values
+- **json** - Parse JSON string into dict/list/str/num/bool/None
+
 ### Key Features
 
 **Variable Substitution:**

schema.json

@@ -25,8 +25,7 @@
             "type": {
               "enum": [
                 "str",
-                "int",
-                "float",
+                "num",
                 "bool",
                 "list",
                 "dict"
@@ -48,10 +47,42 @@
     },
     "outputs": {
       "type": "object",
-      "description": "Workflow output expressions",
+      "description": "Workflow output expressions with type coercion",
       "patternProperties": {
         ".*": {
-          "type": "string"
+          "additionalProperties": false,
+          "description": "Schema for workflow-level output with type coercion.\n\nDefines outputs that the workflow exposes to callers. Outputs are expressions\nthat reference block outputs, with optional type coercion.\n\nAttributes:\n    value: Expression (e.g., \"{{block.outputs.field}}\" or \"{{block.exit_code}}\")\n    type: Output type (str, int, float, bool, json, list, dict) - defaults to str\n    description: Optional human-readable output description\n\nType Coercion:\n    When type is specified, the resolved value is coerced to that type:\n    - str: Convert any value to string\n    - int: Parse string to int or validate existing int\n    - float: Parse string to float or validate existing float\n    - bool: Parse string (\"true\"/\"false\") or validate existing bool\n    - json: Parse JSON string to dict/list or validate existing JSON-compatible value\n    - list: Validate existing list\n    - dict: Validate existing dict\n\nExamples:\n    # Minimal (type defaults to str)\n    outputs:\n      message:\n        value: \"{{blocks.foo.outputs.msg}}\"\n\n    # With type coercion\n    outputs:\n      count:\n        value: \"{{blocks.foo.outputs.count}}\"\n        type: int\n        description: \"Number of items\"\n\n    # Logical expression (evaluates to bool)\n      success:\n        value: \"{{blocks.test.outputs.exit_code}} == 0\"\n        type: bool\n        description: \"Whether tests passed\"",
+          "properties": {
+            "value": {
+              "description": "Expression referencing block outputs",
+              "minLength": 1,
+              "title": "Value",
+              "type": "string"
+            },
+            "type": {
+              "$ref": "#/$defs/ValueType",
+              "default": "str",
+              "description": "Output type with automatic coercion (defaults to str)"
+            },
+            "description": {
+              "anyOf": [
+                {
+                  "type": "string"
+                },
+                {
+                  "type": "null"
+                }
+              ],
+              "default": null,
+              "description": "Human-readable description",
+              "title": "Description"
+            }
+          },
+          "required": [
+            "value"
+          ],
+          "title": "WorkflowOutputSchema",
+          "type": "object"
         }
       }
     },
@@ -840,7 +871,20 @@
       }
     }
   },
-  "definitions": {
+  "$defs": {
+    "ValueType": {
+      "description": "Unified Python type system for workflow values.\n\nSingle source of truth for all type declarations across:\n- Workflow inputs\n- Block outputs (file-based)\n- Workflow outputs\n- Output parsing logic\n\nThese match Python's built-in types for consistency with:\n- isinstance() checks in conditions: isinstance({{inputs.name}}, str)\n- Type annotations in executor models: Field(default=\"\", description=\"...\")\n- Variable resolution return types\n\nType mappings:\n- str: Text values (Python str)\n- num: Numeric values (int or float)\n- bool: Boolean values (Python bool)\n- list: List/array values (Python list)\n- dict: Dictionary/object values (Python dict)\n- json: Special - parse as JSON (returns dict/list/str/int/float/bool/None)",
+      "enum": [
+        "str",
+        "num",
+        "bool",
+        "list",
+        "dict",
+        "json"
+      ],
+      "title": "ValueType",
+      "type": "string"
+    },
     "ShellInput": {
       "additionalProperties": false,
       "description": "Input model for Shell executor.\n\nArchitecture (ADR-006):\n- Execute returns ShellOutput directly\n- Operation outcome determined by exit_code\n- Exceptions indicate execution failure",

src/workflows_mcp/engine/executor_base.py

@@ -23,7 +23,7 @@
 
 from .block import BlockInput, BlockOutput
 from .execution import Execution
-from .schema import InputType
+from .schema import InputType, WorkflowOutputSchema
 
 
 class ExecutorSecurityLevel(Enum):
@@ -254,11 +254,16 @@ def generate_workflow_schema(self) -> dict[str, Any]:
             with open("workflow-schema.json", "w") as f:
                 json.dump(schema, f, indent=2)
         """
-        # Collect all executor input schemas
+        # Collect all executor input schemas and shared type definitions
         definitions = {}
         block_types = []
         type_conditionals = []
 
+        # Extract WorkflowOutputSchema and merge its $defs to root level
+        # This ensures ValueType enum is accessible at the root for proper $ref resolution
+        output_schema = WorkflowOutputSchema.model_json_schema()
+        definitions.update(output_schema.pop("$defs", {}))
+
         for type_name, executor in self._executors.items():
             # Get the actual Pydantic schema from the executor
             input_schema = executor.get_input_schema()
@@ -377,16 +382,16 @@ def generate_workflow_schema(self) -> dict[str, Any]:
                 },
                 "outputs": {
                     "type": "object",
-                    "description": "Workflow output expressions",
-                    "patternProperties": {".*": {"type": "string"}},
+                    "description": "Workflow output expressions with type coercion",
+                    "patternProperties": {".*": output_schema},
                 },
                 "blocks": {
                     "type": "array",
                     "description": "Workflow execution blocks",
                     "items": base_block_schema,
                 },
             },
-            "definitions": definitions,
+            "$defs": definitions,
         }
 
     def discover_entry_points(self, group: str = "mcp_workflows.executors") -> int:

src/workflows_mcp/engine/executors_core.py

@@ -165,7 +165,7 @@ def parse_output_value(content: str, output_type: str) -> Any:
 
     Args:
         content: Raw file content
-        output_type: One of ValueType values: str, int, float, bool, json
+        output_type: One of ValueType values: str, num, bool, json
 
     Returns:
         Parsed value with correct Python type
@@ -177,16 +177,15 @@ def parse_output_value(content: str, output_type: str) -> Any:
 
     if output_type == "str":
         return str(content)  # Explicit cast for consistency
-    elif output_type == "int":
+    elif output_type == "num":
+        # Parse as number (int or float)
         try:
-            return int(content)
+            # Try float first (accepts both int and float strings)
+            value = float(content)
+            # Return int if it's a whole number, otherwise float
+            return int(value) if value.is_integer() else value
         except ValueError:
-            raise ValueError(f"Cannot parse as int: {content}")
-    elif output_type == "float":
-        try:
-            return float(content)
-        except ValueError:
-            raise ValueError(f"Cannot parse as float: {content}")
+            raise ValueError(f"Cannot parse as num: {content}")
     elif output_type == "bool":
         # Accept: true/false, 1/0, yes/no (case-insensitive)
         lower = content.lower()
@@ -208,6 +207,98 @@ def parse_output_value(content: str, output_type: str) -> Any:
         raise ValueError(f"Unknown output type: {output_type}")
 
 
+def coerce_value_type(value: Any, output_type: str) -> Any:
+    """
+    Coerce a value to the declared type (flexible version of parse_output_value).
+
+    Handles both string values that need parsing and already-typed values.
+    Used for workflow output type coercion where values may already be correctly typed
+    from nested workflows or block outputs.
+
+    Args:
+        value: Value to coerce (can be str, int, float, bool, dict, list, etc.)
+        output_type: One of ValueType values: str, num, bool, json, list, dict
+
+    Returns:
+        Value coerced to correct Python type
+
+    Raises:
+        ValueError: If value cannot be coerced to declared type
+
+    Examples:
+        # String values (parsed)
+        coerce_value_type("42", "num") -> 42
+        coerce_value_type("42.5", "num") -> 42.5
+        coerce_value_type("true", "bool") -> True
+        coerce_value_type('{"a":1}', "json") -> {"a": 1}
+
+        # Already-typed values (validated and passed through)
+        coerce_value_type(42, "num") -> 42
+        coerce_value_type(42.5, "num") -> 42.5
+        coerce_value_type(True, "bool") -> True
+        coerce_value_type({"a": 1}, "json") -> {"a": 1}
+
+        # Type conversion when needed
+        coerce_value_type(42, "str") -> "42"
+        coerce_value_type(42.5, "str") -> "42.5"
+    """
+    # Handle string values using existing parser
+    if isinstance(value, str):
+        # Use existing parse_output_value for strings
+        return parse_output_value(value, output_type)
+
+    # Handle already-typed values with validation and conversion
+    if output_type == "str":
+        # Convert any value to string
+        return str(value)
+
+    elif output_type == "num":
+        # Accept both int and float (exclude bool since it's subclass of int)
+        if isinstance(value, (int, float)) and not isinstance(value, bool):
+            return value
+        # Try to convert
+        try:
+            result = float(value)
+            # Return int if whole number, otherwise float
+            return int(result) if result.is_integer() else result
+        except (ValueError, TypeError):
+            raise ValueError(f"Cannot coerce {type(value).__name__} to num: {value}")
+
+    elif output_type == "bool":
+        # If already bool, return as-is
+        if isinstance(value, bool):
+            return value
+        # Try to convert using standard Python truthiness
+        # But be strict - only accept actual booleans or 1/0 integers
+        if isinstance(value, int) and value in [0, 1]:
+            return bool(value)
+        raise ValueError(
+            f"Cannot coerce {type(value).__name__} to bool: {value}. "
+            f"Only bool values or integers 0/1 are accepted."
+        )
+
+    elif output_type == "json":
+        # Accept dict, list, or JSON-compatible primitives
+        if isinstance(value, (dict, list, str, int, float, bool, type(None))):
+            return value
+        raise ValueError(f"Cannot coerce {type(value).__name__} to json: {value}")
+
+    elif output_type == "list":
+        # If already list, return as-is
+        if isinstance(value, list):
+            return value
+        raise ValueError(f"Cannot coerce {type(value).__name__} to list: {value}")
+
+    elif output_type == "dict":
+        # If already dict, return as-is
+        if isinstance(value, dict):
+            return value
+        raise ValueError(f"Cannot coerce {type(value).__name__} to dict: {value}")
+
+    else:
+        raise ValueError(f"Unknown output type: {output_type}")
+
+
 class ShellExecutor(BlockExecutor):
     """
     Shell command executor.