run-lightflows

# Running & Resuming Lightflow Workflows (`run_lightflows`) > **Authoring new workflows?** Read `create_lightflows` instead. ## Fast-Path Rules 1. **Read only `SKILL.md`, then run `start` directly**: do **not** read `lightflow.yaml`, `actions.py`, or `README.md` first. The CLI compiles the manifest and prints any gate's `Instructions`, `Payload Schema`, and the exact `Resume with:` command. `--lightflow=<path>` accepts a manifest file or its directory. 2. **Skip redundant `status` calls & chain cleanup**: when `start` or `resume` exits `0` (`Lightflow completed successfully!`), do **not** run `status`. If asked to clean up afterwards, chain `start ... && cleanup ...` (`&&` stops naturally at an `EXIT_CODE=2` gate). ## 1. Commands `python3 -m lightflow` is equivalent to `lightflow` when the console script is not on `PATH`. Runs remember their manifest, so `status`, `resume`, `visualize`, and `cleanup` need only `--log_id`; if the manifest file moved, pass `--lightflow=<new path>` once and it is re-recorded. ```bash lightflow start --lightflow=<dir_or_manifest> --log_id=<run_id> [--payload='{...}' | --payload=@file.json] lightflow start ... --dry_run # only when asked to preview; ends with a Summary: line and a 💡 --payload seed hint # Resolve a paused gate once its Instructions are satisfied (APPROVE sets approved=true itself) lightflow resume --log_id=<id> --stage=<gate_stage> --resolution=APPROVE --payload='{...}' lightflow resume --log_id=<id> --stage=<gate_stage> --resolution=REJECT --comment="..." # runs rollback_action; dependents are blocked # After fixing a failed stage: re-arms only failed stages, keeps completed work lightflow resume --log_id=<id> [--payload='{...}'] lightflow status --log_id=<id> # one line per stage + any paused gate's Instructions, Schema, resume command; --verbose adds payload + stamp log lightflow list # every saved run: log ID, lightflow, state, last activity, manifest lightflow visualize --log_id=<id> --output=/tmp/viz.html lightflow cleanup --log_id=<id> # deletes the run's state only; workflow artifacts on disk are untouched ``` ## 2. Exit Codes & Governance - **`0` COMPLETED**: done; report the stage outputs printed to `stdout`. - **`2` SUSPENDED at an `operator_action`**: follow the printed `Instructions`, then `resume` with a payload matching the `Payload Schema`. `--resolution=APPROVE` validates `--payload` against the gate's `json_schema`; on a validation error the gate stays paused, so fix the payload and re-run (`status` reprints the schema in a new conversation). - **`1` FAILED or REJECTED**: the footer names the root cause and the exact `resume` command. Fix the cause, then `resume` — **never `start --force`**, which discards completed stages and is only for rerunning a *completed* run from scratch. A rejected gate (`🛑`) is terminal unless deliberately re-opened: `resume --stage=<gate> --resolution=APPROVE --payload='{...}'` decides again in one call; a bare `resume --stage=<gate>` only re-opens it. - **`status` exits like the run**: `0` completed · `1` failed, rejected, or interrupted · `2` paused · `3` no saved state · `4` running in another process (wait; don't `resume`) · `5` waiting: a `polling_policy` stage yielded before its condition was met, nothing is broken, `resume` once it holds. Use `--verbose` only when you need the payload, stamp log, or Mermaid diagram.