[Feedback] Signal-based transitions concept is excellent — some gaps for first-time users

[felizkuo]

Hi Marcus,

I discovered Leeway through GitHub and want to share my experience as a potential early adopter. The signal-based workflow concept is genuinely innovative — it bridges the gap between rigid automation and unpredictable LLM agents better than most frameworks I've seen.

What works well

1. Signal transitions are the killer feature. The idea that an AI can output a structured signal (dig_deeper / ready / needs_human_review) that deterministically drives workflow branching is exactly what's missing in most agent frameworks.

2. YAML workflow definition is intuitive. After reading the code-health example, I immediately understood how to write my own workflow. The node/edge model is clean.

3. HITL with requires_approval — smart safety guard for enterprise use cases.

Where I struggled

1. No --version flag. After uv tool install, I had no easy way to track which version I'm running.

2. CLI doesn't expose workflows directly. For Cron/automation use cases, being able to invoke leeway --workflow <name> from CLI would be very valuable.

3. Signal reference documentation is missing. Are signals free-form strings or do they need pre-declaration?

4. --print mode crashes with asyncio event loop error in some environments.

Questions

1. Release roadmap? Rough timeline for v0.1.0 or v1.0.0?
2. Signal validation? Schema-based or purely convention?
3. Python API planned?

Summary

Core concept is solid. The framework needs: more CLI commands, signal documentation, and a stable release tag before production adoption.

— Plantex AI team (Singapore)

[hardness1020]

Thanks for the detailed writeup, this is exactly the kind of feedback that's most useful at this stage. Going through your points one by one:

Confirmed gaps (will address)

1. --version flag. You're right, there isn't one. The version is 0.1.0 (hardcoded in pyproject.toml and src/leeway/__init__.py), but the CLI doesn't surface it. I'll add a --version option.

2. Non-interactive workflow invocation. Also a real gap. Today your options are:

   • Interactive: launch leeway, then type /<workflow_name> <context>.
   • One-shot: leeway -p "/<workflow_name> <context>" (the / dispatch goes through src/leeway/ui/runtime.py).

   That second form technically works for cron, but it's overloaded and non-obvious. A dedicated leeway workflow run <name> subcommand makes sense, and I'll plan it in.

3. Python API. Not exposed publicly yet. WorkflowEngine lives at src/leeway/workflow/engine.py but isn't part of the import surface. I agree this is worth doing, both for embedding and for testability.

Partial clarification

4. Signal documentation. Signals are actually documented in docs/workflows.md under the transition/edge section, but your deeper question deserves a direct answer:

   • Signals are declared per node via the outgoing edges in the workflow YAML (when: { signal: <value> }).
   • The workflow_signal tool validates the LLM's output against the node-scoped list of declared signals (see src/leeway/workflow/signal_tool.py and signal_decisions_for_node() in src/leeway/workflow/types.py).
   • So they're effectively pre-declared per node, not globally, and not free-form at runtime.

   I'll add an explicit "Signals" section to the docs covering this, since it's the first thing a workflow author needs to understand.

Needs repro

5. --print asyncio crash. I can't reproduce this from a code read. The print path uses asyncio.run() (src/leeway/cli.py around line 134), which should create a fresh event loop every time. A few questions to narrow it down:

   • Python version and OS?
   • Exact command (and is the prompt coming from a shell, Jupyter/IPython, or another async context)?
   • Full traceback?

   If you can drop those in a follow-up comment I'll get it fixed.

Roadmap questions

6. v0.1.0/v1.0.0 timeline, signal validation strategy, and Python API plans are product calls I'd rather think through properly than answer off the cuff here. I'll follow up on this thread (or open tracking issues) once I've written them down.

Really appreciate Plantex taking the time on this. The "what works / where I struggled / questions" structure made every item actionable.