lda-wf/skills/wf-workflow/references/workflow-lifecycle.md

Workflow Lifecycle Reference

Use this when an agent needs to go from available capabilities to a saved, validated, runnable deployment.

Primary Path

1. List sources.
   • CLI: wf source list
2. List workflow capabilities.
   • CLI: wf cap list
3. Inspect one capability.
   • CLI: wf cap inspect <name>
4. Bootstrap a draft workspace.
   • CLI: wf draft create <workspace_id> --capability <capability>
5. Inspect/patch/validate the workspace until valid.

   • Use focused CLI commands (set-name, set-route, set-input, set-output) for common edits.

   • set-input, set-output, and set-workflow-output replace their ordered canonical binding lists. Repeated sources preserve fan-out to distinct targets. The --merge variants are compatibility-only and cannot preserve canonical ordering or repeated-source fan-out; existing literals are retained for input merges.

   • set-workflow-output accepts ordered path/value bindings. Nested input.* and state.* sources can project declared source schemas into missing output fields; literals and context.* require declared targets. --clear restores implicit same-name state fallback.

   • Before mapping into a new workflow input, state, or output field, prefer wf draft bind --from ... --to ... when it should mirror a capability local input/output property. It declares the matching schema and merges the binding in one revision-checked edit.

   • When adding a new capability-backed step, prefer:

     wf draft add capability ... --description "Step purpose" \
       --input state.value=request.value --value request.format='"json"'
     wf draft update capability ... --retry 0 --clear-timeout
     wf draft validate <workspace_id>
     

     Capability updates are presence-aware and preserve capability selection, routes, and outputs. Input flags replace the complete canonical input list; use --bindings-file for lossless path/value interleaving.

     For control flow, use the corresponding typed wf draft add <kind> command. Use raw wf draft patch only when changing structure that no focused helper covers.

   • Use JSON Patch only for general structural edits.

6. Save an artifact.
   • Draft artifact: wf draft save <workspace_id> --artifact <artifact_id> --version 1 --title "Workflow Title"
   • Complete raw plan: wf artifact create-from-plan workflow.plan.json --artifact <artifact_id> --version 1 --title "Workflow Title" --outcome ok
7. Save and validate a deployment.
   • wf deploy save <deployment_id> --artifact <artifact_id> --version 1 --binding <logical_source>=<concrete_source> (or wf deploy create alias)
   • wf deploy validate <deployment_id>
8. Run the deployment with an optional step budget.
   • CLI: wf run start <deployment_id> --input-file input.json with --max-steps 50000 (default 10_000 when omitted; at least 1)
   • Python: await deployment.run(input, max_steps=50_000)
   • The budget covers every frame and subgraph scope in the run. Exhaustion fails the run; it is never a routable workflow outcome and the denied handler never runs.
9. Inspect the run summary first; read bounded traces only when needed.

Raw Plan Escape Hatch

Draft workspaces are the normal interactive authoring path. If a compiler, fixture, or advanced client already has a complete raw JSON/YAML workflow plan, use the CLI escape hatch instead of writing a helper script around the Python API:

wf artifact create-from-plan workflow.plan.json \
  --artifact <artifact_id> \
  --version 1 \
  --title "Workflow Title" \
  --outcome ok \
  --binding <logical_source>=<concrete_source>

Do not pass draft JSON to artifact create-from-plan. Drafts use steps, routes, and step field use. Raw plans use nodes, edges, and node field node. See direct-plan-import.md for the exact shape.

Then continue with the normal deployment and run steps:

wf deploy save <deployment_id> --artifact <artifact_id> --version 1
wf deploy validate <deployment_id>
wf run start <deployment_id> --input-file input.json

If artifact save returns suggested_bindings, include each suggestion as a deployment binding:

wf deploy save <deployment_id> \
  --artifact <artifact_id> \
  --version 1 \
  --binding <logical_source>=<concrete_source>

If no suggestion is present, do not guess an account-like source binding; inspect sources and choose the concrete source explicitly.

Object Model

• Source: owner of capabilities, such as wf.std or everything.default.
• Workflow capability: graph-ready NodeSpec or saved wrapper artifact.
• Artifact: immutable saved workflow or wrapper.
• Deployment: mutable binding from artifact version to concrete sources.
• Run: durable stopped execution record with status, output, trace count, and step budget (max_steps, steps_executed, steps_remaining).

Result Handling

wf run start returns compact status by default. Capture run_id even for completed or failed runs. Inspection exposes the effective budget stored with the run (max_steps, steps_executed, steps_remaining). Use:

• wf run inspect <run_id> for compact stored result.
• wf run trace <run_id> --from 0 --limit 25 for explicit debug slices.
• wf run resume <run_id> only for interrupted runs. Resume reuses the persisted budget and accepts no replacement value.

Do not ask for unbounded traces.

Interrupt Resume Contracts

An interrupted run can carry a self-describing resume contract. Treat interrupt.resume_schema from wf run inspect as the source of truth for the payload you pass to wf run resume. Do not read workflow source code just to guess approval fields when the schema is present.