How it behaves
dsh_workflow accepts named workflows, natural-language authoring requests and restricted inline workflows through run_workflow. /workflow create <request> and unknown-name natural-language requests hand the intent to the current main agent. The agent investigates the workspace, then starts a workflow with source and manifest. By default, starting a run returns { runId, status, jobId? } without waiting; use --wait or the tool argument wait: true where supported. approvalMode: always and trusted-local workflows retain their approval requirements.
Workflow discovery is deterministic: built-ins and patterns, project entries in .dsh/workflows, then personal entries in $DSH_HOME/workflows. A project entry with the same name overrides a personal entry. In one directory, .workflow.json takes precedence over .ts, .mjs and .js.
Commands
| Command |
Purpose |
/workflow list |
List discoverable workflows |
/workflow <name> [JSON args] |
Run a named workflow |
/workflow runs [--all|--limit N] |
List runs |
/workflow show [--full] [runId] |
Show the latest or selected run |
/workflow pause|resume|stop [runId] |
Control an active run |
/workflow rerun|resume-run <runId|savedName> [JSON args] [--wait] |
Rerun from a snapshot or resume cached work |
/workflow save <runId> <name> [project|personal] |
Save a run as a workflow |
/workflow delete-run <runId> [--force] |
Delete a run |
/workflow review can capture the current Git range and start the built-in review workflow. workflow_manage also supports renaming, revising, deleting saved workflows and pruning retained runs.
Persistence and requirements
Runs are stored by default in .dsh/workflow-runs/<run-id>/, including run.json, append-only events.jsonl, a workflow.workflow.json execution snapshot, results/ for completed verified effect-cache entries and artifacts/ for named evidence. Terminal runs are cleaned according to maxRetainedRuns; prune can also preview or perform cleanup. The plugin requires Node.js >=22.19 and a DSH snapshot matching compatibility.json.
Safety and validation
Capsules use dsh.workflow v1 and include a manifest, source, intent, inputs, requirements and provenance. Path traversal, symlinks, oversized files, unknown fields, incompatible versions and filename/manifest mismatches fail before execution. Generated scripts run in a capability-only VM with JSON boundaries and deterministic guards. runAgent may return null for ordinary subtask failures, while explicit handles preserve failure results.
Written from the project's own documentation and kept in sync with it. Where the two disagree, the source is authoritative — read the README on GitHub