# Draft Workspaces Reference Use draft workspaces for iterative workflow authoring. They are mutable and revisioned; artifacts are immutable and versioned. Before writing or patching a draft, inspect the current public shape: wf schema draft wf schema DraftUseStep ## Draft Shape A draft has: - `name` - `input_schema` - `state_schema` - `output_schema` - `start` - `steps` - `routes` - optional top-level `output` `steps` are keyed by stable ids. `routes` map outcomes to another step id or `__end__`. ## Mapping Rules Step input bindings read graph values into node-local input: ```json { "target": "text", "path": "input.text" } ``` Step output bindings write node-local output into workflow state: ```json { "source": "echoed", "target": "state.echoed" } ``` Top-level workflow output uses `path` / `target`, not step-level `source` / `target`: ```json { "path": "state.echoed", "target": "echoed" } ``` ## Workspace Flow 1. Create workspace from capability. 2. Get workspace with `include_draft=true` before patching. 3. Patch with current `revision`. 4. Validate workspace. 5. Save artifact or wrapper from workspace. Capability-backed creation auto-binds required capability inputs only. Optional inputs remain declared by the capability but are omitted from the initial step input map. Add one deliberately when the workflow should expose it: ```bash wf draft bind report_ws --revision 2 --step call --from input.path --to local.path ``` If a patch returns `revision_conflict`, fetch the workspace again and retry against the latest revision. Forward routes in drafts are allowed as invalid intermediate state. If `wf draft add-step --route ok=collect` returns `status: invalid`, add the missing `collect` step next, then run `wf draft validate`. Do not save or compile until validation is valid. ## Focused Helpers Prefer focused helpers over JSON Patch for common edits: - `set_draft_name` - `set_draft_route` - `set_step_input_map` - `set_step_output_map` - `set_workflow_output_map` - `bind_draft` - `add_step_from_capability` - `branch_draft` - `handle_draft` - `compile_draft_workspace` CLI equivalents: ```bash wf draft set-name --revision --name wf draft set-route --revision --step --outcome ok --to wf draft set-input --revision --step --map input.text=text wf draft set-input --revision --step --merge --map input.other=other wf draft set-output --revision --step --map text=state.text wf draft set-output --revision --step --merge --map other=state.other wf draft set-workflow-output --revision --map state.value=result wf draft set-workflow-output --revision --merge --map state.other=other wf draft branch --revision --step --route ok=__end__ --route error=fail wf draft handle --revision --to fail --branch lookup:error --branch transform:error wf draft compile wf draft bind --revision --step --from local. --to state. wf draft bind --revision --step --from input. --to local. wf draft add-step --revision --step --capability --from-step --from-outcome ok --route ok=__end__ --route error=fail --input input.text=text --bind-output result=state.result ``` `set-workflow-output` maps a graph source path (`input.*`, `state.*`, or `context.*`) to one public workflow output field. It edits top-level `WorkflowDraft.output`; `set-output` edits one step's local-to-state bindings. For single-field `input.*` and `state.*` sources, missing public output schema fields are projected automatically from the source schema. `set-input` direction: `input.text=text` means graph source `input.text` maps to node-local target `local.text`. Targets are bare node-local field names; never prefix the target with `local.`. `set-output` direction: `text=state.text` means node-local source `local.text` maps to graph target `state.text`. Without `--merge`, `set-input`, `set-output`, and `set-workflow-output` replace the whole map for that step or output scope. Use repeated `--map` flags in one command for a complete replacement. Use `--merge` only when adding/updating entries over multiple revisions. `bind input.x -> local.x` is schema-aware and idempotent when `input.x` is already declared. Use it for repair hints or schema projection. Use `set-input --merge --map input.x=x` when you only need to update a step input map. - `bind_draft` Declares a workflow input/state/output schema field from a capability local input/output schema and merges the matching step binding. Use `input/state -> local` for step inputs and `local -> state/output` for step outputs. Prefer this over manual JSON Patch when validation says a target schema field is missing. The selected step must have `use` so the helper can find the capability schema. It intentionally rejects non-capability/control steps instead of guessing. A `local.x -> output.y` bind is atomic: it projects the capability field schema into both workflow state and output schemas, writes `local.x -> state.y` on the step, and publishes `state.y -> output.y` at the workflow boundary. ```bash wf draft bind --revision --step --from local. --to state. wf draft bind --revision --step --from input. --to local. wf draft bind --revision --step --from local. --to output. wf draft validate ``` - `add_step_from_capability` Adds a new capability-backed step with explicit route, input bindings, and output-to-state schema/binding wiring in one revision. It can set the incoming edge, outgoing edges, input map, and output-to-state schema/binding. Use `--route OUTCOME=TARGET` for each outcome; when omitted and the capability declares a single outcome, that outcome routes to `__end__`. Multi-outcome capabilities require exact route coverage; missing or unknown outcomes are rejected before mutation. When `add-step --route` rejects an outcome, the error reports declared outcomes and direct add/remove repair guidance. Remove unknown route entries and add one route for each missing declared outcome. It still requires explicit choices; if you do not know a map, inspect the capability or run validation rather than guessing. Explicit top-level `--input input.x=x` and `--input state.x=x` mappings project the corresponding workflow input/state schema fields from the capability input schema. ```bash wf draft add-step --revision --step --capability --from-step --from-outcome ok --route ok=__end__ --route error=fail --input input.text=text --input input.other=other --bind-output result=state.result --bind-output title=state.title wf draft validate ``` Repeat `--input` and `--bind-output` once per mapping. Do not write `--bind-output title=state.title summary=state.summary`; the second mapping is an unexpected extra argument because it is not attached to its own flag. - `branch_draft` Updates routes for an existing step in one revision without rewriting the full routes object. Supply `--route OUTCOME=TARGET` for each outcome to set or update. - `handle_draft` Routes multiple source step outcomes to a common target. Supply `--branch STEP:OUTCOME` for each source outcome and `--to TARGET` for the shared destination. - `compile_draft_workspace` API/RPC/MCP returns the compiled raw plan plus required capabilities without mutating or saving the draft workspace. The CLI prints only the raw plan JSON on success. On invalid draft status, it returns structured diagnostics without a `compiled_plan`. Validation repair hints are product guidance. If a diagnostic suggests `wf draft bind`, run that exact focused command before hand-editing schemas or step bindings, then validate the new revision. Remove commands are for recovery. They do not delete schema fields and `remove-step` does not remove inbound routes. Validate after removal and repair the resulting diagnostics explicitly. Use JSON Patch for structural edits the helpers do not cover. For larger patches, write a JSON Patch array to a file and pass it with `--input-file`: ```bash wf draft patch --revision --input-file draft-patch.json ``` The patch file must be an RFC 6902 JSON Patch array, not a full draft object.