[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" inserts a human approval gate — run_workflow refuses ungated destructive steps.

Args: name: Workflow name (used as workflow_type). description: Human-readable description. steps: List of step dicts, each with action/skill/tool/params. save_as_template: If True, save as YAML to ~/.vmware/workflows/ for reuse.

Returns: dict with workflow_id and plan summary. Next call review_workflow to check the plan, then run_workflow to execute; rollback undoes it.

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

Args: goal: Natural language description of what the user wants to accomplish. constraints: Optional constraints (e.g. "must have approval before any destructive step", "use NSX for networking", "target is vcenter-prod").

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.

Args: workflow_id: The draft workflow ID. name: Workflow name (optional, updates workflow_type). description: Human-readable description. steps: Complete list of steps (replaces all existing steps).

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.

Args: workflow_id: The draft workflow ID to confirm. save_as_template: If True, save to ~/.vmware/workflows/ for reuse.

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.

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)

Args: workflow_type: One of the available workflow types. params: Workflow-specific parameters. clone_and_test: target_vm (str), change_spec (dict), monitor_minutes (int), target (str). incident_response: alert_entity (str), alert_name (str), target (str). plan_and_approve: operations (list[dict]), target (str), description (str). compliance_scan: target (str), check_alarms (bool), check_capacity (bool).

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 steps or destructive steps inside a parallel group, unless force=True (forced runs are written to the workflow audit log).

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

Args: workflow_id: The workflow ID from plan_workflow. force: Bypass blocking review findings (ungated_destructive, destructive_in_parallel_group). Use only with explicit human consent; the bypass is audited.

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.

Args: workflow_id: The workflow ID to approve. approver: Name of the person approving (for audit trail).

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.

Use this to undo steps that already ran; use cancel_workflow instead to stop a workflow that has not started yet or whose approval was rejected. Works in any state except 'completed'. Irreversible steps are skipped. The workflow state is set to 'failed' after rollback.

Args: workflow_id: The workflow ID to rollback.

Returns: Rollback results for each step. 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.

Cancel only stops FUTURE steps. It does NOT undo already-completed steps — use rollback() to reverse those. Cancel is valid only from a non-terminal state; cancelling an already completed/failed/cancelled workflow returns a teaching error. The cancellation is written to the workflow audit log.

Args: workflow_id: The workflow ID to cancel. reason: Optional human-readable reason (e.g. "approval rejected by on-call"), recorded in the audit log.

Returns: Updated workflow state (state='cancelled', outcome='cancelled'), or an error if the workflow is already terminal.

[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 vs. read-only steps

• Approval coverage: are all destructive ops gated behind a require_approval?

Args: workflow_id: The workflow ID returned by plan_workflow.

Returns: Dict with keys: - verdict: "approved" if no structural issues, otherwise "needs_revision" - findings: list of {severity, kind, message, step_index} - summary: counts (steps, gather/destructive/approval), groups, est_duration_min

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

Args: workflow_id: The workflow ID to query.

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