[Feature Request]: Add visual flowchart output for workflow files

[salem221094]

Feature Request: Visual Flowchart for Lobster Workflows

Summary

When a Lobster workflow file (.lobster / YAML) is loaded or run, it would be extremely useful to render a visual flowchart of the workflow's step graph — showing steps, data flow, approval gates, and conditional branches — without requiring the user to mentally parse YAML.

---

Motivation / Problem

Lobster workflows can include multiple interconnected steps using run:, pipeline:, approval:, when:, and stdin: $step.stdout references. As workflows grow in complexity (branching when: conditions, multiple approval: gates, chained LLM steps), it becomes hard to audit, debug, or explain the flow at a glance. Currently there is no visual representation of the step graph — all understanding must come from reading raw YAML.

This is especially important in AI-agent contexts, where an agent (like OpenClaw) needs to understand a workflow's structure before deciding whether to run it.

---

Proposed Solution

Add a new lobster graph (or lobster visualize) command that:

1. Parses a .lobster / YAML workflow file.
2. Outputs a flowchart representing:
   • Each step as a node (labeled with id and step type: run, pipeline, approval)
   • Data flow edges from stdin: $step.stdout / stdin: $step.json references
   • Conditional edges from when: / condition: fields (dashed or labeled)
   • Approval gates rendered as a distinct diamond/gate node shape
3. Supports multiple output formats, at minimum:
   • --format mermaid → prints a Mermaid flowchart TD block (renders natively in GitHub Markdown, Notion, etc.)
   • --format dot → outputs Graphviz DOT syntax
   • --format ascii → plain-text fallback for terminals

Example command

lobster graph --file path/to/workflow.lobster --format mermaid

Example output (Mermaid)

flowchart TD
  fetch["🔧 fetch\nrun: weather --json"]
  confirm{"✅ confirm\napproval gate"}
  advice["🤖 advice\npipeline: llm.invoke"]

  fetch -->|stdin| confirm
  fetch -->|stdin| advice
  confirm -->|when: approved| advice

---

Why Mermaid First?

Mermaid renders natively inside GitHub issues, PRs, and wikis with no extra tooling. This means the output of lobster graph --format mermaid can be pasted directly into a GitHub comment or README and become an interactive diagram instantly — zero install required for consumers.

---

Acceptance Criteria

• lobster graph --file <path> command exists and parses valid workflow files
• Mermaid output correctly represents all step types (run, pipeline, approval)
• stdin: references produce directed edges between nodes
• when: / condition: fields produce labeled conditional edges
• Approval steps render with a visually distinct node shape
• Works with --args-json to resolve dynamic arg values where possible
• Documented in README under a new "Visualizing Workflows" section

---

Alternatives Considered

• Inline rendering in TUI: Could be added later as a UI layer, but a CLI-first approach is consistent with Lobster's local-first, no-new-auth-surface philosophy.
• Auto-generating on lobster run: Opt-in via a flag rather than default, to avoid noise in agent-driven pipelines.

---

Additional Context

This feature would directly support Lobster's stated goal of improving determinism and explainability for AI agent workflows. It would also make onboarding new contributors to complex workflow files significantly easier.