lda-wf/skills/wf-workflow/SKILL.md

name, description

name	description
wf-workflow	Use when an agent needs to discover workflow capabilities, create or patch draft workspaces, save workflow or wrapper artifacts, deploy, run, resume, debug, or troubleshoot workflows in this repository.

wf Workflow

Use this skill for the workflow lifecycle when the available front door is the repo-local wf CLI.

Prefer small discovery calls, draft workspaces, validation, and bounded trace reads. Do not write raw workflow plans unless the user explicitly asks for the low-level escape hatch or you already have a complete compiler/generated plan.

Workflow Lifecycle

1. Discover available capabilities with wf cap list.
2. Inspect one candidate with wf cap inspect.
3. Call one candidate with wf cap call when payload shape or upstream source reachability is uncertain.
4. Create a patchable draft workspace with wf draft create <workspace_id> --capability <qualified_name> when the first step is a known capability, or with wf draft create <workspace_id> --name <name> for a control-first, interrupt-first, end-first, or subgraph-first graph.
5. Set the entry point or whole workflow contract with wf draft set-start and wf draft set-contract when needed, then patch other targeted fields with focused commands or JSON Patch.
6. Validate with wf draft validate.
7. Save an artifact with wf draft save, or import a complete raw plan with wf artifact create-from-plan.
8. Save a deployment with wf deploy save or wf deploy create.
9. Validate with wf deploy validate.
10. Run with wf run start.
11. Inspect stopped runs with wf run inspect; read bounded trace slices only when debugging.

Rules

• Use workflow capabilities, not raw MCP tools, when building graphs.
• Use call_capability for single-call probes; use deployments/runs for durable lifecycle behavior.
• Treat wrapper hints as scaffolding, not semantic truth.
• Use draft workspaces for iterative authoring; avoid rewriting full drafts.
• Prefer focused draft edit commands before hand-writing JSON Patch.
• Treat set-contract schema files and repeated outcomes as whole-field replacements, not merges.
• Prefer draft bind or draft add capability when selected schema fields should be projected from a known node contract. Reserve JSON Patch for field-level schema surgery not covered by focused operations.
• If a complete raw JSON/YAML plan already exists, the CLI escape hatch is wf artifact create-from-plan; do not write helper scripts that call internal APIs directly.
• Use artifact create-from-plan only for complete raw plans; do not pass draft JSON to it.
• Use explicit source bindings at deployment time.
• Keep traces bounded with trace_range.
• Do not expect a newly saved workflow to become a new MCP tool mid-session.
• For MCP content blocks, add explicit extraction/wrapper steps instead of pretending content is always plain text.

References

Read only the reference needed for the current task:

• Start with system-model.md when lifecycle vocabulary is unclear.
• Use workflow-lifecycle.md for operation order.
• Use capabilities-and-wrappers.md before selecting a source capability.
• Use draft-workspaces.md for iterative editing.
• Use direct-plan-import.md only when a complete raw plan is required.
• Use troubleshooting.md after a public validation/run failure.

Before authoring JSON, query the live public model with wf schema; the references explain semantics while the command reflects the current shape.

Useful patterns:

# PowerShell preview
Get-Content skills/wf-workflow/references/system-model.md -TotalCount 80

# Targeted search
rg -n "trace|resume|binding_missing|wrapper_hints" skills/wf-workflow/references

• references/system-model.md: short explanation of how sources, capabilities, drafts, artifacts, deployments, runs, bindings, and traces fit together.
• references/workflow-lifecycle.md: end-to-end lifecycle and tool order.
• references/capabilities-and-wrappers.md: raw capability vs workflow capability, wrapper artifacts, and content-block handling.
• references/draft-workspaces.md: draft shape, mappings, patches, and save path.
• references/direct-plan-import.md: complete workflow plan JSON shape for wf artifact create-from-plan.
• references/troubleshooting.md: missing source/capability, unrunnable deployment, run/trace issues.

For shell-first workflows, also use the existing wf-cli skill.