[WRITE] Approve a workflow that is waiting for human confirmation.

Use this only after showing the user the pending step and getting explicit human consent; use cancel_workflow instead when the approval is rejected. Only works when workflow state is 'awaiting_approval'. After approval, execution continues to the next steps.

Without --dispatch, the steps before the gate are 'not_executed': Pilot has no record that they ran, whatever the gate's message says. approve refuses (listing them in not_executed_before_gate) until acknowledge_not_executed=True — set it only after you performed each of those steps yourself and showed the user their results. They are then recorded as 'reported_done' and not handed out again.

Note: with --dispatch, approving runs the next steps (this call takes as long as they do; if it times out in your client, Pilot carries on — check get_workflow_status once it answers again, and never perform those steps yourself). Without it, the remaining steps are recorded as 'not_executed' and the result carries outcome='dispatch_required' with a 'pending_dispatch' list for you to perform (see run_workflow); the workflow then never reaches 'completed'.

Returns: Updated workflow state after resuming.

[WRITE] Cancel a workflow — move it to the terminal CANCELLED state.

Use this when an approval is REJECTED, a review flags the plan as unsafe, or an operator decides the workflow must never run. A cancelled workflow is dead: run_workflow and approve refuse to execute it. Without this, an approval-rejected PENDING workflow could still be picked up and run.

Without confirm=True this only previews: it returns blast_radius — the workflow's id, type and state, the executed steps that stay applied (left_in_place: cancelling part-way leaves a half-applied change), steps performed outside Pilot (performed_outside_pilot), steps already handed to you in pending_dispatch that cancel can neither stop nor undo (handed_out_to_caller), the steps that would be skipped (would_skip), steps with unknown effects, and blockers — and changes nothing. Show that to the user and get their explicit decision. Do not set confirm=True on your own because the user asked to cancel earlier — the user has not seen the preview yet.

Cancel only stops FUTURE steps. It does NOT undo already-completed steps — use rollback() to reverse those. Refused with confirm=True: an already completed/failed/cancelled workflow, a step whose status Pilot does not recognise, a workflow record that cannot be read, and — unless acknowledge_unknown_effects=True — a step left 'running' or 'interrupted' (listed in unknown_effects). The cancellation is written to the workflow audit log.

Returns: Preview: {"action": "preview", "blast_radius", "hint"}. Acting: the workflow state (state='cancelled', outcome='cancelled', action='cancelled') with blast_radius, or an error if refused.

[WRITE] Confirm a draft workflow — changes state from DRAFT to PENDING.

Use this once the user has approved the draft's steps; call update_draft instead if anything still needs changing. After confirmation, the workflow can be executed via run_workflow(). Optionally saves as a YAML template for future reuse. Refused — the draft stays a draft and nothing is saved — while any destructive or unclassifiable step, or any step passing confirm=True, lacks a require_approval gate before it.

Returns: Confirmed workflow summary. Call run_workflow() to execute.

[WRITE] Create a custom workflow dynamically from a step list.

Use this when you already know the steps and no built-in template matches; prefer create_workflow_from_template when one does, and design_workflow when the user gave a goal rather than steps. Call get_skill_catalog first for the skill and tool names a step may target.

Each step dict must have: action, skill, tool, params. Optional: rollback_tool, rollback_params. action="require_approval" (skill "pilot", tool "approve") inserts a human approval gate. A workflow whose destructive or unclassifiable step, or a step passing confirm=True, has no gate before it is REFUSED — nothing is saved — and the error names the step and the gate to insert.

Returns: dict with workflow_id and plan summary. Next call review_workflow to check the plan, then run_workflow to execute. Nothing is undone automatically on failure; see rollback.

[WRITE] Create and save a workflow from a template, ready for run_workflow.

Takes a template name (workflow_type) plus its params, builds the steps the template defines, and persists the workflow in state "pending" — it is not a dry run. Templates are the built-in types below plus custom YAML templates (list_workflows shows both). Use this when the goal matches a template; use create_workflow instead to save your own step list when none of them fit. A custom YAML template whose destructive or unclassifiable step (or step passing confirm=True) has no require_approval gate before it is refused, naming the step and the file to fix.

Available workflow types:

• clone_and_test: Clone VM → apply changes → monitor → approve → commit

• incident_response: Diagnose alert → collect info → approve → remediate

• plan_and_approve: Wrap aiops batch operations with approval gate

• compliance_scan: Read-only health/capacity/anomaly check (no approval)

Returns: dict with workflow_id, steps summary, and plan details.

[WRITE] Start designing a workflow from a natural language description.

Call this when the user describes a complex operation and you need to design a multi-step workflow. Returns a DRAFT workflow with proposed steps for the user to review and edit before execution.

Design flow: design_workflow → update_draft (add steps, then iterate on user feedback) → confirm_draft (state becomes PENDING) → run_workflow.

Use get_skill_catalog() first to see which tools the steps may target.

Returns: dict with workflow_id (state=DRAFT), proposed steps placeholder, and instructions for the AI to fill in steps via update_draft.

[READ] Get the complete catalog of available skills and tools for workflow design.

Use this to understand what building blocks are available when designing a custom workflow, then feed the skill and tool names into create_workflow or update_draft steps. Note this is a static curated catalog, not a live query of each skill's registry, so it may lag a skill's actual tool list; pilot cannot call these tools itself — the calling agent does.

Returns: dict mapping skill name → {description, tools: {tool_name: {risk, desc}}}.

[READ] Get current workflow state, diff report, and audit log.

Use this to poll a workflow after run_workflow and to find out why one stopped: steps with status 'not_executed' are yours to perform (the server runs without --dispatch), state 'awaiting_approval' means call approve. Returns a point-in-time snapshot and does not advance the workflow.

Returns: Full workflow state including steps, audit log, and diff report.

[READ] List all available workflow templates (built-in + custom).

Use this first to see whether a template already covers the goal, then pass its name to create_workflow_from_template; if none fit, use create_workflow instead. Built-in templates are always available. Custom templates are loaded from ~/.vmware/workflows/*.yaml — drop a YAML file there to add your own workflows.

Returns: dict with builtin and custom workflow lists, each with name, description, steps count, plus active_workflows — the IDs of in-flight runs to pass to get_workflow_status.

[READ] Sanity-check a planned workflow before execution.

Performs structural validation only — does NOT call into other skills. Catches the common authoring errors before they hit production:

• Delete-then-use: a step deletes resource X, a later step references X

• Missing required params: a step has empty params or placeholder values

• Cross-skill order issues: surfacing the cross-skill dispatch sequence

• Risk profile: count of destructive / write / read-only / unclassified steps

• Approval coverage: is every destructive OR unclassifiable step gated behind a preceding require_approval?

Each step is placed in a tier from the tool's entry in get_skill_catalog first, then from name patterns. A step that matches neither is reported as ungated_unclassified rather than assumed safe: pilot dispatches nothing itself and cannot inspect a sibling skill's annotations, so "this tool is unknown to me" is the honest finding, and it needs the same gate a known destructive step does. The remedy is in the message — add the tool to SKILL_CATALOG with the risk its own skill declares, or add a gate.

Medium-risk writes (create / scale / enable) are classified and counted but not gated: the family gates destructive work, and several built-in templates deliberately create in staging before asking for approval.

Returns: Dict with keys: - verdict: "approved" if no structural issues, otherwise "needs_revision" - findings: list of {severity, kind, message, step_index}. Kinds ungated_destructive, ungated_unclassified and destructive_in_parallel_group are what run_workflow refuses on; force=True overrides that only for a built-in template, never for a custom workflow's missing approval gate. - summary: counts — total/destructive/write/read_only/approval_gates, parallel_groups, est_duration_min, plus classified_steps and unclassified_steps so an "approved" verdict can be told apart from a workflow this review could not read.

[WRITE] Abort a workflow and rollback completed steps in reverse order.

Without confirm=True this only previews: it returns blast_radius — the workflow's id, type and state, the executed steps whose rollback_tool would run with its rollback_params, secrets redacted (would_roll_back — these often carry confirm=True, and this call's confirm=True is the decision to run them), the executed steps that have none and stay applied (left_in_place), steps you performed from pending_dispatch that Pilot will not reverse (not_reversed_by_pilot: they have an undo you must call; not_reversible_outside_pilot: they have none — a clone, a production resize), undos that would leave something behind (leaves_behind on a would_roll_back entry), steps with unknown effects, and blockers — and changes nothing. Show that to the user and get their explicit decision. Do not set confirm=True on your own because the user asked for a rollback earlier — the user has not seen the preview yet.

Nothing rolls back automatically: a failed step leaves the workflow 'failed' and stops. This tool is the explicit, best-effort undo, and it only reverses steps pilot itself recorded as 'success' — without --dispatch, approval gates only. Steps YOU performed from pending_dispatch are 'not_executed' (or 'reported_done' once acknowledged at a gate) here, so to undo them call each one's rollback_tool with its rollback_params yourself, last step first. Embedders that pass a dispatcher to WorkflowExecutor get those calls made for them. Steps without a rollback_tool are reported 'not_reversible' and stay applied; an undo that does not remove what the step created is 'partial' (a clone powered off stays). A failed undo does not stop the rest. The workflow state is set to 'failed' afterwards.

Refused with confirm=True: a workflow in draft, completed, rolling_back or cancelled state, a step whose status Pilot does not recognise, a workflow record that cannot be read, and — unless acknowledge_unknown_effects=True — a step left 'running' or 'interrupted' by a Pilot process that stopped mid-dispatch (listed in unknown_effects).

Returns: Preview: {"action": "preview", "blast_radius", "hint"}. Acting: the workflow state with "action": "rolled_back" ("rollback_incomplete", with outcome "failed" and an error naming them, when an undo failed or its effect is unknown), rollback_results for each step pilot recorded as succeeded, and blast_radius. Check get_workflow_status afterwards to see which steps were actually reversed and which were skipped.

[WRITE] Advance a planned workflow. Pauses at approval gates.

Who runs the steps depends on how this server was started:

• with --dispatch (or VMWARE_PILOT_DISPATCH=stdio): Pilot runs each step itself in that skill's own MCP server, stops at each approval gate, and the workflow can reach 'completed'. This call takes as long as the steps it runs. If it times out in your client, Pilot carries on (and answers nothing else until the step ends); afterwards get_workflow_status shows the outcome. NEVER perform the steps yourself.

• without it (the default): Pilot runs nothing. Steps are recorded as 'not_executed' and the run ends with outcome='dispatch_required' (NOT 'completed'), listing each step in 'pending_dispatch'. YOU (the calling agent) must perform those skill/tool calls in order. The result says which: a 'pending_dispatch' list means you run them.

Safety: the workflow is structurally reviewed before each run. Runs are REFUSED if review finds ungated destructive or unclassifiable steps, or destructive steps inside a parallel group. For a built-in template, force=True overrides that (forced runs are written to the workflow audit log). For a custom workflow (create_workflow, design_workflow, or a YAML template) an ungated step is refused even with force=True: add a require_approval step before it instead.

When an approval gate is reached, the workflow pauses with state 'awaiting_approval'. Call approve() to continue.

Returns: Current workflow state with 'outcome' (completed | awaiting_approval | dispatch_required | failed) and, when dispatch is required, a 'pending_dispatch' list of steps for the agent to perform.

[WRITE] Update a DRAFT workflow's name, description, or steps.

Call this after design_workflow() to fill in the actual steps, or to modify steps based on user feedback. Use it only while the workflow is still DRAFT — after confirm_draft the steps are frozen and you must create_workflow a new one instead.

Each step dict: {action, skill, tool, params, rollback_tool?, rollback_params?} Use action="require_approval" for approval gates. A draft may be saved without them while it is being designed; the result lists every step that still needs one, and confirm_draft refuses until none are left.

Returns: Updated workflow summary for user review.