--- name: dynworkflow-cli description: Operate the dynworkflow standalone CLI for durable multi-agent workflows. Use when installing or preflighting dynworkflow, creating a first workflow file, running or serving a workflow, monitoring runs, reading JSON output, pausing, resuming, stopping, deleting, or diagnosing Codex, Claude Code, and Pi executors. When workflow JavaScript must be written or changed, use the companion workflow-authoring skill for the code itself. --- # Operate dynworkflow Use the singular executable name `dynworkflow`. Do not invent commands or flags from the Pi `workflow` tool: the standalone CLI and the Pi tool are different surfaces. ## Establish the task 1. Run preflight checks before the first real workflow. 2. Load `workflow-authoring` when creating, editing, reviewing, or debugging workflow JavaScript. Read only its references needed for the requested change. 3. Choose one-shot execution or a long-lived runtime. 4. Keep the same project identity across later inspection and control commands. 5. Inspect the settled run and report its actual state, result, usage, and missing coverage. ## Preflight Run: ```bash node --version dynworkflow version dynworkflow doctor dynworkflow help ``` Require Node.js 20.11 or newer. The Claude Code plugin places `dynworkflow` on Claude's Bash `PATH`; after a fresh plugin installation, reload plugins or start a new Claude Code session if the command is not yet visible. Outside the plugin, install it with: ```bash npm install -g @fish59fish/dynamic-workflows ``` Inspect the requested adapter's line in `doctor`; its exit code is nonzero only when all adapters are unavailable, so exit code 0 alone does not prove that a specific executor works. Codex and Claude Code do not require the optional Pi SDK. ## Prepare a workflow There is no `dynworkflow init`, `validate`, or `capabilities` command. Start from a trusted existing workflow or copy the shipped provider-free smoke example `examples/hello.workflow`. Use `workflow-authoring` before changing workflow code. Do not call `run` a validation step: a successfully parsed script begins execution and may launch agents or modify a workspace. Treat workflow JavaScript as trusted code. The orchestration VM protects deterministic resume behavior; it is not a security sandbox. ## Run once Run locally and wait for settlement: ```bash dynworkflow run ./audit.workflow.js \ --executor claude-code \ --args '{"scope":"src"}' ``` Add `--ui` for a loopback dashboard. Use `--args @args.json` for complex inputs. Set explicit bounds such as `--concurrency`, `--max-agents`, `--agent-timeout-ms`, or `--token-budget` only when the task or user supplies them; do not invent budget caps as defaults. ## Use a long-lived runtime Start the project owner and dashboard in a foreground terminal: ```bash dynworkflow serve --state-dir ~/.dynamic-workflows ``` Submit later work: ```bash dynworkflow run ./audit.workflow.js --executor codex ``` An active runtime owns child processes. A submitted `run` returns immediately unless `--attach` is present. Use `--detach` only to require an already-active runtime; it fails instead of falling back to local execution. If `serve ./flow.js` discovers an existing runtime, it prints that dashboard and does not submit the file; use `run` to submit to the existing owner. Ctrl-C on `serve` pauses active runs and preserves their completed-call journals. ## Inspect and control Use: ```bash dynworkflow list dynworkflow show dynworkflow pause dynworkflow resume --attach dynworkflow resume --script ./revised.workflow.js --attach dynworkflow stop dynworkflow delete ``` - Use `pause` to retain resumability. - Resume only paused or failed runs. Resume keeps the same run ID and replays the longest unchanged completed-call prefix; interrupted in-flight Codex or Claude Code calls start fresh. - Use `stop` only when the user does not need to resume the run. - Use `delete` only with explicit intent. It removes the durable record and aborts live work. - Do not try to resume a completed run; the standalone CLI has no completed-run fork command. ## Use machine-readable output Add `--json` when another tool must consume the result: ```bash dynworkflow list --json dynworkflow show --json ``` `list --json` returns lightweight summaries; `show --json` returns full agent detail. A detached daemon submission returns a run ID and dashboard URL, whereas a local or attached run returns the settled run, so do not assume every `run --json` response has the same shape. Treat exit 0 as completed, exit 2 as paused, and exit 1 as another settled failure for locally owned or attached runs. Preserve stderr when diagnosing progress or errors. ## Preserve project identity and sensitive state Keep `--cwd` and `--state-dir` consistent across `run`, `list`, `show`, and control commands. Relative `--state-dir` values, workflow files, `--script` files, and `--args @file` resolve from the shell process working directory, not from `--cwd`; use absolute paths when those differ. Run IDs are not globally searchable. If only a run ID is known and the original project cwd or state root is missing, obtain those values from the runtime owner; the CLI cannot recover them from the ID alone. Durable state can contain scripts, arguments, prompts, outputs, histories, and usage. Do not print or publish full run JSON without checking it for secrets. The dashboard is token-authenticated and loopback-only; use SSH port forwarding rather than a non-loopback bind. ## Report completion accurately Separate: - CLI installation and executor preflight; - workflow authoring or review; - run submission; - live, paused, failed, or completed state; - result and usage inspection; and - destructive cleanup. Do not report a workflow as successful merely because a daemon accepted it or `doctor` found some adapter.