flowsh-cli 0.8.2__tar.gz → 0.9.0__tar.gz

{flowsh_cli-0.8.2 → flowsh_cli-0.9.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: flowsh-cli
-Version: 0.8.2
+Version: 0.9.0
 Summary: Generate Bash harness scripts from workflow YAML files.
 License-Expression: MIT
 Classifier: Programming Language :: Python :: 3.11
@@ -16,7 +16,7 @@ Description-Content-Type: text/markdown
 
 # flowsh-cli
 
-`flowsh-cli` turns workflow YAML into executable Bash harnesses for OpenCode.
+`flowsh-cli` turns workflow YAML into executable shell scripts.
 
 Use it when you want a small, reproducible way to encode a workflow once and rerun it locally or in CI.
 
@@ -28,7 +28,7 @@ uvx flowsh-cli path/to/workflows.yml
 
 That reads the workflow YAML at the path you provide and writes harness scripts to the current working directory.
 
-In this repository, the example workflow file lives at `.made/workflows.yml`.
+In this repository, the example workflow file lives at `workflows.yml`.
 
 Useful flags:
 
@@ -68,18 +68,23 @@ workflows:
         expandPrompt: true
         prompt: |
           Review issue ${ISSUE_NUMBER} and summarize the repository state.
-      - type: parallel
-        steps:
-          - type: bash
-            run: echo "worker A"
-          - type: bash
-            run: echo "worker B"
-      - type: for
-        in: ITEMS
-        item: ITEM
-        steps:
-          - type: bash
-            run: echo "$ITEM"
+       - type: parallel
+         steps:
+           - type: bash
+             run: echo "worker A"
+           - type: bash
+             run: echo "worker B"
+       - type: for
+         in: ITEMS
+         item: ITEM
+         steps:
+           - type: bash
+             run: echo "$ITEM"
+       - type: while
+         condition: '[ -n "$(ls doc/plan/steps/planned/ 2>/dev/null)" ]'
+         steps:
+           - type: bash
+             run: echo "keep looping until the queue is empty"
 ```
 
 Harness paths are derived from workflow ids. `wf_example` becomes `example.sh` in the current working directory.
@@ -90,8 +95,9 @@ Harness paths are derived from workflow ids. `wf_example` becomes `example.sh` i
 |---|---|---|
 | `vars` | Execute shell commands and export their stdout into shell variables | Variable names must be uppercase shell identifiers. |
 | `bash` | Run shell commands | Runs with `bash -euo pipefail`. |
-| `agent` | Call OpenCode | Supports `agent`, `model`, `command`, `expandPrompt`, and `dangerouslySkipPermissions`. |
+| `agent` | Call the agent runtime | Supports `agent`, `model`, `command`, `capture`, `expandPrompt`, and `dangerouslySkipPermissions`. |
 | `for` | Iterate over newline-delimited values from a previous `vars` step | Flat iteration only; nested `for` steps are not supported. |
+| `while` | Re-evaluate a Bash condition before each iteration | Use for dynamic queues or other stateful loops that must keep discovering new work. |
 | `parallel` | Run child steps concurrently | Children run as separate branches and the parent waits for all of them. |
 
 ## Agent Behavior
@@ -100,7 +106,9 @@ Harness paths are derived from workflow ids. `wf_example` becomes `example.sh` i
 
 `expandPrompt: true` does plain text replacement only. It does not evaluate shell expressions like `$(...)`, backticks, or globs.
 
-Set `dangerouslySkipPermissions: true` only when you want the generated harness to pass `--dangerously-skip-permissions` to OpenCode. The YAML alias `dangerously-skip-permissions` is also accepted.
+Set `capture: VARIABLE_NAME` on an `agent` step when you want the full agent output stored in a shell variable for later `vars` or `bash` steps.
+
+Set `dangerouslySkipPermissions: true` only when you want the generated harness to pass `--dangerously-skip-permissions` to the agent runtime. The YAML alias `dangerously-skip-permissions` is also accepted.
 
 ## Validation And Safety
 

{flowsh_cli-0.8.2 → flowsh_cli-0.9.0}/README.md

@@ -1,6 +1,6 @@
 # flowsh-cli
 
-`flowsh-cli` turns workflow YAML into executable Bash harnesses for OpenCode.
+`flowsh-cli` turns workflow YAML into executable shell scripts.
 
 Use it when you want a small, reproducible way to encode a workflow once and rerun it locally or in CI.
 
@@ -12,7 +12,7 @@ uvx flowsh-cli path/to/workflows.yml
 
 That reads the workflow YAML at the path you provide and writes harness scripts to the current working directory.
 
-In this repository, the example workflow file lives at `.made/workflows.yml`.
+In this repository, the example workflow file lives at `workflows.yml`.
 
 Useful flags:
 
@@ -52,18 +52,23 @@ workflows:
         expandPrompt: true
         prompt: |
           Review issue ${ISSUE_NUMBER} and summarize the repository state.
-      - type: parallel
-        steps:
-          - type: bash
-            run: echo "worker A"
-          - type: bash
-            run: echo "worker B"
-      - type: for
-        in: ITEMS
-        item: ITEM
-        steps:
-          - type: bash
-            run: echo "$ITEM"
+       - type: parallel
+         steps:
+           - type: bash
+             run: echo "worker A"
+           - type: bash
+             run: echo "worker B"
+       - type: for
+         in: ITEMS
+         item: ITEM
+         steps:
+           - type: bash
+             run: echo "$ITEM"
+       - type: while
+         condition: '[ -n "$(ls doc/plan/steps/planned/ 2>/dev/null)" ]'
+         steps:
+           - type: bash
+             run: echo "keep looping until the queue is empty"
 ```
 
 Harness paths are derived from workflow ids. `wf_example` becomes `example.sh` in the current working directory.
@@ -74,8 +79,9 @@ Harness paths are derived from workflow ids. `wf_example` becomes `example.sh` i
 |---|---|---|
 | `vars` | Execute shell commands and export their stdout into shell variables | Variable names must be uppercase shell identifiers. |
 | `bash` | Run shell commands | Runs with `bash -euo pipefail`. |
-| `agent` | Call OpenCode | Supports `agent`, `model`, `command`, `expandPrompt`, and `dangerouslySkipPermissions`. |
+| `agent` | Call the agent runtime | Supports `agent`, `model`, `command`, `capture`, `expandPrompt`, and `dangerouslySkipPermissions`. |
 | `for` | Iterate over newline-delimited values from a previous `vars` step | Flat iteration only; nested `for` steps are not supported. |
+| `while` | Re-evaluate a Bash condition before each iteration | Use for dynamic queues or other stateful loops that must keep discovering new work. |
 | `parallel` | Run child steps concurrently | Children run as separate branches and the parent waits for all of them. |
 
 ## Agent Behavior
@@ -84,7 +90,9 @@ Harness paths are derived from workflow ids. `wf_example` becomes `example.sh` i
 
 `expandPrompt: true` does plain text replacement only. It does not evaluate shell expressions like `$(...)`, backticks, or globs.
 
-Set `dangerouslySkipPermissions: true` only when you want the generated harness to pass `--dangerously-skip-permissions` to OpenCode. The YAML alias `dangerously-skip-permissions` is also accepted.
+Set `capture: VARIABLE_NAME` on an `agent` step when you want the full agent output stored in a shell variable for later `vars` or `bash` steps.
+
+Set `dangerouslySkipPermissions: true` only when you want the generated harness to pass `--dangerously-skip-permissions` to the agent runtime. The YAML alias `dangerously-skip-permissions` is also accepted.
 
 ## Validation And Safety
 

{flowsh_cli-0.8.2 → flowsh_cli-0.9.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "uv_build"
 
 [project]
 name = "flowsh-cli"
-version = "0.8.2"
+version = "0.9.0"
 description = "Generate Bash harness scripts from workflow YAML files."
 readme = "README.md"
 requires-python = ">=3.11"
@@ -29,7 +29,7 @@ flowsh-cli = "flowsh_cli.cli:main"
 
 [dependency-groups]
 dev = [
-  "pytest>=8,<9",
+  "pytest>=9.0.3,<10",
   "ruff>=0.14,<0.15",
 ]
 
@@ -45,3 +45,4 @@ select = ["E", "F", "I", "UP", "B", "SIM"]
 
 [tool.ruff.lint.per-file-ignores]
 "tests/test_workflow_to_harness.py" = ["E501"]
+"src/flowsh_cli/skill.py" = ["E501"]

{flowsh_cli-0.8.2 → flowsh_cli-0.9.0}/src/flowsh_cli/__init__.py

@@ -1,9 +1,9 @@
-"""flowsh-cli: generate OpenCode Bash harness scripts from workflow YAML."""
+"""flowsh-cli: generate shell scripts from workflow YAML files."""
 
 from flowsh_cli.models import Workflow, WorkflowParseError, parse_workflows
 from flowsh_cli.render import harness_path, render_harness
 
-__version__ = "0.8.2"
+__version__ = "0.9.0"
 
 __all__ = [
     "Workflow",

{flowsh_cli-0.8.2 → flowsh_cli-0.9.0}/src/flowsh_cli/cli.py

@@ -14,11 +14,15 @@ from flowsh_cli import __version__
 from flowsh_cli.examples import example_yaml, examples_index
 from flowsh_cli.models import Workflow, WorkflowParseError, parse_workflows, workflow_schema_yaml
 from flowsh_cli.render import harness_path, render_harness
+from flowsh_cli.skill import skill_text
+
+DEFAULT_WORKFLOW_YAML = Path("workflows.yml")
+WORKFLOW_YAML_ARGUMENT = typer.Argument(DEFAULT_WORKFLOW_YAML, help="Path to workflow.yml")
 
 app = typer.Typer(
     add_completion=False,
     context_settings={"terminal_width": 120, "max_content_width": 120},
-    help="Generate reproducible OpenCode Bash harness scripts from MADE workflow YAML.",
+    help="Generate reproducible shell scripts from workflow YAML files.",
     pretty_exceptions_enable=False,
 )
 
@@ -32,9 +36,9 @@ def main(argv: Sequence[str] | None = None) -> int:
     return 0
 
 
-@app.command(help="Generate reproducible OpenCode Bash harness scripts from MADE workflow YAML.")
+@app.command(help="Generate reproducible shell scripts from workflow YAML files.")
 def generate(
-    workflow_yaml: Annotated[Path, typer.Argument(help="Path to workflow YAML")],
+    workflow_yaml: Path = WORKFLOW_YAML_ARGUMENT,
     workflow: Annotated[
         str | None,
         typer.Option(
@@ -90,6 +94,15 @@ def generate(
             is_eager=True,
         ),
     ] = None,
+    skill: Annotated[
+        bool,
+        typer.Option(
+            "--skill",
+            callback=lambda value: print_skill(value),
+            help="Show the flowsh-cli skill description and exit.",
+            is_eager=True,
+        ),
+    ] = False,
     output: Annotated[
         Path | None,
         typer.Option(
@@ -99,12 +112,13 @@ def generate(
         ),
     ] = None,
 ) -> None:
-    """Generate Bash harnesses from workflow YAML."""
+    """Generate shell scripts from workflow YAML."""
 
     _ = version
     _ = schema
     _ = examples
     _ = example
+    _ = skill
 
     try:
         workflows = parse_workflows(workflow_yaml)
@@ -173,6 +187,14 @@ def print_example(value: str | None) -> None:
     raise typer.Exit
 
 
+def print_skill(value: bool) -> None:
+    if not value:
+        return
+
+    print(skill_text(), end="")
+    raise typer.Exit
+
+
 def write_harnesses(
     workflows: list[Workflow], *, dry_run: bool, force: bool, output_path: Path | None = None
 ) -> None:

{flowsh_cli-0.8.2 → flowsh_cli-0.9.0}/src/flowsh_cli/models.py

@@ -94,6 +94,10 @@ class AgentStep(BaseStep):
     agent: str | None = None
     model: str | None = None
     command: str | None = None
+    capture: str | None = Field(
+        default=None,
+        description="Name of a shell variable that receives the full agent output for later steps.",
+    )
     dangerouslySkipPermissions: bool = Field(
         default=False,
         validation_alias=AliasChoices(
@@ -112,6 +116,16 @@ class AgentStep(BaseStep):
             "are replaced. All other shell syntax in the prompt is safe to use."
         ),
     )
+    expandFields: bool = Field(
+        default=False,
+        description=(
+            "When true, substitutes ${VAR} and $VAR tokens from vars steps into the model, "
+            "agent, and command fields at runtime, using the same safe plain-text replacement "
+            "as expandPrompt. Also implies prompt expansion (equivalent to expandPrompt: true) "
+            "so that expandFields: true alone expands model, agent, command, and prompt. "
+            "Setting both expandPrompt and expandFields is allowed; both simply apply."
+        ),
+    )
 
     @model_validator(mode="before")
     @classmethod
@@ -138,8 +152,15 @@ class AgentStep(BaseStep):
     @field_validator("agent")
     @classmethod
     def validate_agent(cls, value: str | None) -> str | None:
-        if value is not None and not re.fullmatch(r"[A-Za-z0-9_-]+", value):
-            raise ValueError("must match ^[A-Za-z0-9_-]+$")
+        if value is not None and not re.fullmatch(r"[A-Za-z0-9_${}-]+", value):
+            raise ValueError("must match ^[A-Za-z0-9_${}-]+$")
+        return value
+
+    @field_validator("capture")
+    @classmethod
+    def validate_capture(cls, value: str | None) -> str | None:
+        if value is not None and not re.fullmatch(r"[A-Z_][A-Z0-9_]*", value):
+            raise ValueError("must match ^[A-Z_][A-Z0-9_]*$")
         return value
 
 
@@ -196,18 +217,42 @@ class ForStep(BaseStep):
         return value
 
 
+class WhileStep(BaseStep):
+    type: Literal["while"]
+    condition: str
+    steps: list[Step] = Field(min_length=1)
+
+    @field_validator("condition")
+    @classmethod
+    def validate_condition(cls, value: str) -> str:
+        if value.strip() == "":
+            raise ValueError("must not be empty")
+        if has_unsafe_control_characters(value):
+            raise ValueError("must not contain unsafe control characters")
+        return value
+
+    @field_validator("steps")
+    @classmethod
+    def reject_nested_while_steps(cls, value: list[Step]) -> list[Step]:
+        for step in value:
+            if isinstance(step, WhileStep):
+                raise ValueError("nested while steps are not supported")
+        return value
+
+
 class ParallelStep(BaseStep):
     type: Literal["parallel"]
     steps: list[Step] = Field(min_length=1)
 
 
 Step = Annotated[
-    VarsStep | BashStep | AgentStep | ForStep | ParallelStep,
+    VarsStep | BashStep | AgentStep | ForStep | WhileStep | ParallelStep,
     Field(discriminator="type"),
 ]
 
 
 ForStep.model_rebuild()
+WhileStep.model_rebuild()
 ParallelStep.model_rebuild()
 
 

{flowsh_cli-0.8.2 → flowsh_cli-0.9.0}/src/flowsh_cli/render.py

@@ -10,6 +10,7 @@ from flowsh_cli.models import (
     ParallelStep,
     Step,
     VarsStep,
+    WhileStep,
     Workflow,
     WorkflowParam,
 )
@@ -121,19 +122,26 @@ def render_harness(workflow: Workflow) -> str:
         "catch() {",
         '  local step_name="$1"',
         '  local exit_code="$2"',
-        '  log ERROR "Step failed: ${step_name} (exit=${exit_code})"',
+        '  local step_type="${3:-}"',
+        '  local hint=""',
+        '  if [[ "$step_type" == "vars" && "$exit_code" == "127" ]]; then',
+        '    hint=" — vars values are shell commands, not literal strings;'
+        ' check workflow definition"',
+        "  fi",
+        '  log ERROR "Step failed: ${step_name} [${step_type}] (exit=${exit_code})${hint}"',
         "}",
         "",
         section("run_step() - dry-run and failure handling; streams output via tee"),
         "run_step() {",
         '  local step_name="$1"',
+        '  local step_type="${2:-}"',
         "",
         '  if [[ "$DRY_RUN" == true ]]; then',
-        '    log INFO "[DRY-RUN] would run: ${step_name}"',
+        '    log INFO "[DRY-RUN] would run: ${step_name} [${step_type}]"',
         "    return 0",
         "  fi",
         "",
-        '  log INFO "Running step: ${step_name}"',
+        '  log INFO "Running step: ${step_name} [${step_type}]"',
         "",
         "  set +e",
         '  if ( : >> "$LOG_FILE" ) 2>/dev/null; then',
@@ -146,7 +154,7 @@ def render_harness(workflow: Workflow) -> str:
         "  set -e",
         "",
         "  if [[ $status -ne 0 ]]; then",
-        '    catch "$step_name" "$status"',
+        '    catch "$step_name" "$status" "$step_type"',
         "  fi",
         '  return "$status"',
         "}",
@@ -154,13 +162,14 @@ def render_harness(workflow: Workflow) -> str:
         section("run_stateful_step() - dry-run and failure handling without subshells"),
         "run_stateful_step() {",
         '  local step_name="$1"',
+        '  local step_type="${2:-}"',
         "",
         '  if [[ "$DRY_RUN" == true ]]; then',
-        '    log INFO "[DRY-RUN] would run: ${step_name}"',
+        '    log INFO "[DRY-RUN] would run: ${step_name} [${step_type}]"',
         "    return 0",
         "  fi",
         "",
-        '  log INFO "Running step: ${step_name}"',
+        '  log INFO "Running step: ${step_name} [${step_type}]"',
         "",
         "  set +e",
         '  "$step_name"',
@@ -168,18 +177,19 @@ def render_harness(workflow: Workflow) -> str:
         "  set -e",
         "",
         "  if [[ $status -ne 0 ]]; then",
-        '    catch "$step_name" "$status"',
+        '    catch "$step_name" "$status" "$step_type"',
         "  fi",
         '  return "$status"',
         "}",
         "",
-        section("run_agent() - prompt handling and OpenCode CLI invocation"),
+        section("run_agent() - prompt handling and CLI invocation"),
         "run_agent() {",
         '  local prompt="$1"',
         '  local agent="${2:-}"',
         '  local model="${3:-}"',
         '  local command="${4:-}"',
-        '  local dangerously_skip_permissions="${5:-false}"',
+        '  local capture="${5:-}"',
+        '  local dangerously_skip_permissions="${6:-false}"',
         "",
         "  local cmd=(opencode run --format json)",
         '  if [[ -n "$agent" ]]; then',
@@ -205,7 +215,17 @@ def render_harness(workflow: Workflow) -> str:
         "    return 127",
         "  fi",
         "",
-        '  "${cmd[@]}" -- "$prompt"',
+        '  if [[ -n "$capture" ]]; then',
+        "    local output",
+        "    local status=0",
+        '    output="$("${cmd[@]}" -- "$prompt")"',
+        "    status=$?",
+        "    printf '%s\\n' \"$output\"",
+        '    printf -v "$capture" \'%s\' "$output"',
+        '    return "$status"',
+        "  else",
+        '    "${cmd[@]}" -- "$prompt"',
+        "  fi",
         "}",
         "",
         section(f"Starting workflow: {workflow.name}"),
@@ -248,9 +268,36 @@ def render_step(index: int, step: Step, used_function_names: set[str] | None = N
         body_lines = [
             f"  while IFS= read -r {step.item}; do",
             f"    export {step.item}",
-            *[f"    run_step {fn}" for fn in inner_fns],
+            *[
+                f"    run_step {fn} {inner_step.type}"
+                for fn, inner_step in zip(inner_fns, step.steps, strict=True)
+            ],
             f'  done <<< "${{{step.in_}}}"',
         ]
+    elif isinstance(step, WhileStep):
+        child_fns: list[str] = []
+        for i, child in enumerate(step.steps, start=1):
+            child_title = child.name or default_step_title(i, child)
+            child_fn = step_function_name(i, child.name, used_function_names)
+            child_fns.append(child_fn)
+            prefix_lines.append(section(f"While child {i} ({child.type}): {child_title}"))
+            prefix_lines.append(f"{child_fn}() {{")
+            prefix_lines.extend(_render_step_body(child, child_title))
+            prefix_lines.append("}")
+            prefix_lines.append("")
+
+        body_lines = []
+        if step.when is not None:
+            body_lines.append(f"  if ! ({step.when}); then")
+            body_lines.append(f"    log INFO {bash_quote(f'Step skipped (when): {title}')}")
+            body_lines.append("    return 0")
+            body_lines.append("  fi")
+            body_lines.append("")
+
+        body_lines.append(f"  while ({step.condition}); do")
+        for child_fn in child_fns:
+            body_lines.append(f"    run_step {child_fn} || return $?")
+        body_lines.append("  done")
     elif isinstance(step, ParallelStep):
         child_fns: list[str] = []
         for i, child in enumerate(step.steps, start=1):
@@ -273,7 +320,7 @@ def render_step(index: int, step: Step, used_function_names: set[str] | None = N
     else:
         body_lines = _render_step_body(step, title)
 
-    runner = "run_stateful_step" if isinstance(step, (VarsStep, ForStep)) else "run_step"
+    runner = "run_stateful_step" if isinstance(step, (VarsStep, ForStep, WhileStep)) else "run_step"
     outer_lines = [
         section(f"Step {index} ({step.type}): {title}"),
         f"{function_name}() {{",
@@ -283,13 +330,32 @@ def render_step(index: int, step: Step, used_function_names: set[str] | None = N
     outer_lines.extend(
         [
             "}",
-            f"{runner} {function_name}",
+            f"{runner} {function_name} {step.type}",
             "",
         ]
     )
     return prefix_lines + outer_lines
 
 
+def _find_var_tokens(text: str) -> list[str]:
+    """Return unique ${VAR}/$VAR tokens (matching [A-Z_][A-Z0-9_]*) in order of first appearance."""
+    braced = re.findall(r"\$\{([A-Z_][A-Z0-9_]*)\}", text)
+    bare = re.findall(r"\$([A-Z_][A-Z0-9_]*)(?!\w)", text)
+    seen: dict[str, None] = {}
+    for var in braced + bare:
+        seen[var] = None
+    return list(seen)
+
+
+def _expand_var_lines(local_name: str, tokens: list[str]) -> list[str]:
+    """Return bash lines that expand ${VAR}/$VAR literal tokens in `local_name` at runtime."""
+    lines: list[str] = []
+    for var in tokens:
+        lines.append(f'  _p=\'${{{var}}}\'; {local_name}="${{{local_name}//"$_p"/"${var}"}}"')
+        lines.append(f'  _p=\'${var}\'; {local_name}="${{{local_name}//"$_p"/"${var}"}}"')
+    return lines
+
+
 def _render_step_body(step: Step, title: str) -> list[str]:
     """Return indented body lines for a step function (no wrapper, no run_step call)."""
     lines: list[str] = []
@@ -338,23 +404,24 @@ def _render_step_body(step: Step, title: str) -> list[str]:
                 "  )",
             ]
         )
-        if step.expandPrompt:
+        if step.expandPrompt or step.expandFields:
             _prompt_no_code = re.sub(r"```.*?```", "", step.prompt, flags=re.DOTALL)
-            braced = re.findall(r"\$\{([A-Z_][A-Z0-9_]*)\}", _prompt_no_code)
-            bare = re.findall(r"\$([A-Z_][A-Z0-9_]*)(?!\w)", _prompt_no_code)
-            seen: dict[str, None] = {}
-            for var in braced + bare:
-                seen[var] = None
-            for var in seen:
-                lines.append(f'  _p=\'${{{var}}}\'; prompt="${{prompt//"$_p"/"${var}"}}"')
-                lines.append(f'  _p=\'${var}\'; prompt="${{prompt//"$_p"/"${var}"}}"')
+            lines.extend(_expand_var_lines("prompt", _find_var_tokens(_prompt_no_code)))
         lines.append(f"  local agent={bash_quote(step.agent or '')}")
+        if step.expandFields and step.agent:
+            lines.extend(_expand_var_lines("agent", _find_var_tokens(step.agent)))
         lines.append(f"  local model={bash_quote(step.model or '')}")
+        if step.expandFields and step.model:
+            lines.extend(_expand_var_lines("model", _find_var_tokens(step.model)))
         lines.append(f"  local command={bash_quote(step.command or '')}")
+        if step.expandFields and step.command:
+            lines.extend(_expand_var_lines("command", _find_var_tokens(step.command)))
+        lines.append(f"  local capture={bash_quote(step.capture or '')}")
         dangerous_skip_permissions = "true" if step.dangerouslySkipPermissions else "false"
         lines.append(f"  local dangerously_skip_permissions={dangerous_skip_permissions}")
         lines.append(
-            '  run_agent "$prompt" "$agent" "$model" "$command" "$dangerously_skip_permissions"'
+            '  run_agent "$prompt" "$agent" "$model" '
+            '"$command" "$capture" "$dangerously_skip_permissions"'
         )
     elif isinstance(step, ForStep):
         raise AssertionError("nested for steps are not supported")
@@ -393,6 +460,8 @@ def default_step_title(index: int, step: Step) -> str:
         return truncate_one_line(step.prompt)
     if isinstance(step, ForStep):
         return f"for {step.item} in {step.in_}"
+    if isinstance(step, WhileStep):
+        return f"while {truncate_one_line(step.condition)}"
     if isinstance(step, ParallelStep):
         return f"parallel ({len(step.steps)} steps)"
     return f"step {index}"

flowsh_cli-0.9.0/src/flowsh_cli/skill.py

@@ -0,0 +1,244 @@
+from __future__ import annotations
+
+SKILL_MARKDOWN = """\
+---
+name: flowsh-cli
+description: Generate executable shell harness scripts from workflow definitions. Use when creating, modifying, validating, reviewing, troubleshooting, or generating workflow-to-shell automation, especially for orchestrating bash and agent calls.
+---
+
+# Workflow-to-Shell Generation with flowsh-cli
+
+Use this skill whenever working with workflow definitions that produce executable Bash or shell scripts.
+
+## Purpose
+
+flowsh-cli converts workflow definitions into executable shell harness scripts.
+
+Workflow definitions are the source of truth.
+
+Generated shell scripts are build artifacts derived from those workflow definitions.
+
+The CLI parses, validates, and generates in a single operation. Validation is therefore an essential part of workflow generation.
+
+A workflow is considered correct when:
+
+* It conforms to the current schema.
+* Validation succeeds.
+* Generated shell output matches the intended behavior.
+
+---
+
+# Mandatory Operating Procedure
+
+## Rule 1: Always Consult the Current Schema First
+
+Before creating, modifying, reviewing, troubleshooting, or generating workflows:
+
+```bash
+uvx flowsh-cli --schema
+```
+
+The schema is the authoritative specification.
+
+Do not rely on:
+
+* Memory
+* Existing workflow files
+* Previous examples
+* Assumptions about supported fields
+
+If a workflow conflicts with the schema, the schema is authoritative.
+
+---
+
+## Rule 2: Validate Through Generation
+
+flowsh-cli validates workflows as part of generation.
+
+Use:
+
+```bash
+uvx flowsh-cli [workflow-name].yml
+```
+
+Validation failures must be resolved before reasoning about generated shell output.
+
+Do not assume a workflow is valid simply because it appears similar to previous examples.
+
+---
+
+## Rule 3: Always Verify After Changes
+
+After modifying a workflow:
+
+1. Retrieve the current schema.
+2. Run a dry-run generation.
+3. Review any validation errors or warnings.
+4. Review the generated output.
+5. Confirm generated shell behavior matches intent.
+
+Example:
+
+```bash
+uvx flowsh-cli [workflow-name].yml --dry-run
+```
+
+A workflow modification is not complete until a successful dry-run has been reviewed.
+
+---
+
+## Rule 4: Make Minimal Changes
+
+When modifying workflows:
+
+* Prefer the smallest possible change.
+* Avoid unrelated refactoring.
+* Preserve existing behavior unless explicitly requested.
+* Keep workflow structure stable.
+
+---
+
+# Workflow Review Priorities
+
+When reviewing workflows:
+
+1. Schema compliance.
+2. Successful validation.
+3. Workflow correctness.
+4. Generated shell correctness.
+5. Shell safety.
+6. Maintainability.
+
+Generated shell behavior should only be reviewed after validation succeeds.
+
+---
+
+# Common Commands
+
+Display help:
+
+```bash
+uvx flowsh-cli --help
+```
+
+Display the current schema:
+
+```bash
+uvx flowsh-cli --schema
+```
+
+Generate all workflows:
+
+```bash
+uvx flowsh-cli [workflow-name].yml
+```
+
+Generate a specific workflow:
+
+```bash
+uvx flowsh-cli [workflow-name].yml --workflow wf_example
+```
+
+Preview generation without writing files:
+
+```bash
+uvx flowsh-cli [workflow-name].yml --dry-run
+```
+
+Overwrite existing generated files:
+
+```bash
+uvx flowsh-cli [workflow-name].yml --force
+```
+
+---
+
+# Folder Structure & File Management
+
+By convention, organize workflow files and generated harness scripts under a `.harness/` folder:
+
+```
+project/
+└── .harness/
+    ├── [workflow-name].yml        # Workflow file
+    └── [harness-name].sh          # Generated harness script
+```
+
+**Convention:**
+- Store workflow definitions under `[workflow-name].yml` files
+- Generated harness scripts are produced in `.harness/` directory with names matching `[harness-name].sh`
+- Generated artifacts are build products—regenerate them as needed from source workflows
+- Use `.gitignore` to exclude generated `.sh` files if desired, or commit them for reproducibility
+
+**Generation command:**
+
+```bash
+uvx flowsh-cli .harness/[workflow-name].yml
+```
+
+This generates harnesses in `.harness/` alongside the source workflow definitions.
+
+---
+
+# Example Workflow
+
+Always verify against the current schema before creating production workflows.
+
+```yaml
+workflows:
+  - id: wf_example
+    name: Example Workflow
+
+    steps:
+      - type: vars
+        values:
+          TODAY: date -u +%F
+
+      - type: bash
+        run: |
+          echo "$TODAY"
+
+      - type: agent
+        prompt: |
+          Summarize the output.
+```
+
+---
+
+# Troubleshooting Procedure
+
+If generation fails:
+
+1. Retrieve the latest schema.
+2. Review validation errors.
+3. Correct the workflow definition.
+4. Run a dry-run.
+5. Review generated output.
+6. Apply the smallest possible fix.
+7. Repeat until validation and generation succeed.
+
+---
+
+# Expected Behavior
+
+Always:
+
+* Consult the latest schema first.
+* Treat the schema as authoritative.
+* Use flowsh-cli validation before evaluating generated output.
+* Run a dry-run after workflow modifications.
+* Review generated shell behavior before declaring success.
+* Prefer minimal changes.
+
+Never:
+
+* Assume schema details from memory.
+* Skip schema inspection.
+* Ignore validation errors.
+* Skip dry-run verification after changes.
+* Declare success without reviewing generated output.
+"""
+
+
+def skill_text() -> str:
+    return SKILL_MARKDOWN