skills

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

@@ -0,0 +1,48 @@
+# 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.
+   - MCP: `wf.admin.list_sources`
+   - CLI: `wf cap list --format ids`
+2. List workflow capabilities.
+   - MCP: `wf.workflow.list_capabilities`
+   - CLI: `wf cap list`
+3. Inspect one capability.
+   - MCP: `wf.workflow.inspect_capability`
+   - CLI: `wf cap inspect <name>`
+4. Bootstrap a draft workspace.
+   - MCP: `wf.workflow.create_draft_workspace_from_capability`
+   - CLI: `wf draft create-from-capability <workspace_id> <capability>`
+5. Inspect/patch/validate the workspace until valid.
+   - Prefer focused helpers when available.
+   - Use JSON Patch only for general edits.
+6. Save an artifact.
+   - Full workflow: `create_artifact_from_workspace`
+   - Reusable wrapper: `create_wrapper_from_workspace`
+7. Save and validate a deployment.
+8. Run the deployment.
+9. Inspect the run summary first; read bounded traces only when needed.
+
+## 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, and trace count.
+
+## Result Handling
+
+`run_deployment` returns compact status by default. Capture `run_id` even for
+completed or failed runs. Use:
+
+- `inspect_run` for compact stored result.
+- `read_run_trace` for explicit debug slices, for example
+  `{"start": 0, "limit": 25}`.
+- `resume_run` only for interrupted runs.
+
+Do not ask for unbounded traces.