[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 plan_workflow 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] 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.

[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.

[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 an execution plan for a multi-step workflow.

Use this when the goal matches one of the built-in types below; use create_workflow instead 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] Advance a planned workflow. Pauses at approval gates.

IMPORTANT — this MCP server has no dispatcher and cannot call other skills' MCP tools itself. Steps are recorded as 'not_executed' and the run finishes with outcome='dispatch_required' (NOT 'completed'), returning each pending step's skill/tool/params. YOU (the calling agent) must then perform those skill/tool calls in order. A workflow only reaches 'completed' when every step genuinely executed via a real dispatcher (embedders supplying one to WorkflowExecutor).

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] 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.

Note: this server has no dispatcher — after approval, remaining steps are recorded as 'not_executed' and the result carries outcome='dispatch_required' with a 'pending_dispatch' list for the calling agent to perform (see run_workflow).

Returns: Updated workflow state after resuming.

[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), 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' — which, on this server (no dispatcher), are approval gates only. Steps YOU performed from pending_dispatch are still 'not_executed' 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 skipped; 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_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] 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), 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.

[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.

[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: outcome='dispatch_required' means you must perform the pending steps yourself, '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 plan_workflow; 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] 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}}}.