99 lines
4.4 KiB
Markdown
99 lines
4.4 KiB
Markdown
---
|
|
name: wf-workflow
|
|
description: 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:
|
|
|
|
```bash
|
|
# 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.
|