{"id":"860116db-d033-4195-90a3-182fce4d3337","entityType":"agent","slug":"clawhub-zw008-vmware-pilot","name":"vmware-pilot","canonicalUrl":"https://www.xpersona.co/agent/clawhub-zw008-vmware-pilot","canonicalPath":"/agent/clawhub-zw008-vmware-pilot","generatedAt":"2026-10-09T17:29:18.576Z","source":"CLAWHUB","claimStatus":"UNCLAIMED","verificationTier":"NONE","summary":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-10-09T15:08:30.490Z","emptyReason":null},"description":"Use this skill whenever the user wants to design, execute, or manage complex multi-step VMware workflows with human approval gates and explicit, best-effort rollback. Pilot is the orchestration brain — it breaks a goal into steps across companion VMware skills (aiops, monitor, nsx, nsx-security, aria, vks, storage, avi), adds approval gates before destructive operations, and records per-step undo actions that run only when rollback is explicitly called, never automatically. Always use vmware-pilot for: \"clone and test before applying to production\", \"VMware incident response with checkpoints\", \"investigate alert root cause\", \"VMware rolling restart with health checks\", \"baseline capture and drift detection\", \"rolling maintenance with AVI drain\", or any VMware workflow needing approval gates or rollback. 15 built-in templates + custom YAML + AI-designed workflows. Do NOT use for single-step work — use vmware-aiops for one VM action, vmware-monitor for read-only queries, vmware-avi for load balancer queries.","descriptionLabel":"Source description","evidenceSummary":"Capability contract not published. No trust telemetry is available yet. 2.4K downloads reported by the source. Last updated 10/9/2026.","installCommand":"clawhub skill install s171xgnmqse0nqvgqvqnaq5f9183kyre:vmware-pilot","sourceUrl":"https://clawhub.ai/zw008/vmware-pilot","homepage":"https://clawhub.ai/zw008/skills/vmware-pilot","primaryLinks":[{"label":"View on ClawHub","url":"https://clawhub.ai/zw008/vmware-pilot","kind":"source"},{"label":"Homepage","url":"https://clawhub.ai/zw008/skills/vmware-pilot","kind":"homepage"}],"safetyScore":84,"overallRank":62,"popularityScore":42,"trustScore":null,"claimedByName":null,"isOwner":false,"seoDescription":"vmware-pilot technical dossier on Xpersona with agent coverage, OPENCLEW support, and live trust metadata."},"coverage":{"evidence":{"source":"public-profile","verified":false,"confidence":"medium","updatedAt":"2026-10-09T15:08:30.490Z","emptyReason":null},"protocols":[{"protocol":"OPENCLEW","label":"OpenClaw","status":"self-declared","notes":"Declared in the public agent profile."}],"capabilities":[],"verifiedCount":0,"selfDeclaredCount":1,"capabilityMatrix":{"rows":[{"key":"OPENCLEW","type":"protocol","support":"unknown","confidenceSource":"profile","notes":"Listed on profile"}],"flattenedTokens":"protocol:OPENCLEW|unknown|profile"}},"adoption":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-10-09T15:08:30.490Z","emptyReason":null},"stars":null,"forks":null,"downloads":2422,"packageName":null,"latestVersion":"1.12.0","tractionLabel":"2.4K downloads"},"release":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-10-09T15:08:30.489Z","emptyReason":null},"lastUpdatedAt":"2026-10-09T15:08:30.490Z","lastCrawledAt":"2026-10-09T15:08:30.489Z","lastIndexedAt":null,"nextCrawlAt":"2026-10-10T15:08:30.489Z","lastVerifiedAt":null,"highlights":[{"version":"1.12.0","createdAt":"2026-09-19T03:55:41.850Z","changelog":"Destructive MCP tools preview by default (confirm=False) and state their blast radius; confirm=True refuses on blockers or unreadable measurements. Requires vmware-policy>=1.17.0.","fileCount":13,"zipByteSize":49167},{"version":"1.11.1","createdAt":"2026-09-15T06:05:58.115Z","changelog":"CLI reads are audited under their MCP tool names; every CLI command declares what it reaches (needs vmware-policy 1.15.0)","fileCount":13,"zipByteSize":47110},{"version":"1.11.0","createdAt":"2026-09-15T03:13:30.366Z","changelog":"design catalog covers all thirteen companion skills","fileCount":13,"zipByteSize":47145},{"version":"1.10.1","createdAt":"2026-09-14T15:12:46.659Z","changelog":"investigate_alert and compliance_scan now call registered tools with real parameters; template steps are checked against the companions' registries.","fileCount":13,"zipByteSize":46953},{"version":"1.10.0","createdAt":"2026-09-12T07:53:19.320Z","changelog":"A step whose dispatch returns {\"error\": ...} or an isError result is now a failed step, on the forward and the rollback path — previously such a workflow reported completed and rollback then refused it. Found on a live vCenter.","fileCount":13,"zipByteSize":46173},{"version":"1.9.0","createdAt":"2026-09-12T00:14:12.299Z","changelog":"BREAKING: a custom workflow whose destructive steps carry no approval gate is rejected instead of running with a warning, and patch_deployment requires an explicit username.","fileCount":13,"zipByteSize":46100},{"version":"1.8.12","createdAt":"2026-08-31T00:35:46.615Z","changelog":"fix: run the suite on a non-UTF-8 machine, and stop one skill answering for another","fileCount":13,"zipByteSize":41514},{"version":"1.8.11","createdAt":"2026-08-30T15:20:38.577Z","changelog":"Second-round fixes from the 2026-08-30 VCF 9.1 re-test; vmware-policy floor raised to 1.11.0 (the engine no longer fails open when rules.yaml cannot be read).","fileCount":13,"zipByteSize":41606}]},"execution":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No published capability contract is available yet."},"installCommand":"clawhub skill install s171xgnmqse0nqvgqvqnaq5f9183kyre:vmware-pilot","setupComplexity":"low","setupSteps":["Install using `clawhub skill install s171xgnmqse0nqvgqvqnaq5f9183kyre:vmware-pilot` in an isolated environment before connecting it to live workloads.","No published capability contract is available yet, so validate auth and request/response behavior manually.","Review the upstream CLAWHUB listing at https://clawhub.ai/zw008/vmware-pilot before using production credentials."],"contract":{"contractStatus":"missing","authModes":[],"requires":[],"forbidden":[],"supportsMcp":false,"supportsA2a":false,"supportsStreaming":false,"inputSchemaRef":null,"outputSchemaRef":null,"dataRegion":null,"contractUpdatedAt":null,"sourceUpdatedAt":null,"freshnessSeconds":null},"invocationGuide":{"preferredApi":{"snapshotUrl":"https://www.xpersona.co/api/v1/agents/clawhub-zw008-vmware-pilot/snapshot","contractUrl":"https://www.xpersona.co/api/v1/agents/clawhub-zw008-vmware-pilot/contract","trustUrl":"https://www.xpersona.co/api/v1/agents/clawhub-zw008-vmware-pilot/trust"},"curlExamples":["curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-zw008-vmware-pilot/snapshot\"","curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-zw008-vmware-pilot/contract\"","curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-zw008-vmware-pilot/trust\""],"jsonRequestTemplate":{"query":"summarize this repo","constraints":{"maxLatencyMs":2000,"protocolPreference":["OPENCLEW"]}},"jsonResponseTemplate":{"ok":true,"result":{"summary":"...","confidence":0.9},"meta":{"source":"CLAWHUB","generatedAt":"2026-10-09T17:29:18.571Z"}},"retryPolicy":{"maxAttempts":3,"backoffMs":[500,1500,3500],"retryableConditions":["HTTP_429","HTTP_503","NETWORK_TIMEOUT"]}},"endpoints":{"dossierUrl":"https://www.xpersona.co/api/v1/agents/clawhub-zw008-vmware-pilot/dossier","snapshotUrl":"https://www.xpersona.co/api/v1/agents/clawhub-zw008-vmware-pilot/snapshot","contractUrl":"https://www.xpersona.co/api/v1/agents/clawhub-zw008-vmware-pilot/contract","trustUrl":"https://www.xpersona.co/api/v1/agents/clawhub-zw008-vmware-pilot/trust"}},"reliability":{"evidence":{"source":"runtime-metrics","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No trust, reliability, or runtime telemetry is available."},"trust":{"status":"unavailable","handshakeStatus":"UNKNOWN","verificationFreshnessHours":null,"reputationScore":null,"p95LatencyMs":null,"successRate30d":null,"fallbackRate":null,"attempts30d":null,"trustUpdatedAt":null,"trustConfidence":"unknown","sourceUpdatedAt":null,"freshnessSeconds":null},"decisionGuardrails":{"doNotUseIf":["Contract metadata is missing or unavailable for deterministic execution."],"safeUseWhen":[],"riskFlags":["missing_or_unavailable_contract","trust_data_unavailable","schema_references_missing"],"operationalConfidence":"low"},"executionMetrics":{"observedLatencyMsP50":null,"observedLatencyMsP95":null,"estimatedCostUsd":null,"uptime30d":null,"rateLimitRpm":null,"rateLimitBurst":null,"lastVerifiedAt":null,"verificationSource":null},"runtimeMetrics":{"successRate":null,"avgLatencyMs":null,"avgCostUsd":null,"hallucinationRate":null,"retryRate":null,"disputeRate":null,"p50Latency":null,"p95Latency":null,"lastUpdated":null}},"benchmarks":{"evidence":{"source":"no-benchmark-data","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No benchmark suites or observed failure patterns are available."},"suites":[],"failurePatterns":[]},"artifacts":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-10-09T15:08:30.490Z","emptyReason":null},"readme":"Skill: vmware-pilot\n\nOwner: zw008\n\nSummary: Use this skill whenever the user wants to design, execute, or manage complex multi-step VMware workflows with human approval gates and explicit, best-effort rollback. Pilot is the orchestration brain — it breaks a goal into steps across companion VMware skills (aiops, monitor, nsx, nsx-security, aria, vks, storage, avi), adds approval gates before destructive operations, and records per-step undo actions that run only when rollback is explicitly called, never automatically. Always use vmware-pilot for: \"clone and test before applying to production\", \"VMware incident response with checkpoints\", \"investigate alert root cause\", \"VMware rolling restart with health checks\", \"baseline capture and drift detection\", \"rolling maintenance with AVI drain\", or any VMware workflow needing approval gates or rollback. 15 built-in templates + custom YAML + AI-designed workflows. Do NOT use for single-step work — use vmware-aiops for one VM action, vmware-monitor for read-only queries, vmware-avi for load balancer queries.\n\nTags: latest:1.12.0\n\nVersion history:\n\nv1.12.0 | 2026-09-19T03:55:41.850Z | user\n\nDestructive MCP tools preview by default (confirm=False) and state their blast radius; confirm=True refuses on blockers or unreadable measurements. Requires vmware-policy>=1.17.0.\n\nv1.11.1 | 2026-09-15T06:05:58.115Z | user\n\nCLI reads are audited under their MCP tool names; every CLI command declares what it reaches (needs vmware-policy 1.15.0)\n\nv1.11.0 | 2026-09-15T03:13:30.366Z | user\n\ndesign catalog covers all thirteen companion skills\n\nv1.10.1 | 2026-09-14T15:12:46.659Z | user\n\ninvestigate_alert and compliance_scan now call registered tools with real parameters; template steps are checked against the companions' registries.\n\nv1.10.0 | 2026-09-12T07:53:19.320Z | user\n\nA step whose dispatch returns {\"error\": ...} or an isError result is now a failed step, on the forward and the rollback path — previously such a workflow reported completed and rollback then refused it. Found on a live vCenter.\n\nv1.9.0 | 2026-09-12T00:14:12.299Z | user\n\nBREAKING: a custom workflow whose destructive steps carry no approval gate is rejected instead of running with a warning, and patch_deployment requires an explicit username.\n\nv1.8.12 | 2026-08-31T00:35:46.615Z | user\n\nfix: run the suite on a non-UTF-8 machine, and stop one skill answering for another\n\nv1.8.11 | 2026-08-30T15:20:38.577Z | user\n\nSecond-round fixes from the 2026-08-30 VCF 9.1 re-test; vmware-policy floor raised to 1.11.0 (the engine no longer fails open when rules.yaml cannot be read).\n\nv1.8.10 | 2026-08-30T09:36:00.132Z | user\n\nParameter descriptions now reach the MCP JSON schema (0% -> 100% coverage); additionalProperties closed; vmware-policy floor raised to 1.10.0.\n\nv1.8.9 | 2026-08-28T02:56:21.210Z | user\n\nFixes the server's self-reported version and the advertised tool count; adds a Claude Code plugin manifest.\n\nv1.8.8 | 2026-08-01T03:12:12.142Z | user\n\nMoved to vmware-skills GitHub org; MCP Registry namespace → io.github.vmware-skills. Links updated.\n\nv1.8.7 | 2026-07-21T11:43:18.733Z | user\n\nRemove read-only switch and approval tiers; read/write authz delegated to RBAC. Plus accumulated fixes since 1.8.5.\n\nv1.8.5 | 2026-07-20T13:07:36.045Z | user\n\nA failure that is returned is now audited as a failure, and certificate/URL detail no longer reaches the agent. Both fixes v1.8.4 announced were incomplete.\n\nv1.8.4 | 2026-07-20T08:28:05.931Z | user\n\nTeaching error messages, domain exceptions no longer redacted on the way to the agent, and tool descriptions that state when to use each tool and what to call next.\n\nv1.8.3 | 2026-07-20T03:53:06.734Z | user\n\nFamily version alignment; the credential env-var override lands in the skills that have per-target credentials\n\nv1.8.2 | 2026-07-19T18:13:04.843Z | user\n\nMCP server moved into the package namespace — fixes two skills in one environment silently overwriting each other's server; agent-guardrails.md for local/small models now ships in every skill\n\nv1.8.1 | 2026-07-19T11:36:34.095Z | user\n\nRead-only mode now documented on every surface that teaches it (SKILL.md, setup-guide, capabilities)\n\nv1.8.0 | 2026-07-19T09:54:52.463Z | user\n\nRead-only mode (9 orchestration write tools withheld), declared environments; avi added to the design catalog (69 tools across 8 skills); new vmware-pilot CLI entry point\n\nv1.6.2 | 2026-06-24T00:37:50.040Z | user\n\nv1.6.2 MCP Registry registration (mcp-name marker)\n\nv1.6.1 | 2026-06-24T00:01:35.151Z | user\n\nv1.6.1 family version alignment\n\nv1.5.38 | 2026-06-12T06:59:52.321Z | user\n\nbacklog finish: cancel_workflow, templates split\n\nv1.5.37 | 2026-06-12T01:58:31.709Z | user\n\nbacklog: remove dead states\n\nv1.5.36 | 2026-06-11T23:22:01.232Z | user\n\nnever report work that wasn't performed\n\nv1.5.35 | 2026-06-10T00:44:23.788Z | user\n\nSecurity hardening: safe error handling, TLS/path/permission fixes\n\nv1.5.17 | 2026-05-01T11:47:20.822Z | user\n\nv1.5.17 - Pilot v2 architecture follow-ups: investigate_alert template (causal-chain root-cause workflow with 4-criteria checkpoint), review_workflow MCP tool (structural sanity check), parallel_group step type with group_id field, dispatch contract docs.\n\nv1.5.16 | 2026-05-01T03:31:32.299Z | user\n\nv1.5.16 - Enterprise Harness Engineering alignment: 5-level automation taxonomy (L1-L5) in capabilities.md, expert judgment encoded into Common Workflows pre-flight sections, causal-chain investigation protocol shared across aria/monitor/aiops, family version bump.\n\nv1.5.14 | 2026-04-21T12:20:59.320Z | user\n\nv1.5.14: code review fixes by @yjs-2026 + Snyk E005 disclaimer\n\nv1.5.3 | 2026-04-14T05:06:47.748Z | auto\n\nvmware-pilot 1.5.3\n\n- Documentation update only; no code or functional changes.\n- SKILL.md refreshed with existing workflows, scenarios, and companion skills.\n- No changes to installer, compatibility, or tool definitions.\n- Upgrade is optional for current users.\n\nv1.5.2 | 2026-04-14T00:46:02.797Z | auto\n\nvmware-pilot 1.5.2\n\n- Expanded compatibility section to clarify orchestration model (no direct vCenter/NSX credentials, no webhooks, no background services).\n- Added clearer description of state persistence, approval gates, and rollback behavior.\n- Explicitly listed transitive dependency (only vmware-policy) and reaffirmed no post-install scripts.\n- Updated compatibility notes to highlight that companion skills handle their own authentication.\n- No changes to workflow logic or APIs; documentation improvements only.\n\nv1.5.1 | 2026-04-13T00:11:10.152Z | auto\n\n- Added a disclaimer clarifying that this project is community-maintained, open-source, and not affiliated with or endorsed by VMware, Inc. or Broadcom Inc.\n- Mentioned the MIT license and linked the GitHub repository in the disclaimer.\n- No changes to features, templates, or technical functionality.\n\nv1.5.0 | 2026-04-12T04:57:16.144Z | user\n\nv1.5.0: Anthropic best practices, [READ]/[WRITE] prefixes, Broadcom attestation\n\nv1.4.10 | 2026-04-12T04:47:27.596Z | user\n\nAnthropic best practices: [READ]/[WRITE] prefixes, Broadcom author attestation\n\nv1.4.9 | 2026-04-11T13:32:48.148Z | user\n\nSecurity routing fixes and vmware-policy clarity; NSX auth fix for special char passwords\n\nv1.4.4 | 2026-04-01T15:49:26.005Z | user\n\nv1.4.4: vmware-avi family integration, cross-skill routing, sanitize coverage, safety tests\n\nArchive index:\n\nArchive v1.12.0: 13 files, 49167 bytes\n\nFiles: evals/evals.json (2117b), references/agent-guardrails.md (10100b), references/capabilities.md (10012b), references/cli-reference.md (6347b), references/integration-patterns.md (15415b), references/setup-guide.md (6940b), references/templates.md (23586b), references/workflow-design.md (14154b), scripts/list_available_tools.py (9098b), scripts/validate_workflow.py (6500b), skill-card.md (2821b), SKILL.md (20345b), _meta.json (132b)\n\nFile v1.12.0:SKILL.md\n\n---\nname: vmware-pilot\ndescription: >\n Use this skill whenever the user wants to design, execute, or manage complex multi-step VMware workflows with human approval gates and explicit, best-effort rollback.\n Pilot is the orchestration brain — it breaks a goal into steps across companion VMware skills (aiops, monitor, nsx, nsx-security, aria, vks, storage, avi), adds approval gates before destructive operations, and records per-step undo actions that run only when rollback is explicitly called, never automatically.\n Always use vmware-pilot for: \"clone and test before applying to production\", \"VMware incident response with checkpoints\", \"investigate alert root cause\", \"VMware rolling restart with health checks\", \"baseline capture and drift detection\", \"rolling maintenance with AVI drain\", or any VMware workflow needing approval gates or rollback.\n 15 built-in templates + custom YAML + AI-designed workflows.\n Do NOT use for single-step work — use vmware-aiops for one VM action, vmware-monitor for read-only queries, vmware-avi for load balancer queries.\ninstaller:\n kind: uv\n package: vmware-pilot\nallowed-tools: [Bash]\nmetadata: {\"openclaw\":{\"requires\":{\"anyBins\":[\"vmware-pilot\",\"uvx\"]},\"optional\":{\"env\":[\"VMWARE_AUDIT_APPROVED_BY\"]},\"homepage\":\"https://github.com/vmware-skills/VMware-Pilot\",\"emoji\":\"🧭\",\"os\":[\"macos\",\"linux\"]}}\ncompatibility: >\n vmware-policy auto-installed as Python dependency (provides @vmware_tool decorator and audit logging). All workflow operations audited to ~/.vmware/audit.db.\n No direct vCenter/NSX credentials: Pilot is an orchestration layer that delegates to companion skills (aiops, monitor, nsx, etc.) which handle their own auth.\n Approval gates: Workflows pause for human review before destructive steps; a custom workflow (YAML, create_workflow, or AI-designed) with a destructive or unclassifiable step not preceded by a gate is rejected, and force=True cannot override that. Rollback is never automatic: a failed step stops the workflow, and undo happens only when rollback is called; it is best-effort, and on the MCP server the calling agent performs each rollback_tool call itself.\n Pilot drives companion skills that change production (VM power, guest commands, network, storage, Kubernetes). Guest commands (vm_guest_exec, vm_guest_upload, …) and credential-returning steps (vks get_tkc_kubeconfig, get_supervisor_kubeconfig) are gated like destructive ones.\n State persistence: SQLite-backed workflow state (~/.vmware/workflows.db, owner-only 0600 in a 0700 directory) survives restarts; secret-named params are masked before they are written. No webhooks, no outbound network calls.\n Transitive dependencies: Only vmware-policy (audit/policy). No post-install scripts or background services.\n---\n\n# VMware Pilot\n\n> **Disclaimer**: This is a community-maintained open-source project and is **not affiliated with, endorsed by, or sponsored by VMware, Inc. or Broadcom Inc.** \"VMware\" is a trademark of Broadcom. Source code is publicly auditable at [github.com/vmware-skills/VMware-Pilot](https://github.com/vmware-skills/VMware-Pilot) under the MIT license.\n\nMulti-step workflow orchestration for VMware MCP skills — design, approve, execute, rollback.\n\n**Companion Skills**: [vmware-aiops](../vmware-aiops/SKILL.md) (VM operations) | [vmware-monitor](../vmware-monitor/SKILL.md) (monitoring) | [vmware-nsx](../vmware-nsx/SKILL.md) (networking) | [vmware-aria](../vmware-aria/SKILL.md) (metrics/alerts) | [vmware-avi](../vmware-avi/SKILL.md) (load balancing/AKO)\n\n## What This Skill Does\n\n| Capability | Description |\n|---|---|\n| Workflow Design | Natural language goal → AI designs steps from the `get_skill_catalog` building-block list (99 curated tools across 13 skills) |\n| Approval Gates | Pause execution for human review before destructive operations |\n| State Persistence | SQLite-backed, survives restarts, supports resume from checkpoint |\n| Rollback | Explicit, best-effort undo of completed steps in reverse order — never automatic (see Troubleshooting) |\n| Custom Templates | Save workflows as YAML for reuse, hot-reload without restart |\n| Compliance Scans | Read-only health/capacity/anomaly checks across skills |\n\n## Quick Install\n\n```bash\nuv tool install vmware-pilot==1.12.0\nvmware-pilot mcp # start the MCP server (stdio)\n```\n\n## When to Use This Skill\n\n| Scenario | Use Pilot? | Why |\n|---|---|---|\n| \"Clone VM, test, then apply to prod\" | Yes | Multi-step + approval |\n| \"Power on a VM\" | No, use aiops | Single operation |\n| \"Set up app network + firewall + VMs\" | Yes | Cross-skill orchestration |\n| \"Check cluster health\" | No, use monitor/aria | Single read-only query |\n| \"Diagnose and fix an alert\" | Yes | incident_response template |\n| \"Run compliance check\" | Yes | compliance_scan template |\n| \"Drain server, patch, restore traffic\" | Yes | Cross-skill: avi drain + aiops patch |\n| \"Deploy app with AKO ingress\" | Yes | Cross-skill: aiops + vks + avi |\n| \"Check pool member health\" | No, use avi | Single read-only query |\n\n## Related Skills — Skill Routing\n\n| User Intent | Recommended Skill |\n|---|---|\n| VM lifecycle (power, clone, deploy) | **vmware-aiops** (`uv tool install vmware-aiops`) |\n| Read-only monitoring | **vmware-monitor** (`uv tool install vmware-monitor`) |\n| NSX networking (segments, gateways, NAT) | **vmware-nsx** (`uv tool install vmware-nsx-mgmt`) |\n| NSX security (DFW, groups) | **vmware-nsx-security** (`uv tool install vmware-nsx-security`) |\n| Aria metrics/alerts/capacity | **vmware-aria** (`uv tool install vmware-aria`) |\n| Tanzu Kubernetes (Supervisor/TKC) | **vmware-vks** (`uv tool install vmware-vks`) |\n| Storage (iSCSI, vSAN, datastores) | **vmware-storage** (`uv tool install vmware-storage`) |\n| Load balancing, VS, pool, AKO | **vmware-avi** (`uv tool install vmware-avi`) |\n| Audit log query | **vmware-policy** (`vmware-audit` CLI) |\n| **Multi-step orchestration** | **vmware-pilot** (this skill) |\n\n## Common Workflows\n\n### 1. Design a Custom Workflow (Interactive)\n\n```\nUser: \"I need to set up a new app environment with networking and VMs\"\n\nAI calls: get_skill_catalog() → see available tools\nAI calls: design_workflow(goal=\"...\") → create draft\nAI calls: update_draft(id, steps=[...]) → fill in steps\nUser reviews and confirms\nAI calls: confirm_draft(id, save_as_template=True)\nAI calls: run_workflow(id) → execute with approval gates\n```\n\n### 2. Clone-and-Test (Built-in Template)\n\n```\nAI calls: plan_workflow(\"clone_and_test\", {\n target_vm: \"db01\",\n change_spec: {memory_mb: 32768},\n target: \"vcenter-prod\"\n})\nAI calls: run_workflow(workflow_id)\n→ Clone → Apply → Monitor → [Approval Gate] → Commit → Cleanup\n```\n\n### 3. Batch Operations with Approval\n\n```\nAI calls: plan_workflow(\"plan_and_approve\", {\n operations: [\n {action: \"power_off\", vm_name: \"db01\"},\n {action: \"revert_snapshot\", vm_name: \"db01\", snapshot_name: \"baseline\"},\n {action: \"power_on\", vm_name: \"db01\"}\n ]\n})\n→ Create Plan → [Approval Gate] → Execute Plan\n→ If the apply fails, nothing is undone automatically: ask the user, then call\n vmware-aiops vm_rollback_plan(plan_id) yourself\n```\n\n### 4. Rolling Maintenance with AVI Drain\n\nDrain traffic from a pool member via AVI, patch the server, then restore traffic:\n\n```\n1. vmware-avi pool disable # drain traffic from pool member\n2. vmware-avi analytics # verify drain complete (0 active connections)\n3. vmware-aiops vm guest-exec --cmd \"apt-get upgrade -y\" # patch the server\n4. vmware-avi pool enable # restore traffic to pool member\n5. vmware-avi pool members # verify health status is green\n```\n\n### 5. AKO-Aware Application Deployment\n\nDeploy a backend VM, create a K8s namespace, and wire up AKO Ingress to the AVI Controller:\n\n```\n1. vmware-aiops deploy ova --name # deploy backend VM\n2. vmware-vks namespace create # create K8s namespace\n3. kubectl apply -f ingress.yaml # create Ingress with AKO annotations\n4. vmware-avi ako ingress check # validate AKO annotations are correct\n5. vmware-avi ako sync status # verify VS created on AVI Controller\n```\n\n## Dispatch Contract (Important)\n\n**Pilot is a Dispatcher, not an Executor.** It generates plans, tracks state, gates on approvals — it does NOT call companion skills' MCP tools itself. The calling AI agent is responsible for invoking `vmware-aiops::vm_clone` etc. when pilot's `run_workflow` returns a step description.\n\nThis is intentional v2-style architecture: pilot's context stays small, state is always on disk, and there are no persistent agent threads. Full contract details: see [`references/integration-patterns.md`](references/integration-patterns.md#the-dispatch-contract).\n\n**`get_skill_catalog` is a curated design aid, not a whitelist.** It surfaces 99 hand-picked building blocks across 13 skills — a deliberate subset of what those skills expose (aiops alone has 60 tools; the catalog lists 19). A step's `skill` field is a free-form string handed to the calling agent, so a workflow may name any companion skill, including ones the catalog does not list — pilot itself (`pilot`) is used that way by built-in templates for approval gates. Use the catalog for inspiration; consult the target skill's own SKILL.md for its full tool surface.\n\n## MCP Tools (13 — 4 read, 9 write/control)\n\n| Category | Tool | Risk | Description |\n|---|---|---|---|\n| **Discovery** | `get_skill_catalog` | low | Available skills and tools for design |\n| | `list_workflows` | low | Built-in + custom templates |\n| **Design** | `design_workflow` | low | Natural language → draft |\n| | `update_draft` | medium | Edit draft steps |\n| | `confirm_draft` | medium | Finalize draft → ready to execute |\n| **Execute** | `plan_workflow` | medium | Create from template |\n| | `create_workflow` | medium | One-step custom creation (rejected if a destructive step has no gate before it) |\n| | `review_workflow` | low | Structural sanity check before execution (approved \\| needs_revision) |\n| | `run_workflow` | medium | Execute next checkpoint (agent dispatches each step) |\n| **Control** | `approve` | high | Human approval to continue |\n| | `cancel_workflow` | high | Cancel a workflow (approval rejected / unsafe) → terminal CANCELLED, can't be run. Previews unless `confirm=True` |\n| | `rollback` | high | Explicit, best-effort undo; never runs on its own. Previews unless `confirm=True` |\n\n**`rollback` and `cancel_workflow` preview by default.** Without `confirm=True` they return `blast_radius` (steps that would be undone, left applied, or skipped) and change nothing. Show it to the user; the user has not seen the preview yet, so do not set `confirm=True` on your own. They refuse when the state does not allow the transition, the record cannot be read, or a step was left `running`/`interrupted` (its effect is unknown: have the user check it in the target system, then pass `acknowledge_unknown_effects=True`).\n\n**Template steps pass `confirm=True`.** Destructive companion tools preview unless called with `confirm=True`; in every built-in template such a step comes after an `approve` gate, so it carries `confirm=True` — dispatch it as listed. A step that only returned `action: preview` is recorded `failed`, not `success`.\n| | `get_workflow_status` | low | State + audit log |\n\n## Built-in Templates (15)\n\nThe five most-used:\n\n| Template | Steps | Approval | Skills Used |\n|---|---|---|---|\n| `clone_and_test` | 6 (7 for a guest command) | Yes | aiops + monitor |\n| `incident_response` | 4 | Yes | monitor + aiops |\n| `investigate_alert` | 4 / 8 | Yes | monitor + aria (parallel-group gather + 4-criteria checkpoint, optional `deep_dive`) |\n| `plan_and_approve` | 3 | Yes | aiops |\n| `compliance_scan` | 3 | No | monitor + aria |\n\nFull list: `clone_and_test`, `incident_response`, `investigate_alert`, `plan_and_approve`, `compliance_scan`, `network_segment_setup`, `vks_cluster_deploy`, `rolling_restart`, `capacity_expansion`, `disaster_recovery`, `patch_deployment`, `storage_expansion`, `baseline_capture`, `baseline_audit`, `baseline_remediate`. See `references/templates.md` for full details.\n\n## Custom Templates\n\nDrop YAML files in `~/.vmware/workflows/` — pilot auto-loads them.\n\n**Approval gates are mandatory in custom workflows.** Every destructive step (the\nskill catalog marks it high/critical risk, or its name says delete/remove/…) and\nevery step pilot cannot classify must have a `require_approval` step somewhere\nbefore it. Otherwise `plan_workflow`, `create_workflow` and `confirm_draft` refuse\nthe workflow and name the offending steps, `run_workflow` refuses it even with\n`force=True`, and `scripts/validate_workflow.py` reports an error. Medium-risk\nwrites (`create_segment`, `vm_power_on`, …) do not require a gate.\n\n```yaml\n# ~/.vmware/workflows/restart_cluster.yaml\nname: restart_cluster\ndescription: Rolling restart of database cluster\nsteps:\n - action: check_health\n skill: monitor\n tool: get_alarms\n params:\n target: \"{{target}}\"\n - action: require_approval # required: the next step changes the estate\n skill: pilot\n tool: approve\n params:\n message: \"Cluster healthy. Stop replica {{replica_vm}}?\"\n - action: stop_replica\n skill: aiops\n tool: vm_power_off\n params:\n vm_name: \"{{replica_vm}}\"\n rollback_tool: vm_power_on\n rollback_params:\n vm_name: \"{{replica_vm}}\"\n - action: restart_primary\n skill: aiops\n tool: vm_power_off\n params:\n vm_name: \"{{primary_vm}}\"\n```\n\n## Usage Mode\n\n| Scenario | Recommended | Why |\n|----------|:-----------:|-----|\n| Local/small models (Ollama, Qwen) | **MCP** | Structured JSON I/O for multi-step state |\n| Cloud models (Claude, GPT-4o) | **MCP** | Design mode needs structured tool calls |\n| CI/CD pipeline orchestration | **MCP** | Programmatic plan/approve/run cycle |\n| Quick template listing | **MCP** | Call `list_workflows`; the CLI has no template commands |\n\n> Note: every workflow operation — design, plan, run, approve, rollback — is MCP-only.\n> The `vmware-pilot` CLI exists to launch the server and report its version, nothing more.\n> Other skills in the family (aiops, monitor, avi, etc.) offer full CLI and MCP modes.\n\n## CLI Quick Reference\n\nThe CLI is a launcher, not a second interface to workflows:\n\n```bash\nvmware-pilot mcp # start the MCP server (stdio)\nvmware-pilot version # print installed version\nvmware-pilot --help\n\n# Validate a custom workflow YAML before loading (runs pilot's own gate check,\n# so it needs the Python vmware-pilot is installed in)\n\"$(uv tool dir)/vmware-pilot/bin/python\" scripts/validate_workflow.py ~/.vmware/workflows/my_workflow.yaml\n\n# List available tools across all skills (design helper)\npython3 scripts/list_available_tools.py # all skills\npython3 scripts/list_available_tools.py aiops # specific skill\npython3 scripts/list_available_tools.py --json # JSON output\n\n# View audit logs (via vmware-policy)\nvmware-audit log --last 20\nvmware-audit log --status denied\n```\n\n> Full CLI reference for companion skills: see `references/cli-reference.md`\n\n## Troubleshooting\n\n### Workflow stuck in \"awaiting_approval\"\nCall `approve(workflow_id, approver=...)` with the correct workflow ID to continue, or `cancel_workflow(workflow_id)` if the approval is rejected (it previews first; call again with `confirm=True` once the user has seen it). If the MCP session was lost, reconnect and call `get_workflow_status(workflow_id)` to see the current state -- workflows persist in SQLite and survive restarts.\n\n### \"Unknown workflow type\" error from plan_workflow\nThe template name is case-sensitive. Use `list_workflows()` to see all available built-in and custom template names. Custom templates must be valid YAML in `~/.vmware/workflows/`.\n\n### Custom YAML template not appearing\n1. Verify the file is in `~/.vmware/workflows/` with a `.yaml` extension\n2. Check YAML syntax -- run `scripts/validate_workflow.py ` with pilot's Python (see CLI Quick Reference)\n3. A YAML file you drop in whose name matches a built-in replaces it (a warning is logged) -- rename it if that is not what you want. `create_workflow` and `confirm_draft` refuse to save a template under a built-in name\n4. A file that lists but will not plan is missing an approval gate -- the `plan_workflow` error names the step and the file\n\n### Rollback did nothing, or fails on some steps\nRollback never happens on its own: a failed step leaves the workflow `failed` and stops. A bare `rollback(workflow_id)` only previews; `confirm=True` acts. It only reverses steps pilot recorded as `success`, and on the MCP server (no dispatcher) the steps you performed from `pending_dispatch` stay `not_executed` — so `rollback` there reverses nothing but approval gates. Undo them yourself: call each performed step's `rollback_tool` with its `rollback_params`, last step first, after confirming with the user. Steps without a `rollback_tool` cannot be undone. When pilot does dispatch (an embedder supplied a dispatcher), rollback is best-effort: a failed undo does not stop the rest, and the result reports each one.\n\n### \"Workflow cannot be run\" state error\nA workflow can only be run from `pending` or `running` states. If it is in `draft`, call `confirm_draft()` first. If it is in `completed` or `failed`, create a new workflow -- completed workflows cannot be re-run.\n\n### vmware-policy dependency missing\nPilot requires `vmware-policy` for the `@vmware_tool` decorator and audit logging. It is declared as a dependency in `pyproject.toml` and should install automatically. If missing, run `pip install vmware-policy` or reinstall pilot.\n\n## Setup\n\nNo vCenter credentials needed — pilot orchestrates other skills that handle connections.\n\n```json\n{\n \"mcpServers\": {\n \"vmware-pilot\": {\n \"command\": \"vmware-pilot\",\n \"args\": [\"mcp\"]\n }\n }\n}\n```\n\n> Fallback: `{\"command\": \"uvx\", \"args\": [\"--from\", \"vmware-pilot==1.12.0\", \"vmware-pilot-mcp\"]}` also\n> works, but `uvx` re-resolves the package against PyPI on every start and fails behind a\n> TLS-inspecting corporate proxy (`invalid peer certificate: UnknownIssuer`). The installed\n> entry point above touches the network zero times; set `UV_NATIVE_TLS=true` if you must use `uvx`.\n\n## Audit & Safety\n\nAll operations are automatically audited via vmware-policy (`@vmware_tool` decorator):\n- Every tool call logged to `~/.vmware/audit.db` (SQLite, framework-agnostic)\n- Policy rules enforced via `~/.vmware/rules.yaml` (deny rules, maintenance windows, risk levels)\n- Risk classification: each tool tagged as low/medium/high/critical\n- Environment scoping: policy rules can scope by environment (an optional label an opt-in `deny` rule may match), and skills with a config may declare `environment:` per target. Pilot has no targets of its own and registers no environment resolver, so its own calls are unlabeled (they match no environment-scoped rule) — its writes go to the local workflow DB, never to a VMware estate. Pilot's approval gate is a step in its own workflow: it pauses before the agent dispatches a destructive step, and the target skill then applies its own policy rules when the step runs\n- View recent operations: `vmware-audit log --last 20`\n- View denied operations: `vmware-audit log --status denied`\n- Credential steps: `vks get_tkc_kubeconfig` and `get_supervisor_kubeconfig` return a live Supervisor token. Treat them as credential access, not read-only queries — never run one on your own initiative, keep it behind an approval gate (pilot gates both like a delete), write the kubeconfig to an owner-only file, and never print the token into chat or logs\n- Local data is sensitive: `~/.vmware/workflows.db` (pilot keeps `~/.vmware` 0700 and the DB 0600) holds step params and companion-skill results, with secret-named params masked. Pilot never writes `~/.vmware/baselines/`; a baseline the agent saves there is an inventory of VMs, hosts, network segments, datastores and alarms — keep it owner-only and out of chat\n\nvmware-policy is automatically installed as a dependency — no manual setup needed.\n\n## License\n\nMIT\n\nFile v1.12.0:_meta.json\n\n{\n \"ownerId\": \"kn7b067awq2s97bn3d7p5qfhw5827pxc\",\n \"slug\": \"vmware-pilot\",\n \"version\": \"1.12.0\",\n \"publishedAt\": 1789790141850\n}\n\nFile v1.12.0:references/agent-guardrails.md\n\n# Operating vmware-pilot with a local / small model\n\nClaude-class models drive this skill without special instruction. Smaller and\nlocally-hosted models — Llama 3.3 70B, Qwen, Mistral, and similar, served\nthrough Goose, Ollama, or OpenShift AI — need explicit operating rules to call\ntools reliably.\n\nThis page exists because an operator wrote those rules by hand first. The\nguardrails below are adapted, with thanks, from the working configuration\n[@juanpf-ha](https://github.com/juanpf-ha) developed while running\nvmware-monitor and vmware-aria against a production vSphere estate with Llama\n3.3 70B FP8 on an on-prem H100\n([VMware-AIops#31](https://github.com/vmware-skills/VMware-AIops/issues/31)). The\ncross-skill rules are identical across this family; the parts below marked\nvmware-pilot are specific to this skill.\n\nvmware-pilot is the odd one out. It manages no infrastructure of its own — it\ndesigns multi-step workflows, tracks their state, and gates them on human\napproval. Two consequences follow, and both matter more on a small model than\non a large one: **authoring a workflow is itself the write operation**, and\n**pilot does not execute anything** — the calling agent does.\n\n> **Disclaimer**: This is a community-maintained open-source project and is\n> **not affiliated with, endorsed by, or sponsored by VMware, Inc. or Broadcom\n> Inc.** \"VMware\" and \"vSphere\" are trademarks of Broadcom.\n\n---\n\n## First: the rules you no longer need to write\n\nSeveral guardrails from the original configuration are now enforced by the\nskill itself. Prompt instructions are advisory — a model can ignore them.\nThese are structural, so it cannot.\n\n| Guardrail you would otherwise prompt for | Now enforced by |\n|---|---|\n| \"Do not execute steps yourself — hand them back for a human to run\" | **The dispatch contract.** Pilot never calls a companion skill's MCP tools; it returns a step description and the calling agent invokes the tool. This is architecture, not etiquette. |\n| \"Check the plan makes sense before running it\" | **`review_workflow`** performs a structural sanity check and returns `approved` or `needs_revision`. It is a read tool that inspects a definition without executing it. |\n| \"Put an approval gate before anything destructive\" | **Custom-workflow rejection.** In a custom workflow (YAML, `create_workflow`, or a draft), a destructive or unclassifiable step — or any step passing `confirm: True` — with no `require_approval` before it makes `create_workflow` / `confirm_draft` / `plan_workflow` refuse to save it and `run_workflow` refuse to run it — `force=True` does not override that. The refusal names the step and the gate to insert. |\n| \"Log every state change you make\" | **The `@vmware_tool` decorator.** Every workflow transition is recorded to `~/.vmware/audit.db`, and `get_workflow_status` returns the state plus its audit log. |\n\nThe one guardrail this skill does not hand you: pilot's list tools return bare\ncollections, not the family `{items, returned, limit, total, truncated, hint}`\nenvelope. Truncation is not self-declaring here.\n\n---\n\n## The system prompt\n\nEverything below still benefits from being stated explicitly. Copy this into\nyour agent's instruction block.\n\n```text\n## Tool use\n\n- Always call an MCP tool before answering any question about workflow state.\n Never answer from memory or assumption.\n- Never describe a tool call, and never output a JSON example, instead of\n executing the tool. If you intend to call a tool, call it.\n- If a tool fails, report the actual error text. Do not complete the answer\n with assumptions about what the result would have been.\n- Use explicit limits on queries that may return large amounts of data. Do not\n request unlimited results unless the user asks for them.\n\n## Skill routing\n\n- vmware-pilot: multi-step workflows — design, plan, run, approve, roll back,\n cancel, and inspect state.\n- vmware-aiops: VM lifecycle. Pilot never calls it; you do, when pilot hands\n you a step.\n- vmware-monitor: read-only vCenter inventory, hosts, alarms, events.\n- vmware-nsx / vmware-nsx-security: networking and firewall.\n- vmware-storage, vmware-vks, vmware-aria, vmware-avi: their own domains.\n- A single-step request does not need a workflow. Call the skill directly.\n\n## The dispatch contract\n\n- Pilot is a dispatcher, not an executor. When run_workflow returns a step, YOU\n invoke that skill's MCP tool and report the result back. Pilot will not do it.\n- Never claim a step ran because pilot advanced its state. State advanced\n because you told pilot it did.\n- If you cannot invoke the tool a step names — it is not installed or is\n otherwise unavailable — say so and stop. Do not improvise a substitute.\n\n## Designing workflows\n\n- A step's tool must be a real tool on the named skill. get_skill_catalog is a\n curated design aid, not a whitelist: it lists a hand-picked subset, so a tool\n missing from the catalog may still exist. Confirm against the target skill's\n own SKILL.md before writing a step that names it.\n- Never invent a tool name to make a step read well. A workflow that names a\n tool which does not exist fails at run time, several steps in.\n- Order steps by dependency, not by narration. Gather state before changing it;\n put the approval gate before the first irreversible step, not after it.\n- Give every reversible step a rollback_tool and rollback_params. A step with\n no rollback cannot be undone by the rollback tool.\n- Nothing is ever rolled back automatically. After a failure, ask the user\n before undoing anything. On the MCP server the rollback tool cannot see the\n steps you performed (they stay not_executed), so undo them yourself: call each\n one's rollback_tool with its rollback_params, last step first.\n- get_tkc_kubeconfig and get_supervisor_kubeconfig return a live credential.\n Only fetch one when the user asks, write it to a file, and never print the\n token.\n- Run review_workflow before executing. Treat needs_revision as a stop.\n\n## Data fidelity\n\n- Never invent workflows, steps, templates, or state transitions. If a tool did\n not return it, it does not exist for this answer.\n- Preserve the exact workflow and step state values the tools return. Do not\n translate, normalise, or prettify them.\n- Report the steps in their defined order. Order is semantic in a workflow.\n- If a requested field was not returned, show it as \"not available\".\n- When a response is long, report every item it contains.\n\n## Analysis discipline\n\n- Separate observed data from interpretation. State which is which.\n- Do not claim a workflow succeeded, or that an estate is now in some state,\n on the basis of workflow state alone. Verify with the owning skill's read\n tools.\n- Avoid generic recommendations that are not directly supported by the results.\n```\n\n---\n\n## Known failure modes on small models\n\nObserved with Llama 3.3 70B FP8 (Goose, on-prem H100), and useful as a\nchecklist when evaluating any local model against these skills:\n\n| Symptom | Mitigation |\n|---|---|\n| Describes a tool call, or emits a JSON example, instead of executing it | The \"never describe a tool call\" rule above. Also check your harness is not echoing tool schemas into context — models imitate the nearest format they see. |\n| Long tool responses: omits items, or reports \"no data returned\" when data was present | Ask for explicit limits so responses stay small. Pilot's lists have no truncation envelope, so verify long results rather than trusting the summary. |\n| Adds generic recommendations unsupported by results | The \"analysis discipline\" rules. |\n| Drops requested fields or reorders results | State the required fields and ordering in the request itself. In a workflow, reordering the steps changes what the plan does. |\n| Multi-tool workflows take 30–50s end to end | Start from a built-in template with `plan_workflow` rather than designing from scratch; `get_workflow_status` returns state and audit log together. |\n\n### Workflow design failures — the pattern to watch here\n\nDesigning a plan is generative work, and it is where a small model's habits do\nthe most damage. These are specific to this skill:\n\n| Symptom | Mitigation |\n|---|---|\n| Writes a step naming a tool that does not exist — a plausible name assembled from the skill's naming pattern rather than its actual surface | The \"never invent a tool name\" rule. `get_skill_catalog` lists a curated subset, so absence from the catalog is not proof a tool is missing — and presence of a *plausible* name in the model's head is no proof it exists. Confirm against the target skill's SKILL.md. Nothing catches this until run time. |\n| Orders steps by narrative rather than dependency: changes state before gathering it, or verifies before acting | The \"order by dependency\" rule, then `review_workflow`. |\n| Places the approval gate after the irreversible step it was meant to guard | Refused structurally for destructive and unclassifiable steps (see the table above); for medium-risk writes, the \"order by dependency\" rule. State explicitly which step the gate protects. |\n| Omits `rollback_tool` on reversible steps, leaving nothing for `rollback` to undo | The rollback rule above. Add it while writing the step, not afterwards. |\n| Treats pilot's state machine as evidence the infrastructure changed | The dispatch contract. Pilot records what you told it; verify with the owning skill. |\n| Reports a step as done without having invoked the companion tool | Same. This is the dispatch contract's characteristic failure. |\n| Designs a workflow for something that is a single tool call | The routing rule. A workflow is overhead unless there is an approval gate or a real dependency chain. |\n\n## Reporting results\n\nLocal-model compatibility is an explicit design constraint for this family, and\nthe evidence base is small. If you evaluate a model against this skill —\nQwen, Mistral, Granite, or anything else — a report of what worked and what did\nnot is genuinely useful:\n[github.com/vmware-skills/VMware-Pilot/issues](https://github.com/vmware-skills/VMware-Pilot/issues).\n\nFile v1.12.0:references/capabilities.md\n\n# Capabilities — vmware-pilot\n\n## MCP Tools (13 — 4 read, 9 write)\n\n| # | Tool | Risk | Category | Description |\n|---|------|------|----------|-------------|\n| 1 | `get_skill_catalog` | low | Discovery | List all available skills and tools for workflow design |\n| 2 | `list_workflows` | low | Discovery | List built-in + custom templates and active workflows |\n| 3 | `design_workflow` | low | Design | Natural language goal → draft workflow for review |\n| 4 | `update_draft` | medium | Design | Edit draft workflow steps, name, or description |\n| 5 | `confirm_draft` | medium | Design | Finalize draft → state changes to PENDING |\n| 6 | `plan_workflow` | medium | Execute | Create workflow from built-in/custom template |\n| 7 | `create_workflow` | medium | Execute | Create custom workflow from step list (refused if a destructive step has no approval gate before it) |\n| 8 | `run_workflow` | medium | Execute | Execute workflow, pauses at approval gates |\n| 9 | `approve` | high | Control | Human approval to continue past approval gate |\n| 10 | `rollback` | high | Control | Explicit, best-effort undo of steps pilot recorded as succeeded, in reverse order — never automatic. Previews (`blast_radius`) unless `confirm=True` |\n| 11 | `get_workflow_status` | low | Control | Query workflow state, audit log, diff report |\n| 12 | `review_workflow` | low | Discovery | Sanity-check a planned workflow before anyone runs it |\n| 13 | `cancel_workflow` | high | Control | Cancel a workflow — moves it to the terminal CANCELLED state. Previews (`blast_radius`) unless `confirm=True` |\n\n---\n\n## Built-in Templates (15)\n\n| # | Template | Steps | Approval | Skills Used | Risk |\n|---|----------|-------|----------|-------------|------|\n| 1 | `clone_and_test` | 6-7 | Yes | aiops, monitor | Medium |\n| 2 | `incident_response` | 4 | Yes | monitor, aiops | Medium |\n| 3 | `plan_and_approve` | 3 | Yes | aiops | High |\n| 4 | `compliance_scan` | 1-3 | No | monitor, aria | Low |\n| 5 | `network_segment_setup` | 3-6 | Yes | nsx, nsx-security | Medium |\n| 6 | `vks_cluster_deploy` | 5 | Yes | vks | Medium |\n| 7 | `rolling_restart` | 2+3n | Yes | aiops, monitor | Medium |\n| 8 | `capacity_expansion` | 5 | Yes | aria, aiops, monitor | Medium |\n| 9 | `disaster_recovery` | 5 | Yes | aiops, monitor, nsx | High |\n| 10 | `patch_deployment` | 1+3n | Yes | aiops, monitor | Medium |\n| 11 | `storage_expansion` | 6 | Yes | storage | Medium |\n| 12 | `baseline_capture` | 1-5 | No | monitor, nsx, storage | Low |\n| 13 | `baseline_audit` | 1-5 | No | monitor, nsx, storage, aria | Low |\n| 14 | `baseline_remediate` | 3+n | Yes | varies | High |\n| 15 | `investigate_alert` | 4 (8 with `deep_dive`) | Checkpoint | monitor, aria | Low |\n\n---\n\n## Orchestrated Skills (13)\n\nPilot does not call VMware APIs directly. It delegates to these skills. Two different\nnumbers matter here, and they are not the same thing:\n\n- **Skill tools** — everything that skill exposes over MCP, all callable by the agent\n when it dispatches a step.\n- **In design catalog** — the hand-picked subset `get_skill_catalog` surfaces to the AI\n while it drafts a workflow. It is a curated starting point, not a whitelist: a step may\n name any skill, including ones absent from the catalog.\n\n| Skill | Package | Skill tools | In design catalog | Domain |\n|-------|---------|:-----------:|:-----------------:|--------|\n| vmware-aiops | `vmware-aiops` | 60 | 19 | VM lifecycle, deployment, guest ops, clusters |\n| vmware-monitor | `vmware-monitor` | 32 | 5 | Read-only inventory, alarms, events |\n| vmware-nsx | `vmware-nsx-mgmt` | 33 | 8 | NSX segments, gateways, NAT, routing, IPAM |\n| vmware-nsx-security | `vmware-nsx-security` | 22 | 7 | DFW policies/rules, security groups, traceflow |\n| vmware-aria | `vmware-aria` | 44 | 7 | Aria Ops metrics, alerts, capacity, anomalies |\n| vmware-vks | `vmware-vks` | 23 | 8 | Tanzu Supervisor, Namespaces, TKC clusters |\n| vmware-storage | `vmware-storage` | 14 | 5 | Datastores, iSCSI, vSAN, FC multipath |\n| vmware-avi | `vmware-avi` | 28 | 13 | AVI load balancing, pool members, AKO K8s ops |\n| vmware-debug | `vmware-debug` | 14 | 4 | Incident correlation, evidence-graded cases |\n| vmware-harden | `vmware-harden` | 8 | 5 | Compliance baselines, violations, drift |\n| vmware-log-insight | `vmware-log-insight` | 7 | 4 | Log search, aggregation, alerts |\n| vmware-privateai | `vmware-privateai` | 17 | 5 | GPU hosts, vGPU profiles, utilisation |\n| vmware-vdi | `vmware-vdi` | 27 | 9 | Horizon pools, sessions, machines, images |\n\n**Totals**: 329 tools across the 13 companion skills; the design catalog covers 99 of them\nacross all 13. Pilot adds 13 orchestration tools of its own. The counts are checked against\nthe companion snapshot by `tests/eval/regression/test_catalog_covers_the_family.py`.\n\n---\n\n## Workflow States\n\n```\nDRAFT -> PENDING -> RUNNING -> AWAITING_APPROVAL -> RUNNING -> COMPLETED\n | |\n +-> FAILED --(rollback)--> ROLLING_BACK |\n | |\n +-> BLOCKED_BY_POLICY |\n | |\n +-> MONITORING ---> COMMITTING ----------+\n```\n\n| State | Description |\n|-------|-------------|\n| `draft` | AI is designing steps (editable via update_draft) |\n| `pending` | Finalized, ready to execute via run_workflow |\n| `running` | Currently executing steps sequentially |\n| `awaiting_approval` | Paused at an approval gate |\n| `monitoring` | Watching for anomalies during test phase |\n| `committing` | Applying tested changes to production |\n| `rolling_back` | Undoing completed steps in reverse order |\n| `completed` | All steps finished successfully |\n| `failed` | A step failed (rollback may be available) |\n| `blocked_by_policy` | Blocked by vmware-policy rule |\n\n---\n\n## Key Features\n\n### Approval Gates\nPause execution for human review before destructive operations. Workflows can have multiple approval gates. Each gate requires an explicit `approve()` call to continue. In a custom workflow (YAML, `create_workflow`, or AI-designed) every destructive or unclassifiable step, and every step whose params tell its tool to act whatever its risk tier — `confirm` / `confirmed` truthy in any spelling (`True`, `1`, `\"yes\"`), or a legacy `dry_run` passed falsy — must have a gate before it: otherwise pilot refuses to save, confirm, plan or run it, and `force=True` does not override that.\n\n### Rollback (explicit, never automatic)\nA failed step stops the workflow; nothing is reversed until someone calls `rollback`. It undoes, last first, only steps pilot recorded as `success` — on the MCP server (no dispatcher) that is none of the steps the agent performed, so the agent calls each step's `rollback_tool` itself. Best-effort: if one undo fails, the rest still run. Steps without a `rollback_tool` cannot be undone.\n\n### Preview first: rollback and cancel_workflow\nBoth take `confirm: bool = False`. A bare call returns `{\"action\": \"preview\", \"blast_radius\": ...}` and changes nothing. `blast_radius` names the workflow (id, type, state), `state_after`, and — each as a count plus up to 16 steps — `would_roll_back` / `would_skip` (rollback entries carry each step's `rollback_tool` and `rollback_params`, secrets redacted), `left_in_place` (executed steps that stay applied: cancelling part-way leaves a half-applied change), `not_reversed_by_pilot` (rollback: steps the agent performed from `pending_dispatch`), `unknown_effects` (steps interrupted mid-dispatch), plus `blockers` and `unmeasured`. `confirm=True` refuses when either list is non-empty: a state the transition is not allowed from, a step status Pilot does not recognise, a workflow record that cannot be read, or a step in `unknown_effects` (left `running`/`interrupted` by a Pilot process that stopped mid-dispatch). For the last, the refusal says what to check; after the user has checked in the target system whether each such step took effect, re-run with `acknowledge_unknown_effects=True` (default `False`). That acknowledgement covers only those steps — it lifts no blocker and no other unmeasured item.\n\n### Companion tools that preview by default\nDestructive companion tools take `confirm: bool = False` and return `action: preview` on a bare call. Built-in template steps (and their `rollback_params`) pass `confirm=True`, because in every built-in template they come after an `approve` gate (a test enforces it). `rollback_params` with `confirm: True` in any workflow, built-in or custom, run on a `rollback(confirm=True)` call without an approval step of their own: `rollback` is itself gated, and that `confirm=True` is the human decision taken after its preview listed every rollback step's tool and parameters; they no longer pass the deprecated `confirmed` / `dry_run`. A step or rollback whose result is a top-level `action: preview` is recorded `failed` (\"step only previewed\"), never `success`. `baseline_remediate` adds `confirm=True` to caller-supplied drift items for those tools and refuses items that already carry `confirm`, `confirmed` or `dry_run`.\n\n### State Persistence\nAll workflow state is stored in SQLite at `~/.vmware/workflows.db` (WAL mode). Workflows survive MCP server restarts and can be resumed.\n\n### Custom Templates\nDrop YAML files in `~/.vmware/workflows/` for instant availability. Supports `{{variable}}` placeholders filled from params at runtime. Hot-reloaded without server restart.\n\n### Interactive Design Mode\n1. `design_workflow(goal)` creates a draft\n2. `update_draft(id, steps)` edits the draft\n3. `confirm_draft(id)` finalizes for execution\n4. `run_workflow(id)` executes with approval gates\n\n### Policy Integration\nAll operations audited via vmware-policy `@vmware_tool` decorator. Policy rules in `~/.vmware/rules.yaml` can deny operations based on maintenance windows, risk levels, or custom rules.\n\nFile v1.12.0:references/cli-reference.md\n\n# CLI Reference — vmware-pilot\n\nThe `vmware-pilot` CLI is a **launcher, not a second interface to workflows**. It starts the\nMCP server and reports its version — nothing else. Every workflow operation (design, plan,\nrun, approve, rollback, cancel) is performed via MCP tool calls through an AI agent or MCP\nclient.\n\n---\n\n## Commands\n\n| Command | Description |\n|---------|-------------|\n| `vmware-pilot mcp` | Start the MCP server on stdio transport |\n| `vmware-pilot version` | Print the installed version |\n| `vmware-pilot --help` | Show usage |\n\n## MCP Server Launch\n\n```bash\n# Recommended: installed entry point, never touches the network\nuv tool install vmware-pilot==1.12.0\nvmware-pilot mcp\n\n# Fallback: uvx re-resolves against PyPI each start and fails behind a\n# TLS-inspecting corporate proxy — set UV_NATIVE_TLS=true if you must use it\nuvx --from vmware-pilot==1.12.0 vmware-pilot-mcp\n```\n\nThe server runs on **stdio** transport and exposes 13 MCP tools (4 read, 9 write).\n\n---\n\n## MCP Tool Reference\n\n### Discovery Tools\n\n#### get_skill_catalog\n\nGet available skills and tools for workflow design.\n\n```\nget_skill_catalog()\n→ {aiops: {tools: {...}}, monitor: {...}, nsx: {...}, ...}\n```\n\n#### list_workflows\n\nList built-in and custom templates, plus active workflows.\n\n```\nlist_workflows()\n→ {templates: [...], active_workflows: [...]}\n```\n\n### Design Tools\n\n#### design_workflow\n\nCreate a draft workflow from natural language description.\n\n```\ndesign_workflow(\n goal=\"Migrate app01 to new network with firewall\",\n constraints=\"approval before destructive steps\"\n)\n→ {workflow_id: \"wf-...\", state: \"draft\", next_step: \"...\"}\n```\n\n#### update_draft\n\nEdit a draft workflow's name, description, or steps.\n\n```\nupdate_draft(\n workflow_id=\"wf-...\",\n name=\"app_migration\",\n steps=[{action: \"...\", skill: \"...\", tool: \"...\", params: {...}}]\n)\n→ {workflow_id: \"wf-...\", steps: [...]}\n```\n\n#### confirm_draft\n\nFinalize a draft workflow for execution (DRAFT -> PENDING).\n\n```\nconfirm_draft(\n workflow_id=\"wf-...\",\n save_as_template=True\n)\n→ {workflow_id: \"wf-...\", state: \"pending\"}\n```\n\n### Execution Tools\n\n#### plan_workflow\n\nCreate a workflow from a built-in or custom template.\n\n```\nplan_workflow(\n workflow_type=\"clone_and_test\",\n params={target_vm: \"db01\", change_spec: {memory_mb: 32768}}\n)\n→ {workflow_id: \"wf-...\", steps: [...]}\n```\n\nAvailable types: `clone_and_test`, `incident_response`, `plan_and_approve`, `compliance_scan`,\n`network_segment_setup`, `vks_cluster_deploy`, `rolling_restart`, `capacity_expansion`,\n`disaster_recovery`, `patch_deployment`, `storage_expansion`, `baseline_capture`,\n`baseline_audit`, `baseline_remediate`.\n\n#### create_workflow\n\nCreate a custom workflow directly from a step list. Refused — nothing saved —\nif any destructive or unclassifiable step has no `require_approval` step before\nit; the error names each step and the gate to insert.\n\n```\ncreate_workflow(\n name=\"quick_restart\",\n description=\"Restart with health check\",\n steps=[...],\n save_as_template=False\n)\n→ {workflow_id: \"wf-...\", steps: [...]}\n```\n\n#### run_workflow\n\nExecute a planned workflow. Pauses at approval gates.\n\n```\nrun_workflow(workflow_id=\"wf-...\")\n→ {state: \"awaiting_approval\", current_step: {...}}\n```\n\n### Control Tools\n\n#### approve\n\nHuman approval to continue past an approval gate.\n\n```\napprove(\n workflow_id=\"wf-...\",\n approver=\"admin@example.com\"\n)\n→ {state: \"running\", ...}\n```\n\n#### rollback\n\nExplicit, best-effort undo — never runs on its own. Reverses, last first, only\nthe steps pilot recorded as `success`; on the MCP server the steps you performed\nare `not_executed`, so undo them yourself with each step's `rollback_tool`.\n\n```\nrollback(workflow_id=\"wf-...\")\n→ {action: \"preview\", blast_radius: {would_roll_back: [...], left_in_place: [...], blockers: [], ...}}\n\nrollback(workflow_id=\"wf-...\", confirm=True) # after the user has seen the preview\n→ {action: \"rolled_back\", state: \"failed\", rollback_results: [...], blast_radius: {...}}\n```\n\n`cancel_workflow(workflow_id, reason, confirm=False)` works the same way: the\npreview lists the executed steps that stay applied and the steps that would be\nskipped; `confirm=True` cancels.\n\nBoth refuse `confirm=True` while a step is in `unknown_effects` (left `running`\nor `interrupted` when a Pilot process stopped mid-dispatch). Check in the target\nsystem whether that step took effect, then re-run with\n`acknowledge_unknown_effects=True`.\n\n#### get_workflow_status\n\nQuery workflow state, diff report, and audit log.\n\n```\nget_workflow_status(workflow_id=\"wf-...\")\n→ {state: \"completed\", steps: [...], audit_log: [...]}\n```\n\n---\n\n## Helper Scripts\n\n### validate_workflow.py\n\nValidate a custom YAML workflow template before use. It runs pilot's own\napproval-gate check, so use the Python vmware-pilot is installed in:\n\n```bash\n\"$(uv tool dir)/vmware-pilot/bin/python\" scripts/validate_workflow.py ~/.vmware/workflows/my_workflow.yaml\n```\n\nChecks:\n- Step structure has required fields\n- **Error** (exit 1): a destructive or unclassifiable step with no `require_approval` before it — `plan_workflow` would refuse the file\n- Warning: skills or tools not in the catalog\n\n### list_available_tools.py\n\nBrowse all available skills and tools for workflow design.\n\n```bash\npython3 scripts/list_available_tools.py # All skills\npython3 scripts/list_available_tools.py aiops # Specific skill\npython3 scripts/list_available_tools.py --json # JSON output\n```\n\n---\n\n## Audit Log (via vmware-policy)\n\n```bash\nvmware-audit log --last 20 # Recent operations\nvmware-audit log --status denied # Denied by policy\nvmware-audit log --tool approve # Filter by tool\n```\n\n---\n\n## Custom Workflow YAML Format\n\n```yaml\nname: my_workflow\ndescription: Human-readable description\nsteps:\n - action: check_health\n skill: monitor\n tool: get_alarms\n params:\n target: \"{{target}}\"\n\n - action: require_approval\n skill: pilot\n tool: approve\n params:\n message: \"Proceed with changes?\"\n\n - action: apply_change\n skill: aiops\n tool: vm_power_off\n params:\n vm_name: \"{{vm_name}}\"\n rollback_tool: vm_power_on\n rollback_params:\n vm_name: \"{{vm_name}}\"\n```\n\nPlace in `~/.vmware/workflows/` with `.yaml` extension. Hot-reloaded without restart.\n\nFile v1.12.0:references/integration-patterns.md\n\n# Cross-Skill Integration Patterns\n\nvmware-pilot orchestrates the VMware skill family into coherent workflows. Its\ndesign catalog (`get_skill_catalog`) offers 99 curated building blocks across 13\nskills; a dispatched step may name any companion skill, catalogued or not.\nThis reference documents the most common integration patterns and when to use\nPilot vs. calling a skill directly.\n\n---\n\n## The Dispatch Contract\n\nPilot is a **Dispatcher**, not an **Executor**. This is a deliberate v2-style architecture (per the Enterprise Harness Engineering framework — see `docs/architecture-audit-2026-04-30.md`).\n\nThe contract:\n\n1. **Pilot generates a plan** via `plan_workflow` or `design_workflow`. The plan is a sequence of `(skill, tool, params)` tuples plus approval gates and rollback metadata. State is persisted to SQLite.\n2. **Pilot tracks state** via `run_workflow`, `approve`, `rollback`. Each call returns immediately on the next checkpoint — running, awaiting approval, completed, or failed.\n3. **The calling AI agent dispatches each step**. After `run_workflow` returns a step description, the agent invokes the corresponding MCP tool on the target skill (e.g., `vmware-aiops::vm_clone`) and captures the result. Pilot has no call for reporting a step's result back, so on the MCP server those steps stay `not_executed` in pilot's record — which is why `rollback` there cannot undo them (see Error Handling).\n\nIn other words: pilot is the brain, the AI agent is the hands. Pilot never reaches across the wire to call other skills' tools itself — its `dispatch` function defaults to a no-op.\n\n### Why this matters\n\n- **Context isolation**: each step runs in the agent's main loop, not inside pilot. Pilot's context stays small (~100 lines/turn).\n- **No persistent agents**: there is no long-running pilot process that holds state in memory. State is always on disk.\n- **Approval gates as state, not blocking calls**: when a workflow hits `require_approval`, pilot persists the state and returns. Resumption is a new MCP call (`approve`), not an unblocking signal to a paused thread.\n- **Rollback is an explicit operation**: it never happens automatically — not on a failed step, not on agent crash or context loss. The user (or agent) must call `rollback` deliberately, and on the MCP server the agent performs the undo calls itself.\n\n### What this means for agents using pilot\n\n| Agent action | Correct pilot interaction |\n|---|---|\n| Start a multi-step task | Call `plan_workflow`; read returned plan; show to user |\n| Execute the plan | Call `run_workflow`; for each pending step in the response, invoke the named skill+tool yourself; report progress to the user |\n| Hit an approval gate | Tell the user; wait for explicit approval; call `approve` |\n| Encounter a failure | Surface the error; ask the user whether to undo; if yes, call each performed step's `rollback_tool` yourself, last first (pilot's `rollback` cannot see steps you performed) |\n| Need to know workflow state mid-execution | Call `get_workflow_status` (idempotent, safe) |\n\n### What this means for skill authors\n\nIf you add a new template to pilot, your template's steps must reference (`skill`, `tool`) pairs that already exist on companion skills. Pilot does no validation of tool existence at plan time — that's the agent's job at dispatch time. To help agents catch typos early, consider adding a `--validate` flag to template authoring tools.\n\n---\n\n## Pattern 1: Monitor -> Diagnose -> Fix\n\nDetect a problem, gather context, then remediate with approval.\n\n```\nmonitor.get_alarms -> Find active alarms\nmonitor.get_events -> Gather diagnostic context (last 1h, critical)\naria.list_anomalies -> Check for correlated anomalies\n [APPROVAL GATE] -> Human reviews diagnosis\naiops.acknowledge_vcenter_alarm -> Acknowledge/clear the alarm\nmonitor.get_alarms -> Verify alarm is resolved\n```\n\n**Built-in template**: `incident_response`\n\n**When to use**: An alert fires and you want structured triage before taking action.\nThe approval gate ensures no one auto-acknowledges a real issue.\n\n**Variations**:\n- Add `aria.list_rightsizing_recommendations` if the alarm is resource-related\n- Add `aiops.vm_power_off` / `vm_power_on` if restart is the remediation\n- Add `nsx-security.run_traceflow` if the alarm is network-related\n\n---\n\n## Pattern 2: Check -> Change -> Verify\n\nValidate capacity/health, make a change, confirm no regressions.\n\n```\naria.get_remaining_capacity -> Confirm capacity exists\naria.list_rightsizing_recommendations -> Validate change is reasonable\n [APPROVAL GATE] -> Human confirms the plan\naiops.vm_create_plan -> Create batch operation plan\naiops.vm_apply_plan -> Execute the plan\nmonitor.get_alarms -> Verify no new alarms\n```\n\n**Built-in templates**: `capacity_expansion`, `plan_and_approve`\n\n**When to use**: Any change to production VMs (resize, reconfigure, migrate).\nThe pre-check steps prevent expanding a VM when the cluster is already at capacity.\n\n**Variations**:\n- Replace `vm_create_plan` with direct `vm_power_on`/`vm_power_off` for simpler ops\n- Add `storage.vsan_capacity` if the change involves disk expansion\n- Chain with Pattern 4 (baseline) to detect drift after the change\n\n---\n\n## Pattern 3: Build -> Secure -> Deploy\n\nProvision infrastructure, apply security policies, then deploy workloads.\n\n```\nnsx.create_tier1_gateway -> Create network gateway\nnsx.create_segment -> Create network segment\nnsx-security.create_group -> Create security group for the segment\nnsx-security.create_dfw_policy -> Create firewall policy\nnsx-security.create_dfw_rule -> Add allow/deny rules\n [APPROVAL GATE] -> Human reviews network + security setup\naiops.batch_clone_vms -> Deploy VMs into the new segment\nmonitor.get_alarms -> Verify deployment health\n```\n\n**Built-in template**: `network_segment_setup` (networking portion)\n\n**When to use**: Setting up a new application environment from scratch.\nThis pattern ensures networking and security are in place before any VMs are deployed.\n\n**Variations**:\n- Add `vks.create_namespace` + `vks.create_tkc_cluster` instead of `batch_clone_vms` for Kubernetes workloads\n- Add `nsx.create_nat_rule` for outbound SNAT\n- Add `nsx-security.run_traceflow` as a post-deploy verification step\n\n---\n\n## Pattern 4: Capture -> Audit -> Remediate\n\nTake a snapshot of current state, compare later, fix any drift.\n\n```\nPhase 1 - Capture (run once, save as baseline):\n monitor.list_virtual_machines -> VM inventory + configs\n monitor.list_esxi_hosts -> Host inventory\n nsx.list_segments -> Network segments\n storage.list_all_datastores -> Storage state\n monitor.get_alarms -> Alarm state\n [Agent saves results to ~/.vmware/baselines/ — pilot does not;\n sensitive inventory, keep it owner-only (0700 dir / 0600 file)]\n\nPhase 2 - Audit (run periodically):\n monitor.list_virtual_machines -> Current VM state\n monitor.list_esxi_hosts -> Current host state\n nsx.list_segments -> Current network state\n storage.list_all_datastores -> Current storage state\n aria.list_anomalies -> Any new anomalies\n [Agent compares against the saved baseline -> drift report]\n\nPhase 3 - Remediate (if drift detected):\n monitor.get_alarms -> Pre-check\n [APPROVAL GATE] -> Human reviews drift items\n (skill).tool per drift item -> Fix each drift\n monitor.get_alarms -> Post-verify\n```\n\n**Built-in templates**: `baseline_capture`, `baseline_audit`, `baseline_remediate`\n\n**When to use**: Change management and compliance. Capture a baseline before\nmaintenance windows, audit after changes, remediate any unintended drift.\n\n**Variations**:\n- Add `aria.get_capacity_overview` to the capture for capacity baselines\n- Schedule `baseline_audit` as a daily or weekly automated check\n- Filter audit to specific resource types (VMs only, network only, etc.)\n\n---\n\n## Pattern 5: Clone -> Test -> Approve -> Commit\n\nSafe change deployment using a staging clone.\n\n```\naiops.deploy_linked_clone -> Clone production VM to staging\naiops.vm_reconfigure -> Apply changes to staging clone\nmonitor.get_alarms -> Monitor staging for issues\n [APPROVAL GATE] -> Human verifies staging is healthy\naiops.vm_reconfigure -> Apply same changes to production\naiops.vm_power_off -> Cleanup staging clone\n```\n\n**Built-in template**: `clone_and_test`\n\n**When to use**: High-risk configuration changes (memory resize, CPU change,\nsoftware upgrade) where you want to validate in staging first.\n\n**Key benefit**: If staging shows problems, you reject at the approval gate\nand production is never touched.\n\n---\n\n## Pattern 6: Rolling Operations\n\nApply changes to multiple VMs one at a time with health checks between each.\n\n```\nmonitor.get_alarms -> Pre-flight health check\n [APPROVAL GATE] -> Human confirms VM list\n\nFor each VM:\n aiops.vm_power_off -> Stop VM (graceful)\n aiops.vm_power_on -> Start VM\n monitor.get_alarms -> Verify health after restart\n [If alarms -> stop rolling; undo only if the user asks]\n```\n\n**Built-in templates**: `rolling_restart`, `patch_deployment`\n\n**When to use**: Any operation that must be applied to multiple VMs but cannot\nbe done simultaneously (database clusters, load-balanced web servers, etc.).\n\n**Key benefit**: If one VM fails the health check after restart, the workflow\nstops before touching remaining VMs. Nothing is undone automatically; the\nstep's `rollback_tool` (`vm_power_on`) is there for the agent to call if the\nuser wants the VM back on.\n\n---\n\n## Pattern 7: Kubernetes Lifecycle\n\nProvision a complete Tanzu Kubernetes environment.\n\n```\n [APPROVAL GATE] -> Human reviews namespace config\nvks.create_namespace -> Create Supervisor Namespace with storage policy\n [APPROVAL GATE] -> Human approves the TKC cluster\nvks.create_tkc_cluster -> Deploy TKC cluster\nvks.get_tkc_cluster -> Verify cluster is ready\n [APPROVAL GATE] -> get_tkc_kubeconfig returns a live credential\nvks.get_tkc_kubeconfig -> Write it to a file (0600); never print the token\n```\n\n**Built-in template**: `vks_cluster_deploy`\n\n**When to use**: Developer onboarding, new project environments, test cluster\nprovisioning.\n\n**Variations**:\n- Add `vks.scale_tkc_cluster` for day-2 scaling operations\n- Chain with Pattern 3 (Build -> Secure -> Deploy) for network-isolated clusters\n- Add `nsx-security.create_group` + `create_dfw_rule` for cluster network policies\n\n---\n\n## Pattern 8: Storage Lifecycle\n\nAdd or expand storage on ESXi hosts.\n\n```\nstorage.storage_iscsi_status -> Check current iSCSI state (read-only)\n [APPROVAL GATE] -> Human confirms adapter enable + storage target\nstorage.storage_iscsi_enable -> Enable adapter if needed\nstorage.storage_iscsi_add_target -> Add iSCSI target\nstorage.storage_rescan -> Rescan HBAs\nstorage.list_all_datastores -> Verify new datastores visible\n```\n\n**Built-in template**: `storage_expansion`\n\n**When to use**: Adding SAN/NAS storage to hosts, expanding storage pools.\n\n**Variations**:\n- Add `storage.vsan_health` + `storage.vsan_capacity` for vSAN operations\n- Chain with Pattern 2 for VM disk expansion after new storage is available\n\n---\n\n## When to Use Pilot vs. Direct Skill Call\n\n| Scenario | Direct Skill | Use Pilot | Why |\n|----------|:------------:|:---------:|-----|\n| Power on a single VM | aiops | -- | Single operation, no approval needed |\n| List active alarms | monitor | -- | Read-only query |\n| Check VM details | monitor | -- | Read-only query |\n| List network segments | nsx | -- | Read-only query |\n| Check capacity | aria | -- | Read-only query |\n| Get kubeconfig | vks | -- | Credential retrieval, not a read-only query: returns a live Supervisor session token. Run it only when the user asks, write it to an owner-only file (`output_path` on the MCP tool, `-o ` on the CLI), and never echo the token into chat or logs |\n| Clone, test, approve, apply | -- | pilot | Multi-step with approval gate |\n| Set up network + firewall + VMs | -- | pilot | Cross-skill orchestration |\n| Incident diagnosis + remediation | -- | pilot | Needs approval before action |\n| Rolling restart of 5 VMs | -- | pilot | Sequential with health checks |\n| Deploy patches to cluster | -- | pilot | Rolling deployment with verification |\n| Disaster recovery (snapshot revert) | -- | pilot | Destructive, needs approval |\n| Add iSCSI storage + rescan | -- | pilot | Multi-step with verification |\n| Baseline capture + audit | -- | pilot | Multi-skill data collection |\n| Batch power off 10 VMs | either | pilot preferred | Approval gate adds safety |\n\n### Rules of Thumb\n\n1. **Single read-only query** -> Call the skill directly (monitor, aria, nsx, storage, vks)\n2. **Single write operation on one resource** -> Call aiops directly (unless approval is required by policy)\n3. **Multiple steps across skills** -> Use Pilot\n4. **Destructive operation in production** -> Use Pilot (for the approval gate)\n5. **Same operation on multiple resources** -> Use Pilot (for rolling execution + health checks)\n6. **Need audit trail** -> Use Pilot (SQLite-persisted workflow log)\n\n---\n\n## Composing Patterns\n\nPatterns can be chained sequentially:\n\n```\n1. baseline_capture (Pattern 4, Phase 1) -> Save current state\n2. network_segment_setup (Pattern 3) -> Build new environment\n3. clone_and_test (Pattern 5) -> Test VM changes\n4. baseline_audit (Pattern 4, Phase 2) -> Verify no drift\n```\n\nThis gives you a complete change management lifecycle:\n- Capture state before changes\n- Build infrastructure\n- Test changes safely\n- Audit for unintended side effects\n\n---\n\n## Error Handling\n\nWhen a workflow step fails:\n\n1. The step is marked `failed` with the error message\n2. All remaining steps are marked `skipped`\n3. The workflow state becomes `FAILED`\n4. **Nothing is undone automatically.** Undo happens only when someone decides to\n roll back, and it is best-effort:\n - **MCP server (the normal case — no dispatcher):** the steps the agent\n performed are still `not_executed` in pilot's record, so `rollback()`\n reverses nothing but approval gates and just marks the workflow `failed`.\n The agent undoes the work itself: for each step it performed, last first,\n call that step's `rollback_tool` with its `rollback_params`, after the user\n agrees.\n - **Embedders that pass a dispatcher to `WorkflowExecutor`:** `rollback()`\n dispatches `rollback_tool` for each step pilot recorded as `success`, in\n reverse order. The failed step itself is not rolled back (it is `failed`,\n not `success`).\n5. Steps without a `rollback_tool` are skipped; they cannot be undone this way\n6. `rollback()` itself previews first: a bare call returns `blast_radius` and\n changes nothing; call it again with `confirm=True` after the user decides\n\nIf an undo call fails, the remaining ones still run; the result reports each one\nand sets `blocked_reason: rollback_failed`.\n\nFile v1.12.0:references/setup-guide.md\n\n# Setup Guide — vmware-pilot\n\n## Prerequisites\n\n- Python 3.10+\n- `vmware-policy` package (auto-installed as dependency)\n- At least one companion skill installed (aiops, monitor, nsx, etc.) for workflows to delegate to\n\n## Installation\n\n### Via uv (Recommended)\n\n```bash\nuv tool install vmware-pilot==1.12.0\n```\n\n### Via pip\n\n```bash\nuv tool install vmware-pilot==1.12.0\n\n# China mainland mirror\npip install vmware-pilot==1.12.0 -i https://pypi.tuna.tsinghua.edu.cn/simple\n```\n\n### Verify Installation\n\n```bash\n# Confirm the CLI is on PATH, then start the MCP server\nvmware-pilot version\nvmware-pilot mcp\n```\n\n---\n\n## MCP Configuration\n\n### Claude Code\n\nAdd to your Claude Code MCP config:\n\n```json\n{\n \"mcpServers\": {\n \"vmware-pilot\": {\n \"command\": \"vmware-pilot\",\n \"args\": [\"mcp\"]\n }\n }\n}\n```\n\n### Cursor / VS Code Copilot\n\n```json\n{\n \"mcpServers\": {\n \"vmware-pilot\": {\n \"command\": \"vmware-pilot\",\n \"args\": [\"mcp\"]\n }\n }\n}\n```\n\n### Goose\n\n```yaml\nextensions:\n vmware-pilot:\n name: vmware-pilot\n type: stdio\n cmd: vmware-pilot\n args:\n - mcp\n```\n\n### Fallback: launching through `uvx`\n\nThe `uvx` form still works and needs no prior install:\n\n```json\n{\n \"mcpServers\": {\n \"vmware-pilot\": {\n \"command\": \"uvx\",\n \"args\": [\"--from\", \"vmware-pilot==1.12.0\", \"vmware-pilot-mcp\"]\n }\n }\n}\n```\n\nPrefer the installed entry point above where you can. `uvx` re-resolves the package against\nPyPI on every start, so on a corporate network with a TLS-inspecting proxy it fails before the\nserver ever runs:\n\n```\ninvalid peer certificate: UnknownIssuer\n```\n\n`uv` ships its own certificate bundle and ignores the system trust store, which is what breaks.\nEither set `UV_NATIVE_TLS=true` so it honours your corporate CA, or install the tool once\n(`uv tool install vmware-pilot==1.12.0`) and launch `vmware-pilot mcp`, which touches the network\nzero times.\n\n---\n\n## Configuration\n\nPilot itself requires **no vCenter/NSX/AVI credentials**. It is a pure orchestrator that delegates all infrastructure calls to companion skills.\n\n### Workflow Database\n\nWorkflows are persisted to `~/.vmware/workflows.db` (SQLite, WAL mode). Created automatically on first use.\n\n### Custom Templates Directory\n\n```bash\nmkdir -p ~/.vmware/workflows\n```\n\nDrop YAML workflow templates here. Hot-reloaded without server restart.\n\n### Policy Rules (Optional)\n\nvmware-policy rules at `~/.vmware/rules.yaml` apply to all pilot operations:\n\n```yaml\n# Example: deny destructive operations outside maintenance window\nrules:\n - name: maintenance_window\n match:\n risk_level: [high, critical]\n deny_unless:\n time_range: \"02:00-06:00\"\n timezone: \"Asia/Shanghai\"\n```\n\n### Environment Scoping\n\nPolicy rules can scope by environment. Skills that connect to a VMware estate\nmay declare `environment:` (`production` / `staging` / `lab`) per target in\ntheir own `config.yaml` — an optional label an environment-scoped `deny` rule\nin `~/.vmware/rules.yaml` can match on (for example, to freeze writes on\n`production`). A target with no label is simply not matched by such a rule.\n\nvmware-pilot has no targets and needs no such declaration: it registers no\nenvironment resolver, so its own calls are unlabeled and match no\nenvironment-scoped rule. That is accurate rather than an exemption — pilot's own\nwrites land in `~/.vmware/workflows.db`, and its executor never calls VMware\nAPIs. When a workflow reaches an executable step, the MCP server records it as\n`not_executed` and returns `dispatch_required`; the calling agent then performs\nthat step through the target skill's own MCP tool, where that skill's own\npolicy rules apply. Pilot's approval gate is a step in its own workflow — it\npauses before the agent dispatches the step, so it is not skipped.\n\n### Audit Database\n\nAll tool calls are logged to `~/.vmware/audit.db` via vmware-policy. View with:\n\n```bash\nvmware-audit log --last 20\nvmware-audit log --status denied\n```\n\n---\n\n## Companion Skills Setup\n\nFor pilot to execute workflows, the relevant companion skills must be installed and configured:\n\n| Skill | Install | Config Location |\n|-------|---------|-----------------|\n| vmware-aiops | `uv tool install vmware-aiops` | `~/.vmware-aiops/config.yaml` |\n| vmware-monitor | `uv tool install vmware-monitor` | `~/.vmware-monitor/config.yaml` |\n| vmware-nsx | `uv tool install vmware-nsx-mgmt` | `~/.vmware-nsx/config.yaml` |\n| vmware-nsx-security | `uv tool install vmware-nsx-security` | `~/.vmware-nsx-security/config.yaml` |\n| vmware-aria | `uv tool install vmware-aria` | `~/.vmware-aria/config.yaml` |\n| vmware-vks | `uv tool install vmware-vks` | `~/.vmware-vks/config.yaml` |\n| vmware-storage | `uv tool install vmware-storage` | `~/.vmware-storage/config.yaml` |\n| vmware-avi | `uv tool install vmware-avi` | `~/.vmware-avi/config.yaml` |\n\nEach skill has its own `doctor` command to verify connectivity:\n\n```bash\nvmware-aiops doctor\nvmware-monitor doctor\nvmware-avi doctor\n# etc.\n```\n\n---\n\n## Security\n\n### Source Code\n\n[github.com/vmware-skills/VMware-Pilot](https://github.com/vmware-skills/VMware-Pilot) — MIT license.\n\n### Config File Contents\n\nPilot has no config file of its own. No credentials stored.\n\n### TLS Verification\n\nNot applicable to pilot directly. TLS settings are managed by each companion skill.\n\n### Prompt Injection Protection\n\nAll text from VMware/NSX/AVI APIs passes through `_sanitize()` in each companion skill (truncation to 500 chars + C0/C1 control character removal).\n\n### Least Privilege\n\nPilot itself needs no privileges. Each companion skill should use a service account with minimum required permissions.\n\n### Audit Trail\n\nEvery tool call is logged to `~/.vmware/audit.db` with timestamp, tool name, parameters, result, and risk level.\n\n---\n\n## AI Platform Compatibility\n\n| Platform | Transport | Status |\n|----------|-----------|--------|\n| Claude Code | stdio | Supported |\n| Cursor | stdio | Supported |\n| VS Code Copilot | stdio | Supported |\n| Goose | stdio | Supported |\n| Continue.dev | stdio | Supported |\n| Ollama (local) | stdio | Supported (MCP client required) |\n\n---\n\n## Troubleshooting\n\n### vmware-policy not found\n\n```bash\npip install vmware-policy\n# or\nuv pip install vmware-policy\n```\n\nvmware-policy is a declared dependency and should install automatically with pilot.\n\n### SQLite \"database is locked\"\n\nThe workflow database uses WAL mode for concurrent access. If you see lock errors, ensure only one MCP server instance is running, or increase the connection timeout.\n\n### Custom template YAML parse error\n\nValidate your template:\n\n```bash\n\"$(uv tool dir)/vmware-pilot/bin/python\" scripts/validate_workflow.py ~/.vmware/workflows/my_workflow.yaml\n```\n\nCommon issues: incorrect indentation, missing required fields (action, skill, tool, params), invalid YAML syntax, and a destructive step with no `require_approval` step before it (pilot refuses the file until one is added).\n\nFile v1.12.0:references/templates.md\n\n# Built-in Templates Reference\n\nvmware-pilot ships with 15 built-in workflow templates. Each template is a Python function\nthat generates a `Workflow` with pre-configured steps, approval gates, and rollback mappings.\n\nSteps (and rollback steps) that call a companion tool which previews by default pass\n`confirm=True`. In every built-in template such a step comes after an approval gate — Pilot's\n`approve`, which is the human decision; a test fails any template that sends `confirm=True`\nbefore its first gate. Read-only checks may come first.\n\n---\n\n## 1. clone_and_test\n\n**Purpose**: Clone a VM, apply changes in staging, monitor, then await approval before applying to production. The safest way to test changes.\n\n**Steps** (6 for a resize, 7 for a guest command):\n\n| # | Action | Skill | Tool | Rollback |\n|---|--------|-------|------|----------|\n| 0 | Clone VM to staging | aiops | `deploy_linked_clone` | `vm_power_off` (staging) |\n| (1) | **APPROVAL GATE** — guest command only: run it in staging? | pilot | `approve` | -- |\n| 1 | Apply changes to staging | aiops | `vm_reconfigure` or `vm_guest_exec` | -- |\n| 2 | Monitor staging health | monitor | `get_alarms` | -- |\n| 3 | **APPROVAL GATE** | pilot | `approve` | -- |\n| 4 | Apply changes to production | aiops | `vm_reconfigure` or `vm_guest_exec` | -- |\n| 5 | Power off staging VM | aiops | `vm_power_off` | -- |\n\nWith a guest command the extra gate comes first, so the later steps shift by\none. `vm_guest_exec` is destructive (vmware-aiops publishes it with\n`destructiveHint: true`), and the end-of-test gate would come after it had\nalready run in staging.\n\n**Parameters**:\n\n| Param | Type | Required | Description |\n|-------|------|----------|-------------|\n| `target_vm` | str | Yes | Production VM name to clone |\n| `change_spec` | dict | Yes | What to apply — see below |\n| `monitor_minutes` | int | No | How long to monitor staging (default: 5) |\n| `target` | str | No | vCenter target name |\n\n`change_spec` is one of two shapes, and anything the aiops tool would reject is\nrefused when the plan is made — before the staging clone exists:\n\n- **Resize** → aiops `vm_reconfigure`: `cpu` and/or `memory_mb`. `memory_gb` is\n accepted and converted to `memory_mb` (it must come out a whole number of MB;\n do not pass both). No other keys.\n- **Guest command** → aiops `vm_guest_exec`: `command` (full path of the\n program), `username` (**required** — the guest account to run as; there is no\n default, and pilot never assumes root), `password`, and optionally\n `arguments`, `working_directory`. No other keys.\n\n**Example**:\n```\nplan_workflow(\"clone_and_test\", {\n target_vm: \"db01\",\n change_spec: {memory_mb: 32768},\n target: \"vcenter-prod\"\n})\n\nplan_workflow(\"clone_and_test\", {\n target_vm: \"web01\",\n change_spec: {command: \"/usr/bin/apt-get\", arguments: \"-y upgrade\",\n username: \"ops\", password: \"...\"},\n target: \"vcenter-prod\"\n})\n```\n\n---\n\n## 2. incident_response\n\n**Purpose**: Auto-diagnose and remediate an alert with human approval before taking action.\n\n**Steps** (4):\n\n| # | Action | Skill | Tool | Rollback |\n|---|--------|-------|------|----------|\n| 0 | Get alarm details | monitor | `get_alarms` | -- |\n| 1 | Collect diagnostic events | monitor | `get_events` (critical, last 1h) | -- |\n| 2 | **APPROVAL GATE** | pilot | `approve` | -- |\n| 3 | Acknowledge alarm | aiops | `acknowledge_vcenter_alarm` | -- |\n\n**Parameters**:\n\n| Param | Type | Required | Description |\n|-------|------|----------|-------------|\n| `alert_entity` | str | Yes | Entity with the alert (VM/host name) |\n| `alert_name` | str | Yes | Name of the alert/alarm |\n| `target` | str | No | vCenter target name |\n\n**Example**:\n```\nplan_workflow(\"incident_response\", {\n alert_entity: \"esxi-host-03\",\n alert_name: \"Host memory usage\",\n target: \"vcenter-prod\"\n})\n```\n\n---\n\n## 3. plan_and_approve\n\n**Purpose**: Wrap aiops batch operations with an approval gate. Bridge between aiops's single-skill batch operations and pilot's approval-gated workflows.\n\n**Steps** (3):\n\n| # | Action | Skill | Tool | Rollback |\n|---|--------|-------|------|----------|\n| 0 | Create batch plan | aiops | `vm_create_plan` | -- |\n| 1 | **APPROVAL GATE** | pilot | `approve` | -- |\n| 2 | Apply batch plan | aiops | `vm_apply_plan` | `vm_rollback_plan` |\n\n**Parameters**:\n\n| Param | Type | Required | Description |\n|-------|------|----------|-------------|\n| `operations` | list[dict] | Yes | List of operations for vm_create_plan |\n| `target` | str | No | vCenter target name |\n| `description` | str | No | Human-readable description |\n\n**Supported operations**: `power_on`, `power_off`, `reset`, `clone`, `deploy_ova`, `deploy_template`, `linked_clone`, `create_snapshot`, `delete_snapshot`, `revert_snapshot`.\n\n**Example**:\n```\nplan_workflow(\"plan_and_approve\", {\n operations: [\n {action: \"power_off\", vm_name: \"db01\"},\n {action: \"revert_snapshot\", vm_name: \"db01\", snapshot_name: \"baseline\"},\n {action: \"power_on\", vm_name: \"db01\"}\n ],\n description: \"Revert db01 to baseline\"\n})\n```\n\n---\n\n## 4. compliance_scan\n\n**Purpose**: Periodic read-only health scan across monitor and aria. No approval gate needed (all steps are non-destructive).\n\n**Steps** (3, variable):\n\n| # | Action | Skill | Tool | Rollback |\n|---|--------|-------|------|----------|\n| 0 | Check active alarms | monitor | `get_alarms` | -- |\n| 1 | Check capacity | aria / monitor | `get_capacity_overview` (with `cluster_id`) / `cluster_health_summary` (without) | -- |\n| 2 | Check anomalies | aria | `list_anomalies` | -- |\n\nAria's `get_capacity_overview` requires a cluster id. Without one, the capacity step reads vmware-monitor's per-cluster CPU/memory rollup instead.\n\n**Parameters**:\n\n| Param | Type | Required | Description |\n|-------|------|----------|-------------|\n| `target` | str | No | vCenter/Aria target name |\n| `check_alarms` | bool | No | Include alarm check (default: True) |\n| `check_capacity` | bool | No | Include capacity check (default: True) |\n| `cluster_id` | str | No | Aria resource id of a cluster, for Aria's capacity overview |\n\n**Example**:\n```\nplan_workflow(\"compliance_scan\", {target: \"vcenter-prod\"})\n```\n\n---\n\n## 5. network_segment_setup\n\n**Purpose**: Set up a complete application network: Tier-1 gateway + overlay segment + NAT + DFW firewall policy, with approval before finalization.\n\n**Steps** (up to 6, depends on params):\n\n| # | Action | Skill | Tool | Rollback |\n|---|--------|-------|------|----------|\n| 0 | Create Tier-1 gateway (if tier1_id) | nsx | `create_tier1_gateway` | `delete_tier1_gateway` |\n| 1 | Create network segment | nsx | `create_segment` | `delete_segment` |\n| 2 | Create NAT rule (if nat_source) | nsx | `create_nat_rule` | `delete_nat_rule` |\n| 3 | Create DFW policy (if dfw_policy_id) | nsx-security | `create_dfw_policy` | `delete_dfw_policy` |\n| 4 | **APPROVAL GATE** | pilot | `approve` | -- |\n| 5 | Verify segments | nsx | `list_segments` | -- |\n\n**Parameters**:\n\n| Param | Type | Required | Description |\n|-------|------|----------|-------------|\n| `segment_id` | str | Yes | Segment identifier |\n| `display_name` | str | Yes | Human-readable segment name |\n| `subnet` | str | Yes | Subnet CIDR (e.g. \"10.10.1.0/24\") |\n| `transport_zone_path` | str | Yes | NSX transport zone path |\n| `tier1_id` | str | No | Tier-1 gateway ID (creates if provided) |\n| `tier0_path` | str | No | Tier-0 gateway path for uplink |\n| `nat_source` | str | No | NAT source network |\n| `nat_translated` | str | No | NAT translated network |\n| `dfw_policy_id` | str | No | DFW policy ID (creates if provided) |\n| `target` | str | No | NSX target name |\n\n**Example**:\n```\nplan_workflow(\"network_segment_setup\", {\n segment_id: \"app-frontend\",\n display_name: \"App Frontend Network\",\n subnet: \"10.10.1.0/24\",\n transport_zone_path: \"/infra/sites/default/enforcement-points/default/transport-zones/overlay-tz\",\n tier1_id: \"app-t1-gw\",\n tier0_path: \"/infra/tier-0s/t0-gateway\",\n dfw_policy_id: \"app-frontend-fw\"\n})\n```\n\n---\n\n## 6. vks_cluster_deploy\n\n**Purpose**: Deploy a complete VKS (vSphere with Tanzu) environment: create namespace, then deploy TKC cluster, each behind its own approval gate.\n\n**Steps** (5):\n\n| # | Action | Skill | Tool | Rollback |\n|---|--------|-------|------|----------|\n| 0 | **APPROVAL GATE** — create the namespace? | pilot | `approve` | -- |\n| 1 | Create vSphere Namespace | vks | `create_namespace` | `delete_namespace` |\n| 2 | **APPROVAL GATE** — deploy the TKC cluster? | pilot | `approve` | -- |\n| 3 | Create TKC cluster | vks | `create_tkc_cluster` | `delete_tkc_cluster` |\n| 4 | Verify cluster health | vks | `get_tkc_cluster` | -- |\n\n**Parameters**:\n\n| Param | Type | Required | Description |\n|-------|------|----------|-------------|\n| `namespace_name` | str | Yes | Namespace name |\n| `cluster_id` | str | Yes | vSphere cluster ID for the namespace |\n| `storage_policy` | str | Yes | Storage policy for the namespace |\n| `tkc_name` | str | Yes | TKC cluster name |\n| `k8s_version` | str | Yes | Kubernetes version (e.g. \"v1.28.3\") |\n| `vm_class` | str | No | VM class for workers (default: \"best-effort-medium\") |\n| `worker_count` | int | No | Number of workers (default: 3) |\n| `target` | str | No | vCenter target name |\n\n**Example**:\n```\nplan_workflow(\"vks_cluster_deploy\", {\n namespace_name: \"dev-team-a\",\n cluster_id: \"domain-c8\",\n storage_policy: \"vsan-default\",\n tkc_name: \"dev-cluster-01\",\n k8s_version: \"v1.28.3\",\n worker_count: 3\n})\n```\n\n---\n\n## 7. rolling_restart\n\n**Purpose**: Rolling restart of multiple VMs with health checks between each. Approval gate before starting.\n\n**Steps** (2 + 3 per VM):\n\n| # | Action | Skill | Tool | Rollback |\n|---|--------|-------|------|----------|\n| 0 | Pre-check health | monitor | `get_alarms` | -- |\n| 1 | **APPROVAL GATE** | pilot | `approve` | -- |\n| 2 | Power off VM_1 | aiops | `vm_power_off` | `vm_power_on` |\n| 3 | Power on VM_1 | aiops | `vm_power_on` | -- |\n| 4 | Health check VM_1 | monitor | `get_alarms` | -- |\n| ... | (repeat for each VM) | | | |\n\n**Parameters**:\n\n| Param | Type | Required | Description |\n|-------|------|----------|-------------|\n| `vm_names` | list[str] | Yes | List of VM names to restart |\n| `target` | str | No | vCenter target name |\n\n**Example**:\n```\nplan_workflow(\"rolling_restart\", {\n vm_names: [\"web01\", \"web02\", \"web03\"],\n target: \"vcenter-prod\"\n})\n```\n\n---\n\n## 8. capacity_expansion\n\n**Purpose**: Expand VM resources (CPU/memory) with capacity checks and rightsizing validation before applying.\n\n**Steps** (5):\n\n| # | Action | Skill | Tool | Rollback |\n|---|--------|-------|------|----------|\n| 0 | Check remaining capacity | aria | `get_remaining_capacity` | -- |\n| 1 | Check rightsizing recommendations | aria | `list_rightsizing_recommendations` | -- |\n| 2 | **APPROVAL GATE** | pilot | `approve` | -- |\n| 3 | Apply reconfiguration | aiops | `vm_create_plan` | -- |\n| 4 | Verify health | monitor | `get_alarms` | -- |\n\n**Parameters**:\n\n| Param | Type | Required | Description |\n|-------|------|----------|-------------|\n| `vm_name` | str | Yes | VM to expand |\n| `cpu` | int | No | New CPU count |\n| `memory_mb` | int | No | New memory in MB |\n| `target` | str | No | vCenter target name |\n\nAt least one of `cpu` or `memory_mb` must be provided.\n\n**Example**:\n```\nplan_workflow(\"capacity_expansion\", {\n vm_name: \"db01\",\n cpu: 8,\n memory_mb: 65536,\n target: \"vcenter-prod\"\n})\n```\n\n---\n\n## 9. disaster_recovery\n\n**Purpose**: Revert a VM to a known-good snapshot and verify full stack health (VM, network, alarms). Approval gate first since this is destructive.\n\n**Steps** (5):\n\n| # | Action | Skill | Tool | Rollback |\n|---|--------|-------|------|----------|\n| 0 | **APPROVAL GATE** | pilot | `approve` | -- |\n| 1 | Revert VM to snapshot | aiops | `vm_clean_slate` | -- |\n| 2 | Verify VM is running | monitor | `vm_info` | -- |\n| 3 | Verify network segments | nsx | `list_segments` | -- |\n| 4 | Verify health (no new alarms) | monitor | `get_alarms` | -- |\n\n**Parameters**:\n\n| Param | Type | Required | Description |\n|-------|------|----------|-------------|\n| `vm_name` | str | Yes | VM to recover |\n| `snapshot_name` | str | No | Snapshot to revert to (default: \"baseline\") |\n| `target` | str | No | vCenter target name |\n\n**Example**:\n```\nplan_workflow(\"disaster_recovery\", {\n vm_name: \"app-server-01\",\n snapshot_name: \"pre-upgrade\",\n target: \"vcenter-prod\"\n})\n```\n\n---\n\n## 10. patch_deployment\n\n**Purpose**: Rolling patch deployment: upload patch file, execute install, verify health -- one VM at a time. Approval gate before starting.\n\n**Steps** (1 + 3 per VM):\n\n| # | Action | Skill | Tool | Rollback |\n|---|--------|-------|------|----------|\n| 0 | **APPROVAL GATE** | pilot | `approve` | -- |\n| 1 | Upload patch to VM_1 | aiops | `vm_guest_upload` | -- |\n| 2 | Install patch on VM_1 | aiops | `vm_guest_exec_output` | -- |\n| 3 | Verify health VM_1 | monitor | `get_alarms` | -- |\n| ... | (repeat for each VM) | | | |\n\n**Parameters**:\n\n| Param | Type | Required | Description |\n|-------|------|----------|-------------|\n| `vm_names` | list[str] | Yes | VMs to patch |\n| `patch_local_path` | str | Yes | Local path to patch file |\n| `patch_guest_path` | str | Yes | Destination path inside guest OS |\n| `install_command` | str | Yes | Command to run after upload (e.g. \"rpm -Uvh /tmp/patch.rpm\") |\n| `username` | str | Yes | Guest OS account the upload and install run as. No default — vmware-aiops removed its root default, and pilot will not assume one |\n| `password` | str | No | Guest OS password |\n| `target` | str | No | vCenter target name |\n\n**Example**:\n```\nplan_workflow(\"patch_deployment\", {\n vm_names: [\"web01\", \"web02\"],\n patch_local_path: \"/tmp/security-patch-2026q1.rpm\",\n patch_guest_path: \"/tmp/security-patch-2026q1.rpm\",\n install_command: \"rpm -Uvh /tmp/security-patch-2026q1.rpm\",\n username: \"patchadmin\",\n password: \"...\",\n target: \"vcenter-prod\"\n})\n```\n\n---\n\n## 11. storage_expansion\n\n**Purpose**: Add iSCSI storage to a host: enable adapter, add target, rescan, verify new datastores.\n\n**Steps** (6):\n\n| # | Action | Skill | Tool | Rollback |\n|---|--------|-------|------|----------|\n| 0 | Check iSCSI status (read-only) | storage | `storage_iscsi_status` | -- |\n| 1 | **APPROVAL GATE** — enable the adapter and add the target? | pilot | `approve` | -- |\n| 2 | Enable iSCSI adapter | storage | `storage_iscsi_enable` | -- |\n| 3 | Add iSCSI target | storage | `storage_iscsi_add_target` | `storage_iscsi_remove_target` |\n| 4 | Rescan storage | storage | `storage_rescan` | -- |\n| 5 | Verify new datastores | storage | `list_all_datastores` | -- |\n\n**Parameters**:\n\n| Param | Type | Required | Description |\n|-------|------|----------|-------------|\n| `host_name` | str | Yes | ESXi host name |\n| `iscsi_address` | str | Yes | iSCSI target IP address |\n| `iscsi_port` | int | No | iSCSI port (default: 3260) |\n| `target` | str | No | vCenter target name |\n\n**Example**:\n```\nplan_workflow(\"storage_expansion\", {\n host_name: \"esxi-04\",\n iscsi_address: \"10.0.1.100\",\n iscsi_port: 3260,\n target: \"vcenter-prod\"\n})\n```\n\n---\n\n## 12. baseline_capture\n\n**Purpose**: Capture current infrastructure state as a JSON baseline snapshot. Used with `baseline_audit` and `baseline_remediate` for drift detection.\n\n**Steps** (up to 5, depends on params):\n\n| # | Action | Skill | Tool | Rollback |\n|---|--------|-------|------|----------|\n| 0 | Capture VM inventory | monitor | `list_virtual_machines` | -- |\n| 1 | Capture host inventory | monitor | `list_esxi_hosts` | -- |\n| 2 | Capture network segments | nsx | `list_segments` | -- |\n| 3 | Capture datastores | storage | `list_all_datastores` | -- |\n| 4 | Capture active alarms | monitor | `get_alarms` | -- |\n\nAll steps are read-only. No approval gate.\n\n**Parameters**:\n\n| Param | Type | Required | Description |\n|-------|------|----------|-------------|\n| `target` | str | No | vCenter target name |\n| `include_vms` | bool | No | Capture VMs (default: True) |\n| `include_hosts` | bool | No | Capture hosts (default: True) |\n| `include_network` | bool | No | Capture NSX segments (default: True) |\n| `include_storage` | bool | No | Capture datastores (default: True) |\n| `include_alarms` | bool | No | Capture alarms (default: True) |\n| `baseline_name` | str | No | Name for baseline (default: auto-generated timestamp) |\n\n**Pilot does not write the baseline file.** The plan carries a suggested\n`baseline_path` (`~/.vmware/baselines/{name}.json`); the calling agent saves the\ncollected step results there if you want to keep them. **That file is sensitive**:\nit is an inventory of your VMs, ESXi hosts, NSX segments, datastores and active\nalarms — the map an attacker would want. Keep it owner-only (`chmod 700\n~/.vmware/baselines`, `chmod 600` each file), do not paste it into chat, tickets\nor shared drives, and delete baselines you no longer need.\n\n**Example**:\n```\nplan_workflow(\"baseline_capture\", {\n target: \"vcenter-prod\",\n baseline_name: \"pre-maintenance-2026q1\"\n})\n```\n\n---\n\n## 13. baseline_audit\n\n**Purpose**: Compare current infrastructure state against a saved baseline to detect configuration drift.\nPilot collects the current state; the calling agent does the comparison against\nthe file it saved (pilot does not read it, and `diff_report` stays empty).\n\n**Steps** (up to 5):\n\n| # | Action | Skill | Tool | Rollback |\n|---|--------|-------|------|----------|\n| 0 | Current VM inventory | monitor | `list_virtual_machines` | -- |\n| 1 | Current host inventory | monitor | `list_esxi_hosts` | -- |\n| 2 | Current network segments | nsx | `list_segments` | -- |\n| 3 | Current datastores | storage | `list_all_datastores` | -- |\n| 4 | Check anomalies | aria | `list_anomalies` | -- |\n\nAll steps are read-only. No approval gate.\n\n**Parameters**:\n\n| Param | Type | Required | Description |\n|-------|------|----------|-------------|\n| `baseline_name` | str | No | Baseline to compare against (default: \"latest\") |\n| `target` | str | No | vCenter target name |\n| `include_vms` | bool | No | Audit VMs (default: True) |\n| `include_hosts` | bool | No | Audit hosts (default: True) |\n| `include_network` | bool | No | Audit NSX (default: True) |\n| `include_storage` | bool | No | Audit storage (default: True) |\n\n**Example**:\n```\nplan_workflow(\"baseline_audit\", {\n baseline_name: \"pre-maintenance-2026q1\",\n target: \"vcenter-prod\"\n})\n```\n\n---\n\n## 14. baseline_remediate\n\n**Purpose**: Fix configuration drifts detected by `baseline_audit`. Takes drift items and generates remediation steps with approval.\n\n**Steps** (2 + N drift items + 1):\n\n| # | Action | Skill | Tool | Rollback |\n|---|--------|-------|------|----------|\n| 0 | Pre-check alarms | monitor | `get_alarms` | -- |\n| 1 | **APPROVAL GATE** | pilot | `approve` | -- |\n| 2..N+1 | Fix drift item | (varies) | (varies) | (varies) |\n| N+2 | Post-verify health | monitor | `get_alarms` | -- |\n\n**Parameters**:\n\n| Param | Type | Required | Description |\n|-------|------|----------|-------------|\n| `drift_items` | list[dict] | Yes | List of drift items from audit results |\n| `target` | str | No | vCenter target name |\n\nEach drift item dict:\n\n| Field | Type | Required | Description |\n|-------|------|----------|-------------|\n| `action` | str | Yes | Remediation action name |\n| `skill` | str | Yes | Skill to use |\n| `tool` | str | Yes | Tool to call |\n| `params` | dict | Yes | Tool parameters |\n| `resource` | str | No | Resource name (for logging) |\n| `rollback_tool` | str | No | Undo tool |\n| `rollback_params` | dict | No | Undo parameters |\n\n**Example**:\n```\nplan_workflow(\"baseline_remediate\", {\n drift_items: [\n {\n resource: \"web01\",\n action: \"fix_cpu\",\n skill: \"aiops\",\n tool: \"vm_create_plan\",\n params: {operations: [{action: \"reconfigure\", vm_name: \"web01\", cpu: 4}]},\n },\n {\n resource: \"app-segment\",\n action: \"recreate_segment\",\n skill: \"nsx\",\n tool: \"create_segment\",\n params: {segment_id: \"app-segment\", display_name: \"App Segment\", ...},\n rollback_tool: \"delete_segment\",\n rollback_params: {segment_id: \"app-segment\"},\n }\n ],\n target: \"vcenter-prod\"\n})\n```\n\n---\n\n## 15. investigate_alert\n\n**Purpose**: Causal-chain root-cause investigation of an alert. Gathers evidence in parallel, then stops at a checkpoint where the agent applies the four criteria (falsifiability, sufficiency, necessity, mechanism) from `investigation-protocol.md`. All gathering steps are reads; the approvals are synthesis checkpoints, not permission for a change.\n\n**Steps** (4, or 8 with `deep_dive`):\n\n| # | Action | Skill | Tool | Parallel group |\n|---|--------|-------|------|----------------|\n| 0 | Gather active alarms | monitor | `get_alarms` | round1-gather |\n| 1 | Gather events, last 2 h | monitor | `get_events` (`hours: 2`) | round1-gather |\n| 2 | Gather active Aria alerts | aria | `list_alerts` (`active_only: true`) | round1-gather |\n| 3 | **CHECKPOINT** — four criteria | pilot | `approve` | -- |\n| 4 | Gather anomalies | aria | `list_anomalies` | round2-gather |\n| 5 | Gather per-cluster capacity | monitor | `cluster_health_summary` | round2-gather |\n| 6 | Gather Aria alerts incl. cancelled | aria | `list_alerts` (`active_only: false`) | round2-gather |\n| 7 | **CHECKPOINT** — four criteria again | pilot | `approve` | -- |\n\nSteps 4–7 exist only with `deep_dive: true`. None of these tools filters by object, so keep the rows that concern `alert_entity` — alarms and alerts carry the object's name. The checkpoint message says so.\n\n**Parameters**:\n\n| Param | Type | Required | Description |\n|-------|------|----------|-------------|\n| `alert_entity` | str | Yes | Object the alert is on (VM, host, cluster) |\n| `alert_name` | str | No | Alert label shown in the checkpoint messages |\n| `deep_dive` | bool | No | Add the second gathering round and checkpoint (default: False) |\n| `target` | str | No | vCenter target for the monitor steps; also the Aria target unless `aria_target` is set |\n| `aria_target` | str | No | Aria target for the aria steps, when it is named differently from the vCenter one |\n\n**Example**:\n```\nplan_workflow(\"investigate_alert\", {\n alert_entity: \"192.168.60.15\",\n alert_name: \"Host connection and power state\",\n target: \"home-vcenter\",\n aria_target: \"home-aria\",\n deep_dive: true\n})\n```\n\n---\n\n## Template Summary\n\n| Template | Steps | Approval | Skills Used | Risk Level |\n|----------|-------|----------|-------------|------------|\n| `clone_and_test` | 6-7 | Yes | aiops, monitor | Medium |\n| `incident_response` | 4 | Yes | monitor, aiops | Medium |\n| `plan_and_approve` | 3 | Yes | aiops | High |\n| `compliance_scan` | 1-3 | No | monitor, aria | Low |\n| `network_segment_setup` | 3-6 | Yes | nsx, nsx-security | Medium |\n| `vks_cluster_deploy` | 5 | Yes | vks | Medium |\n| `rolling_restart` | 2+3n | Yes | aiops, monitor | Medium |\n| `capacity_expansion` | 5 | Yes | aria, aiops, monitor | Medium |\n| `disaster_recovery` | 5 | Yes | aiops, monitor, nsx | High |\n| `patch_deployment` | 1+3n | Yes | aiops, monitor | Medium |\n| `storage_expansion` | 6 | Yes | storage | Medium |\n| `baseline_capture` | 1-5 | No | monitor, nsx, storage | Low |\n| `baseline_audit` | 1-5 | No | monitor, nsx, storage, aria | Low |\n| `baseline_remediate` | 3+n | Yes | varies | High |\n| `investigate_alert` | 4 (8 with `deep_dive`) | Yes (synthesis checkpoints) | monitor, aria | Low |\n\nFile v1.12.0:references/workflow-design.md\n\n# Workflow Design Guide\n\n## Core Concept: Pilot Breaks Down Goals into Multi-Skill Steps\n\nWhen a user describes a goal, Pilot automatically:\n\n1. **Identifies which skills are needed** (aiops, monitor, nsx, nsx-security, aria, vks, storage)\n2. **Determines the correct step sequence** (pre-check -> action -> verify)\n3. **Inserts approval gates** before destructive operations\n4. **Adds rollback mappings** for reversible steps\n5. **Persists state** so workflows survive restarts (SQLite-backed)\n\n---\n\n## Example: \"Expand database cluster capacity\"\n\n### Without Pilot (user must orchestrate manually)\n\nThe user must know which skill has the right tool, call them in order, and remember to verify:\n\n```\nUser calls aria -> get_remaining_capacity (must know aria has this)\nUser calls aria -> list_rightsizing_recommendations (must remember to check)\nUser calls monitor -> get_alarms (must remember to verify no active issues)\nUser calls aiops -> vm_create_plan (must know parameters)\nUser calls aiops -> vm_apply_plan (must remember to apply)\nUser calls monitor -> get_alarms (must verify no new alarms)\n```\n\nIf anything fails, the user must manually figure out rollback.\n\n### With Pilot (user just states the goal)\n\n```\nUser: \"Expand db01 to 32GB RAM\"\n\nPilot creates workflow:\n Step 0: aria.get_remaining_capacity -> check if capacity exists\n Step 1: aria.list_rightsizing -> validate against recommendations\n Step 2: [APPROVAL GATE] -> user reviews and confirms\n Step 3: aiops.vm_create_plan -> create the change plan\n Step 4: monitor.get_alarms -> verify health after change\n\nUser reviews steps, approves at gate, Pilot completes execution.\nOn failure at Step 3 the workflow stops as `failed`; nothing is undone until\nsomeone calls `rollback` (explicit, best-effort — see Error Handling in\nintegration-patterns.md).\n```\n\n---\n\n## Workflow Step Structure\n\nEach step in a workflow has these fields:\n\n| Field | Type | Required | Description |\n|-------|------|----------|-------------|\n| `index` | int | Yes | Step position (0-based) |\n| `action` | str | Yes | Human-readable name (e.g. \"check_health\", \"clone_vm\") |\n| `skill` | str | Yes | Which VMware skill to invoke |\n| `tool` | str | Yes | The specific MCP tool within that skill |\n| `params` | dict | Yes | Tool parameters (passed directly to MCP tool) |\n| `rollback_tool` | str | No | Tool to call if we need to undo this step |\n| `rollback_params` | dict | No | Parameters for the rollback tool |\n| `status` | str | Auto | pending / running / success / failed / skipped / rolled_back |\n\n### Special step: Approval Gate\n\n```yaml\n- action: require_approval\n skill: pilot\n tool: approve\n params:\n message: \"Changes ready. Proceed with production deployment?\"\n```\n\nWhen the executor reaches an approval gate, it pauses the workflow and waits for\nthe user to call `approve(workflow_id)`. This is the mechanism that makes Pilot\nsafe for destructive operations.\n\n---\n\n## Available Skills and Key Tools\n\nThe **Risk** column is pilot's skill catalog (`get_skill_catalog`), which is what\nthe approval-gate check reads: a `high` step, a step whose name says\ndelete/remove/destroy/shutdown/drop/rollback/force_power_off, or a step whose\ntool is not in the catalog must have a `require_approval` step before it in a\ncustom workflow, or pilot refuses the workflow. `medium` writes need no gate.\n\n### aiops (VM Lifecycle and Operations)\n\n| Tool | Risk | Use For |\n|------|------|---------|\n| `vm_power_on` | medium | Start a VM |\n| `vm_power_off` | high | Stop a VM (graceful or force) |\n| `deploy_linked_clone` | medium | Clone a VM from snapshot |\n| `vm_create_plan` | medium | Create a batch operation plan |\n| `vm_apply_plan` | medium | Execute a planned batch |\n| `vm_rollback_plan` | medium | Undo a batch operation |\n| `vm_guest_exec` | high | Run command inside guest OS — as the account you name; gate it |\n| `vm_guest_exec_output` | high | Run command and capture output |\n| `vm_guest_upload` | high | Upload file to guest OS |\n| `vm_guest_provision` | high | Bootstrap a new VM |\n| `batch_clone_vms` | medium | Clone multiple VMs at once |\n| `vm_clean_slate` | high | Revert VM to snapshot |\n| `acknowledge_vcenter_alarm` | medium | Acknowledge an alarm |\n| `reset_vcenter_alarm` | medium | Reset an alarm |\n| `cluster_create` | medium | Create a new cluster |\n| `deploy_vm_from_ova` | medium | Deploy from OVA |\n| `deploy_vm_from_template` | medium | Deploy from template |\n\n### monitor (Read-Only Monitoring)\n\n| Tool | Risk | Use For |\n|------|------|---------|\n| `list_virtual_machines` | low | Inventory all VMs |\n| `list_esxi_hosts` | low | Inventory all hosts |\n| `list_all_datastores` | low | Inventory all datastores |\n| `list_all_clusters` | low | Inventory all clusters |\n| `get_alarms` | low | Check active alarms |\n| `get_events` | low | Check recent events |\n| `vm_info` | low | Detailed VM information |\n\n### nsx (Networking)\n\n| Tool | Risk | Use For |\n|------|------|---------|\n| `list_segments` | low | List network segments |\n| `create_segment` | medium | Create overlay/VLAN segment |\n| `delete_segment` | high | Remove a segment |\n| `create_tier1_gateway` | medium | Create Tier-1 gateway |\n| `create_nat_rule` | medium | Add NAT rule |\n| `list_nat_rules` | low | List NAT rules |\n\n### nsx-security (Firewall and Microsegmentation)\n\n| Tool | Risk | Use For |\n|------|------|---------|\n| `list_dfw_policies` | low | List DFW policies |\n| `create_dfw_policy` | medium | Create firewall policy |\n| `create_dfw_rule` | medium | Add firewall rule |\n| `delete_dfw_rule` | high | Remove firewall rule |\n| `create_group` | medium | Create security group |\n| `run_traceflow` | medium | Trace packet path |\n\n### aria (Metrics, Alerts, Capacity)\n\n| Tool | Risk | Use For |\n|------|------|---------|\n| `list_alerts` | low | List active alerts |\n| `acknowledge_alert` | medium | Acknowledge an alert |\n| `get_capacity_overview` | low | Overall capacity summary |\n| `get_remaining_capacity` | low | Time/resource remaining |\n| `get_time_remaining` | low | Days until capacity exhaustion |\n| `list_anomalies` | low | Detected anomalies |\n| `list_rightsizing_recommendations` | low | VM rightsizing suggestions |\n| `generate_report` | not in catalog | Generate capacity report (unclassified, so it needs a gate before it) |\n\n### vks (Tanzu Kubernetes)\n\n| Tool | Risk | Use For |\n|------|------|---------|\n| `create_namespace` | medium | Create Supervisor Namespace |\n| `delete_namespace` | high | Delete namespace |\n| `create_tkc_cluster` | medium | Deploy TKC cluster |\n| `scale_tkc_cluster` | medium | Scale worker nodes |\n| `delete_tkc_cluster` | high | Delete TKC cluster |\n| `get_tkc_kubeconfig` | high | Returns a live Supervisor credential — gate it, write it to a file, never print it |\n| `get_supervisor_kubeconfig` | high | Same: a live Supervisor bearer token — gate it, write it to a file, never print it |\n\n### storage (Datastores, iSCSI, vSAN)\n\n| Tool | Risk | Use For |\n|------|------|---------|\n| `list_all_datastores` | low | List datastores |\n| `storage_iscsi_enable` | medium | Enable iSCSI adapter |\n| `storage_iscsi_add_target` | medium | Add iSCSI target |\n| `storage_rescan` | medium | Rescan storage adapters |\n| `vsan_health` | low | vSAN health check |\n| `vsan_capacity` | low | vSAN capacity info |\n\n---\n\n## Designing Custom Workflows\n\n### Method 1: YAML Templates\n\nDrop a `.yaml` file in `~/.vmware/workflows/` and it is immediately available.\nSupports `{{variable}}` placeholders that are filled from params at runtime.\n\n```yaml\n# ~/.vmware/workflows/restart_db_cluster.yaml\nname: restart_db_cluster\ndescription: Rolling restart of database cluster with health checks\nsteps:\n - action: check_health\n skill: monitor\n tool: get_alarms\n params:\n target: \"{{target}}\"\n\n - action: require_approval # required: vm_power_off below is high risk\n skill: pilot\n tool: approve\n params:\n message: \"Cluster healthy. Stop replica {{replica_vm}}?\"\n\n - action: stop_replica\n skill: aiops\n tool: vm_power_off\n params:\n vm_name: \"{{replica_vm}}\"\n force: false\n rollback_tool: vm_power_on\n rollback_params:\n vm_name: \"{{replica_vm}}\"\n\n - action: require_approval\n skill: pilot\n tool: approve\n params:\n message: \"Replica {{replica_vm}} stopped. Restart primary {{primary_vm}}?\"\n\n - action: restart_primary\n skill: aiops\n tool: vm_power_off\n params:\n vm_name: \"{{primary_vm}}\"\n force: false\n rollback_tool: vm_power_on\n rollback_params:\n vm_name: \"{{primary_vm}}\"\n\n - action: start_primary\n skill: aiops\n tool: vm_power_on\n params:\n vm_name: \"{{primary_vm}}\"\n\n - action: start_replica\n skill: aiops\n tool: vm_power_on\n params:\n vm_name: \"{{replica_vm}}\"\n\n - action: verify\n skill: monitor\n tool: get_alarms\n params:\n target: \"{{target}}\"\n```\n\nInvoke it:\n```\nplan_workflow(\"restart_db_cluster\", {\n target: \"vcenter1\",\n replica_vm: \"db02\",\n primary_vm: \"db01\"\n})\n```\n\n### Method 2: AI-Designed (`design_workflow`)\n\nDescribe your goal in natural language. The AI creates a draft that you review and edit.\n\n```\nUser: \"I need to migrate app01 to a new network segment with firewall rules\"\n\nAI calls: design_workflow(goal=\"Migrate app01 to new network segment with firewall rules\")\nAI returns: Draft workflow with steps from nsx, nsx-security, aiops, monitor\nUser reviews: Adjusts steps, adds/removes approval gates\nAI calls: confirm_draft(draft_id, save_as_template=True)\nAI calls: run_workflow(workflow_id)\n```\n\n### Method 3: Direct Creation (`create_workflow`)\n\nProvide steps directly as JSON when you already know exactly what you want:\n\n```\ncreate_workflow(\n name=\"quick_snapshot_revert\",\n steps=[\n {action: \"pre_check\", skill: \"monitor\", tool: \"get_alarms\", params: {target: \"prod\"}},\n {action: \"require_approval\", skill: \"pilot\", tool: \"approve\",\n params: {message: \"Revert web01 to baseline?\"}},\n {action: \"revert\", skill: \"aiops\", tool: \"vm_clean_slate\",\n params: {vm_name: \"web01\", snapshot_name: \"baseline\", target: \"prod\"}},\n {action: \"verify\", skill: \"monitor\", tool: \"vm_info\",\n params: {vm_name: \"web01\", target: \"prod\"}},\n ]\n)\n```\n\n---\n\n## Workflow States\n\nA workflow moves through these states:\n\n```\nDRAFT -> PENDING -> RUNNING -> AWAITING_APPROVAL -> RUNNING -> COMPLETED\n | |\n +-> FAILED --(rollback)--> ROLLING_BACK |\n | |\n +-> BLOCKED_BY_POLICY |\n | |\n +-> MONITORING ---> COMMITTING ----------+\n```\n\n| State | Meaning |\n|-------|---------|\n| `draft` | AI is still designing steps (editable) |\n| `pending` | Finalized, ready to execute |\n| `running` | Currently executing steps |\n| `awaiting_approval` | Paused at an approval gate |\n| `monitoring` | Watching for anomalies during test phase |\n| `committing` | Applying tested changes to production |\n| `rolling_back` | Undoing completed steps in reverse |\n| `completed` | All steps finished successfully |\n| `failed` | A step failed; nothing is undone until someone calls `rollback` |\n| `blocked_by_policy` | Blocked by a policy check |\n\n---\n\n## Best Practices\n\n### Step Design\n\n1. **Always include a pre-check step** -- Start with `monitor.get_alarms` or `aria.list_anomalies` to verify the environment is healthy before making changes.\n\n2. **Always include a post-verification step** -- End with a health check to confirm changes did not introduce issues.\n\n3. **Place approval gates before destructive operations** -- Any step that modifies production (power off, delete, reconfigure) should have an approval gate before it.\n\n4. **Define rollback for reversible steps** -- If a step can be undone (power off -> power on, create segment -> delete segment), always specify `rollback_tool` and `rollback_params`.\n\n5. **Keep workflows under 15 steps** -- Longer workflows are harder to review and more likely to fail mid-execution. Split into multiple workflows if needed.\n\n### Parameter Design\n\n6. **Use `{{variable}}` placeholders in YAML templates** -- Makes templates reusable across different VMs, targets, and environments.\n\n7. **Always include `target` parameter** -- Multi-vCenter setups require explicit target routing. Even single-vCenter setups benefit from explicit naming.\n\n8. **Use descriptive approval messages** -- The message shown at an approval gate is the user's primary decision-making context. Include what was done, what will happen next, and any risks.\n\n### Workflow Organization\n\n9. **Save successful workflows as templates** -- Use `confirm_draft(id, save_as_template=True)` to save AI-designed workflows for reuse.\n\n10. **Name templates by intent, not by tool** -- `restart_db_cluster` is better than `power_off_then_on`. The name should describe the goal, not the implementation.\n\n11. **Group related steps** -- Keep all steps for one resource together (e.g., all steps for VM \"db01\" before moving to \"db02\" in a rolling restart).\n\n12. **Test with `compliance_scan` first** -- Before running destructive workflows, run a compliance scan to verify the environment baseline.\n\n---\n\n## Validation\n\nBefore executing a workflow, validate it with the included script. It runs\npilot's own approval-gate check, so run it with the Python vmware-pilot is\ninstalled in:\n\n```bash\n\"$(uv tool dir)/vmware-pilot/bin/python\" scripts/validate_workflow.py ~/.vmware/workflows/my_workflow.yaml\n```\n\nThis checks:\n- Step structure is valid (action / skill / tool present, params a mapping)\n- **Approval gates (error)**: every destructive or unclassifiable step has a\n `require_approval` step before it — the same check `plan_workflow`,\n `create_workflow`, `confirm_draft` and `run_workflow` enforce\n- Skills and tools not in the catalog (warning — the catalog is a curated subset)\n\nFile v1.12.0:skill-card.md\n\n## Description:\n\nVMware Pilot designs, approves, executes, and tracks rollback-aware multi-step VMware workflows across companion VMware skills.\n\nThis skill is ready for commercial/non-commercial use.\n\n## Publisher:\n\n[zw008](https://clawhub.ai/user/zw008)\n\n### License/Terms of Use:\n\nMIT-0\n\n## Use Case:\n\nDevelopers, infrastructure engineers, and SREs use this skill to plan and coordinate VMware workflows that span multiple companion skills, with human approval gates before destructive operations and explicit rollback handling.\n\n### Deployment Geography for Use:\n\nGlobal\n\n## Known Risks and Mitigations:\n\nRisk: Workflow plans can coordinate high-impact changes through companion VMware skills.\n\nMitigation: Use least-privileged companion skill accounts and review generated workflows before approval.\n\nRisk: Kubeconfig-returning workflow steps can expose live credentials.\n\nMitigation: Keep those steps behind approval gates, write credentials only to owner-restricted files, and avoid printing tokens into chat or logs.\n\nRisk: Local workflow, audit, and baseline files may reveal infrastructure details.\n\nMitigation: Protect or expire those files and keep generated baselines out of shared chat or logs.\n\nRisk: The uvx fallback may re-resolve packages at launch time and is less suitable for production environments.\n\nMitigation: Prefer the installed vmware-pilot entry point for production use.\n\n## Reference(s):\n\n- [ClawHub skill page](https://clawhub.ai/zw008/skills/vmware-pilot)\n- [Project homepage from ClawHub metadata](https://github.com/vmware-skills/VMware-Pilot)\n- [Capabilities](artifact/references/capabilities.md)\n- [Workflow Design Guide](artifact/references/workflow-design.md)\n- [Built-in Templates Reference](artifact/references/templates.md)\n- [Cross-Skill Integration Patterns](artifact/references/integration-patterns.md)\n- [Setup Guide](artifact/references/setup-guide.md)\n- [CLI Reference](artifact/references/cli-reference.md)\n- [Agent Guardrails](artifact/references/agent-guardrails.md)\n\n## Skill Output:\n\n**Output Type(s):** [text, markdown, code, shell commands, configuration, guidance]\n\n**Output Format:** [Markdown guidance with workflow plans, MCP tool-call parameters, shell commands, YAML configuration, and JSON status or validation data.]\n\n**Output Parameters:** [1D]\n\n**Other Properties Related to Output:** [Outputs may include approval-gated workflow steps, rollback previews, audit guidance, and references to local workflow or baseline files.]\n\n## Skill Version(s):\n\n1.12.0 (source: server release metadata)\n\n## Ethical Considerations:\n\nUsers should evaluate whether this skill is appropriate for their environment, review any generated or modified files before relying on them, and apply their organization's safety, security, and compliance requirements before deployment.\n\nFile v1.12.0:evals/evals.json\n\n{\n \"skill_name\": \"vmware-pilot\",\n \"evals\": [\n {\n \"id\": 1,\n \"prompt\": \"I need to expand the database VM's memory from 16GB to 32GB, but test it on a clone first before applying to production\",\n \"expected_output\": \"clone_and_test workflow created with approval gate\",\n \"files\": [],\n \"expectations\": [\n \"Uses plan_workflow with type clone_and_test\",\n \"Change spec includes memory_mb: 32768\",\n \"Workflow has approval gate before production apply\",\n \"Shows workflow steps for user review\"\n ]\n },\n {\n \"id\": 2,\n \"prompt\": \"Design a workflow to set up a new app environment: create NSX segment, add firewall rules, deploy 3 VMs, install nginx on each\",\n \"expected_output\": \"Custom multi-skill workflow with approval gates\",\n \"files\": [],\n \"expectations\": [\n \"Uses design_workflow or create_workflow\",\n \"Steps span multiple skills: nsx, nsx-security, aiops\",\n \"Includes approval gate before VM deployment\",\n \"Shows the full workflow for user review before execution\"\n ]\n },\n {\n \"id\": 3,\n \"prompt\": \"There's a critical CPU alarm on prod-db-01. Run the incident response workflow to diagnose and fix it\",\n \"expected_output\": \"incident_response workflow executed with approval\",\n \"files\": [],\n \"expectations\": [\n \"Uses plan_workflow with type incident_response\",\n \"Collects alarms and events first\",\n \"Pauses for approval before remediation\",\n \"Acknowledges the alarm after approval\"\n ]\n },\n {\n \"id\": 4,\n \"prompt\": \"Save a reusable workflow template for rolling restart of our web cluster (web-01, web-02, web-03) with health checks between each\",\n \"expected_output\": \"rolling_restart workflow saved as template\",\n \"files\": [],\n \"expectations\": [\n \"Uses plan_workflow with type rolling_restart or create_workflow\",\n \"Includes health check between each VM restart\",\n \"Saves as YAML template with save_as_template=true\",\n \"Template is reusable for future runs\"\n ]\n }\n ]\n}\n\nArchive v1.11.1: 13 files, 47110 bytes\n\nFiles: evals/evals.json (2117b), references/agent-guardrails.md (10056b), references/capabilities.md (7482b), references/cli-reference.md (5668b), references/integration-patterns.md (15165b), references/setup-guide.md (6940b), references/templates.md (23080b), references/workflow-design.md (14154b), scripts/list_available_tools.py (9098b), scripts/validate_workflow.py (6500b), skill-card.md (2778b), SKILL.md (19296b), _meta.json (132b)\n\nFile v1.11.1:SKILL.md\n\n---\nname: vmware-pilot\ndescription: >\n Use this skill whenever the user wants to design, execute, or manage complex multi-step VMware workflows with human approval gates and explicit, best-effort rollback.\n Pilot is the orchestration brain — it breaks a goal into steps across companion VMware skills (aiops, monitor, nsx, nsx-security, aria, vks, storage, avi), adds approval gates before destructive operations, and records per-step undo actions that run only when rollback is explicitly called, never automatically.\n Always use vmware-pilot for: \"clone and test before applying to production\", \"VMware incident response with checkpoints\", \"investigate alert root cause\", \"VMware rolling restart with health checks\", \"baseline capture and drift detection\", \"rolling maintenance with AVI drain\", or any VMware workflow needing approval gates or rollback.\n 15 built-in templates + custom YAML + AI-designed workflows.\n Do NOT use for single-step work — use vmware-aiops for one VM action, vmware-monitor for read-only queries, vmware-avi for load balancer queries.\ninstaller:\n kind: uv\n package: vmware-pilot\nallowed-tools: [Bash]\nmetadata: {\"openclaw\":{\"requires\":{\"anyBins\":[\"vmware-pilot\",\"uvx\"]},\"optional\":{\"env\":[\"VMWARE_AUDIT_APPROVED_BY\"]},\"homepage\":\"https://github.com/vmware-skills/VMware-Pilot\",\"emoji\":\"🧭\",\"os\":[\"macos\",\"linux\"]}}\ncompatibility: >\n vmware-policy auto-installed as Python dependency (provides @vmware_tool decorator and audit logging). All workflow operations audited to ~/.vmware/audit.db.\n No direct vCenter/NSX credentials: Pilot is an orchestration layer that delegates to companion skills (aiops, monitor, nsx, etc.) which handle their own auth.\n Approval gates: Workflows pause for human review before destructive steps; a custom workflow (YAML, create_workflow, or AI-designed) with a destructive or unclassifiable step not preceded by a gate is rejected, and force=True cannot override that. Rollback is never automatic: a failed step stops the workflow, and undo happens only when rollback is called; it is best-effort, and on the MCP server the calling agent performs each rollback_tool call itself.\n Pilot drives companion skills that change production (VM power, guest commands, network, storage, Kubernetes). Guest commands (vm_guest_exec, vm_guest_upload, …) and credential-returning steps (vks get_tkc_kubeconfig, get_supervisor_kubeconfig) are gated like destructive ones.\n State persistence: SQLite-backed workflow state (~/.vmware/workflows.db, owner-only 0600 in a 0700 directory) survives restarts; secret-named params are masked before they are written. No webhooks, no outbound network calls.\n Transitive dependencies: Only vmware-policy (audit/policy). No post-install scripts or background services.\n---\n\n# VMware Pilot\n\n> **Disclaimer**: This is a community-maintained open-source project and is **not affiliated with, endorsed by, or sponsored by VMware, Inc. or Broadcom Inc.** \"VMware\" is a trademark of Broadcom. Source code is publicly auditable at [github.com/vmware-skills/VMware-Pilot](https://github.com/vmware-skills/VMware-Pilot) under the MIT license.\n\nMulti-step workflow orchestration for VMware MCP skills — design, approve, execute, rollback.\n\n**Companion Skills**: [vmware-aiops](../vmware-aiops/SKILL.md) (VM operations) | [vmware-monitor](../vmware-monitor/SKILL.md) (monitoring) | [vmware-nsx](../vmware-nsx/SKILL.md) (networking) | [vmware-aria](../vmware-aria/SKILL.md) (metrics/alerts) | [vmware-avi](../vmware-avi/SKILL.md) (load balancing/AKO)\n\n## What This Skill Does\n\n| Capability | Description |\n|---|---|\n| Workflow Design | Natural language goal → AI designs steps from the `get_skill_catalog` building-block list (99 curated tools across 13 skills) |\n| Approval Gates | Pause execution for human review before destructive operations |\n| State Persistence | SQLite-backed, survives restarts, supports resume from checkpoint |\n| Rollback | Explicit, best-effort undo of completed steps in reverse order — never automatic (see Troubleshooting) |\n| Custom Templates | Save workflows as YAML for reuse, hot-reload without restart |\n| Compliance Scans | Read-only health/capacity/anomaly checks across skills |\n\n## Quick Install\n\n```bash\nuv tool install vmware-pilot==1.11.1\nvmware-pilot mcp # start the MCP server (stdio)\n```\n\n## When to Use This Skill\n\n| Scenario | Use Pilot? | Why |\n|---|---|---|\n| \"Clone VM, test, then apply to prod\" | Yes | Multi-step + approval |\n| \"Power on a VM\" | No, use aiops | Single operation |\n| \"Set up app network + firewall + VMs\" | Yes | Cross-skill orchestration |\n| \"Check cluster health\" | No, use monitor/aria | Single read-only query |\n| \"Diagnose and fix an alert\" | Yes | incident_response template |\n| \"Run compliance check\" | Yes | compliance_scan template |\n| \"Drain server, patch, restore traffic\" | Yes | Cross-skill: avi drain + aiops patch |\n| \"Deploy app with AKO ingress\" | Yes | Cross-skill: aiops + vks + avi |\n| \"Check pool member health\" | No, use avi | Single read-only query |\n\n## Related Skills — Skill Routing\n\n| User Intent | Recommended Skill |\n|---|---|\n| VM lifecycle (power, clone, deploy) | **vmware-aiops** (`uv tool install vmware-aiops`) |\n| Read-only monitoring | **vmware-monitor** (`uv tool install vmware-monitor`) |\n| NSX networking (segments, gateways, NAT) | **vmware-nsx** (`uv tool install vmware-nsx-mgmt`) |\n| NSX security (DFW, groups) | **vmware-nsx-security** (`uv tool install vmware-nsx-security`) |\n| Aria metrics/alerts/capacity | **vmware-aria** (`uv tool install vmware-aria`) |\n| Tanzu Kubernetes (Supervisor/TKC) | **vmware-vks** (`uv tool install vmware-vks`) |\n| Storage (iSCSI, vSAN, datastores) | **vmware-storage** (`uv tool install vmware-storage`) |\n| Load balancing, VS, pool, AKO | **vmware-avi** (`uv tool install vmware-avi`) |\n| Audit log query | **vmware-policy** (`vmware-audit` CLI) |\n| **Multi-step orchestration** | **vmware-pilot** (this skill) |\n\n## Common Workflows\n\n### 1. Design a Custom Workflow (Interactive)\n\n```\nUser: \"I need to set up a new app environment with networking and VMs\"\n\nAI calls: get_skill_catalog() → see available tools\nAI calls: design_workflow(goal=\"...\") → create draft\nAI calls: update_draft(id, steps=[...]) → fill in steps\nUser reviews and confirms\nAI calls: confirm_draft(id, save_as_template=True)\nAI calls: run_workflow(id) → execute with approval gates\n```\n\n### 2. Clone-and-Test (Built-in Template)\n\n```\nAI calls: plan_workflow(\"clone_and_test\", {\n target_vm: \"db01\",\n change_spec: {memory_mb: 32768},\n target: \"vcenter-prod\"\n})\nAI calls: run_workflow(workflow_id)\n→ Clone → Apply → Monitor → [Approval Gate] → Commit → Cleanup\n```\n\n### 3. Batch Operations with Approval\n\n```\nAI calls: plan_workflow(\"plan_and_approve\", {\n operations: [\n {action: \"power_off\", vm_name: \"db01\"},\n {action: \"revert_snapshot\", vm_name: \"db01\", snapshot_name: \"baseline\"},\n {action: \"power_on\", vm_name: \"db01\"}\n ]\n})\n→ Create Plan → [Approval Gate] → Execute Plan\n→ If the apply fails, nothing is undone automatically: ask the user, then call\n vmware-aiops vm_rollback_plan(plan_id) yourself\n```\n\n### 4. Rolling Maintenance with AVI Drain\n\nDrain traffic from a pool member via AVI, patch the server, then restore traffic:\n\n```\n1. vmware-avi pool disable # drain traffic from pool member\n2. vmware-avi analytics # verify drain complete (0 active connections)\n3. vmware-aiops vm guest-exec --cmd \"apt-get upgrade -y\" # patch the server\n4. vmware-avi pool enable # restore traffic to pool member\n5. vmware-avi pool members # verify health status is green\n```\n\n### 5. AKO-Aware Application Deployment\n\nDeploy a backend VM, create a K8s namespace, and wire up AKO Ingress to the AVI Controller:\n\n```\n1. vmware-aiops deploy ova --name # deploy backend VM\n2. vmware-vks namespace create # create K8s namespace\n3. kubectl apply -f ingress.yaml # create Ingress with AKO annotations\n4. vmware-avi ako ingress check # validate AKO annotations are correct\n5. vmware-avi ako sync status # verify VS created on AVI Controller\n```\n\n## Dispatch Contract (Important)\n\n**Pilot is a Dispatcher, not an Executor.** It generates plans, tracks state, gates on approvals — it does NOT call companion skills' MCP tools itself. The calling AI agent is responsible for invoking `vmware-aiops::vm_clone` etc. when pilot's `run_workflow` returns a step description.\n\nThis is intentional v2-style architecture: pilot's context stays small, state is always on disk, and there are no persistent agent threads. Full contract details: see [`references/integration-patterns.md`](references/integration-patterns.md#the-dispatch-contract).\n\n**`get_skill_catalog` is a curated design aid, not a whitelist.** It surfaces 99 hand-picked building blocks across 13 skills — a deliberate subset of what those skills expose (aiops alone has 60 tools; the catalog lists 19). A step's `skill` field is a free-form string handed to the calling agent, so a workflow may name any companion skill, including ones the catalog does not list — pilot itself (`pilot`) is used that way by built-in templates for approval gates. Use the catalog for inspiration; consult the target skill's own SKILL.md for its full tool surface.\n\n## MCP Tools (13 — 4 read, 9 write/control)\n\n| Category | Tool | Risk | Description |\n|---|---|---|---|\n| **Discovery** | `get_skill_catalog` | low | Available skills and tools for design |\n| | `list_workflows` | low | Built-in + custom templates |\n| **Design** | `design_workflow` | low | Natural language → draft |\n| | `update_draft` | medium | Edit draft steps |\n| | `confirm_draft` | medium | Finalize draft → ready to execute |\n| **Execute** | `plan_workflow` | medium | Create from template |\n| | `create_workflow` | medium | One-step custom creation (rejected if a destructive step has no gate before it) |\n| | `review_workflow` | low | Structural sanity check before execution (approved \\| needs_revision) |\n| | `run_workflow` | medium | Execute next checkpoint (agent dispatches each step) |\n| **Control** | `approve` | high | Human approval to continue |\n| | `cancel_workflow` | high | Cancel a workflow (approval rejected / unsafe) → terminal CANCELLED, can't be run |\n| | `rollback` | high | Explicit, best-effort undo; never runs on its own |\n| | `get_workflow_status` | low | State + audit log |\n\n## Built-in Templates (15)\n\nThe five most-used:\n\n| Template | Steps | Approval | Skills Used |\n|---|---|---|---|\n| `clone_and_test` | 6 (7 for a guest command) | Yes | aiops + monitor |\n| `incident_response` | 4 | Yes | monitor + aiops |\n| `investigate_alert` | 4 / 8 | Yes | monitor + aria (parallel-group gather + 4-criteria checkpoint, optional `deep_dive`) |\n| `plan_and_approve` | 3 | Yes | aiops |\n| `compliance_scan` | 3 | No | monitor + aria |\n\nFull list: `clone_and_test`, `incident_response`, `investigate_alert`, `plan_and_approve`, `compliance_scan`, `network_segment_setup`, `vks_cluster_deploy`, `rolling_restart`, `capacity_expansion`, `disaster_recovery`, `patch_deployment`, `storage_expansion`, `baseline_capture`, `baseline_audit`, `baseline_remediate`. See `references/templates.md` for full details.\n\n## Custom Templates\n\nDrop YAML files in `~/.vmware/workflows/` — pilot auto-loads them.\n\n**Approval gates are mandatory in custom workflows.** Every destructive step (the\nskill catalog marks it high/critical risk, or its name says delete/remove/…) and\nevery step pilot cannot classify must have a `require_approval` step somewhere\nbefore it. Otherwise `plan_workflow`, `create_workflow` and `confirm_draft` refuse\nthe workflow and name the offending steps, `run_workflow` refuses it even with\n`force=True`, and `scripts/validate_workflow.py` reports an error. Medium-risk\nwrites (`create_segment`, `vm_power_on`, …) do not require a gate.\n\n```yaml\n# ~/.vmware/workflows/restart_cluster.yaml\nname: restart_cluster\ndescription: Rolling restart of database cluster\nsteps:\n - action: check_health\n skill: monitor\n tool: get_alarms\n params:\n target: \"{{target}}\"\n - action: require_approval # required: the next step changes the estate\n skill: pilot\n tool: approve\n params:\n message: \"Cluster healthy. Stop replica {{replica_vm}}?\"\n - action: stop_replica\n skill: aiops\n tool: vm_power_off\n params:\n vm_name: \"{{replica_vm}}\"\n rollback_tool: vm_power_on\n rollback_params:\n vm_name: \"{{replica_vm}}\"\n - action: restart_primary\n skill: aiops\n tool: vm_power_off\n params:\n vm_name: \"{{primary_vm}}\"\n```\n\n## Usage Mode\n\n| Scenario | Recommended | Why |\n|----------|:-----------:|-----|\n| Local/small models (Ollama, Qwen) | **MCP** | Structured JSON I/O for multi-step state |\n| Cloud models (Claude, GPT-4o) | **MCP** | Design mode needs structured tool calls |\n| CI/CD pipeline orchestration | **MCP** | Programmatic plan/approve/run cycle |\n| Quick template listing | **MCP** | Call `list_workflows`; the CLI has no template commands |\n\n> Note: every workflow operation — design, plan, run, approve, rollback — is MCP-only.\n> The `vmware-pilot` CLI exists to launch the server and report its version, nothing more.\n> Other skills in the family (aiops, monitor, avi, etc.) offer full CLI and MCP modes.\n\n## CLI Quick Reference\n\nThe CLI is a launcher, not a second interface to workflows:\n\n```bash\nvmware-pilot mcp # start the MCP server (stdio)\nvmware-pilot version # print installed version\nvmware-pilot --help\n\n# Validate a custom workflow YAML before loading (runs pilot's own gate check,\n# so it needs the Python vmware-pilot is installed in)\n\"$(uv tool dir)/vmware-pilot/bin/python\" scripts/validate_workflow.py ~/.vmware/workflows/my_workflow.yaml\n\n# List available tools across all skills (design helper)\npython3 scripts/list_available_tools.py # all skills\npython3 scripts/list_available_tools.py aiops # specific skill\npython3 scripts/list_available_tools.py --json # JSON output\n\n# View audit logs (via vmware-policy)\nvmware-audit log --last 20\nvmware-audit log --status denied\n```\n\n> Full CLI reference for companion skills: see `references/cli-reference.md`\n\n## Troubleshooting\n\n### Workflow stuck in \"awaiting_approval\"\nCall `approve(workflow_id, approver=...)` with the correct workflow ID to continue, or `cancel_workflow(workflow_id)` if the approval is rejected. If the MCP session was lost, reconnect and call `get_workflow_status(workflow_id)` to see the current state -- workflows persist in SQLite and survive restarts.\n\n### \"Unknown workflow type\" error from plan_workflow\nThe template name is case-sensitive. Use `list_workflows()` to see all available built-in and custom template names. Custom templates must be valid YAML in `~/.vmware/workflows/`.\n\n### Custom YAML template not appearing\n1. Verify the file is in `~/.vmware/workflows/` with a `.yaml` extension\n2. Check YAML syntax -- run `scripts/validate_workflow.py ` with pilot's Python (see CLI Quick Reference)\n3. A YAML file you drop in whose name matches a built-in replaces it (a warning is logged) -- rename it if that is not what you want. `create_workflow` and `confirm_draft` refuse to save a template under a built-in name\n4. A file that lists but will not plan is missing an approval gate -- the `plan_workflow` error names the step and the file\n\n### Rollback did nothing, or fails on some steps\nRollback never happens on its own: a failed step leaves the workflow `failed` and stops. `rollback` only reverses steps pilot recorded as `success`, and on the MCP server (no dispatcher) the steps you performed from `pending_dispatch` stay `not_executed` — so `rollback` there reverses nothing but approval gates. Undo them yourself: call each performed step's `rollback_tool` with its `rollback_params`, last step first, after confirming with the user. Steps without a `rollback_tool` cannot be undone. When pilot does dispatch (an embedder supplied a dispatcher), rollback is best-effort: a failed undo does not stop the rest, and the result reports each one.\n\n### \"Workflow cannot be run\" state error\nA workflow can only be run from `pending` or `running` states. If it is in `draft`, call `confirm_draft()` first. If it is in `completed` or `failed`, create a new workflow -- completed workflows cannot be re-run.\n\n### vmware-policy dependency missing\nPilot requires `vmware-policy` for the `@vmware_tool` decorator and audit logging. It is declared as a dependency in `pyproject.toml` and should install automatically. If missing, run `pip install vmware-policy` or reinstall pilot.\n\n## Setup\n\nNo vCenter credentials needed — pilot orchestrates other skills that handle connections.\n\n```json\n{\n \"mcpServers\": {\n \"vmware-pilot\": {\n \"command\": \"vmware-pilot\",\n \"args\": [\"mcp\"]\n }\n }\n}\n```\n\n> Fallback: `{\"command\": \"uvx\", \"args\": [\"--from\", \"vmware-pilot==1.11.1\", \"vmware-pilot-mcp\"]}` also\n> works, but `uvx` re-resolves the package against PyPI on every start and fails behind a\n> TLS-inspecting corporate proxy (`invalid peer certificate: UnknownIssuer`). The installed\n> entry point above touches the network zero times; set `UV_NATIVE_TLS=true` if you must use `uvx`.\n\n## Audit & Safety\n\nAll operations are automatically audited via vmware-policy (`@vmware_tool` decorator):\n- Every tool call logged to `~/.vmware/audit.db` (SQLite, framework-agnostic)\n- Policy rules enforced via `~/.vmware/rules.yaml` (deny rules, maintenance windows, risk levels)\n- Risk classification: each tool tagged as low/medium/high/critical\n- Environment scoping: policy rules can scope by environment (an optional label an opt-in `deny` rule may match), and skills with a config may declare `environment:` per target. Pilot has no targets of its own and registers no environment resolver, so its own calls are unlabeled (they match no environment-scoped rule) — its writes go to the local workflow DB, never to a VMware estate. Pilot's approval gate is a step in its own workflow: it pauses before the agent dispatches a destructive step, and the target skill then applies its own policy rules when the step runs\n- View recent operations: `vmware-audit log --last 20`\n- View denied operations: `vmware-audit log --status denied`\n- Credential steps: `vks get_tkc_kubeconfig` and `get_supervisor_kubeconfig` return a live Supervisor token. Treat them as credential access, not read-only queries — never run one on your own initiative, keep it behind an approval gate (pilot gates both like a delete), write the kubeconfig to an owner-only file, and never print the token into chat or logs\n- Local data is sensitive: `~/.vmware/workflows.db` (pilot keeps `~/.vmware` 0700 and the DB 0600) holds step params and companion-skill results, with secret-named params masked. Pilot never writes `~/.vmware/baselines/`; a baseline the agent saves there is an inventory of VMs, hosts, network segments, datastores and alarms — keep it owner-only and out of chat\n\nvmware-policy is automatically installed as a dependency — no manual setup needed.\n\n## License\n\nMIT\n\nFile v1.11.1:_meta.json\n\n{\n \"ownerId\": \"kn7b067awq2s97bn3d7p5qfhw5827pxc\",\n \"slug\": \"vmware-pilot\",\n \"version\": \"1.11.1\",\n \"publishedAt\": 1789452358115\n}\n\nFile v1.11.1:references/agent-guardrails.md\n\n# Operating vmware-pilot with a local / small model\n\nClaude-class models drive this skill without special instruction. Smaller and\nlocally-hosted models — Llama 3.3 70B, Qwen, Mistral, and similar, served\nthrough Goose, Ollama, or OpenShift AI — need explicit operating rules to call\ntools reliably.\n\nThis page exists because an operator wrote those rules by hand first. The\nguardrails below are adapted, with thanks, from the working configuration\n[@juanpf-ha](https://github.com/juanpf-ha) developed while running\nvmware-monitor and vmware-aria against a production vSphere estate with Llama\n3.3 70B FP8 on an on-prem H100\n([VMware-AIops#31](https://github.com/vmware-skills/VMware-AIops/issues/31)). The\ncross-skill rules are identical across this family; the parts below marked\nvmware-pilot are specific to this skill.\n\nvmware-pilot is the odd one out. It manages no infrastructure of its own — it\ndesigns multi-step workflows, tracks their state, and gates them on human\napproval. Two consequences follow, and both matter more on a small model than\non a large one: **authoring a workflow is itself the write operation**, and\n**pilot does not execute anything** — the calling agent does.\n\n> **Disclaimer**: This is a community-maintained open-source project and is\n> **not affiliated with, endorsed by, or sponsored by VMware, Inc. or Broadcom\n> Inc.** \"VMware\" and \"vSphere\" are trademarks of Broadcom.\n\n---\n\n## First: the rules you no longer need to write\n\nSeveral guardrails from the original configuration are now enforced by the\nskill itself. Prompt instructions are advisory — a model can ignore them.\nThese are structural, so it cannot.\n\n| Guardrail you would otherwise prompt for | Now enforced by |\n|---|---|\n| \"Do not execute steps yourself — hand them back for a human to run\" | **The dispatch contract.** Pilot never calls a companion skill's MCP tools; it returns a step description and the calling agent invokes the tool. This is architecture, not etiquette. |\n| \"Check the plan makes sense before running it\" | **`review_workflow`** performs a structural sanity check and returns `approved` or `needs_revision`. It is a read tool that inspects a definition without executing it. |\n| \"Put an approval gate before anything destructive\" | **Custom-workflow rejection.** In a custom workflow (YAML, `create_workflow`, or a draft), a destructive or unclassifiable step with no `require_approval` before it makes `create_workflow` / `confirm_draft` / `plan_workflow` refuse to save it and `run_workflow` refuse to run it — `force=True` does not override that. The refusal names the step and the gate to insert. |\n| \"Log every state change you make\" | **The `@vmware_tool` decorator.** Every workflow transition is recorded to `~/.vmware/audit.db`, and `get_workflow_status` returns the state plus its audit log. |\n\nThe one guardrail this skill does not hand you: pilot's list tools return bare\ncollections, not the family `{items, returned, limit, total, truncated, hint}`\nenvelope. Truncation is not self-declaring here.\n\n---\n\n## The system prompt\n\nEverything below still benefits from being stated explicitly. Copy this into\nyour agent's instruction block.\n\n```text\n## Tool use\n\n- Always call an MCP tool before answering any question about workflow state.\n Never answer from memory or assumption.\n- Never describe a tool call, and never output a JSON example, instead of\n executing the tool. If you intend to call a tool, call it.\n- If a tool fails, report the actual error text. Do not complete the answer\n with assumptions about what the result would have been.\n- Use explicit limits on queries that may return large amounts of data. Do not\n request unlimited results unless the user asks for them.\n\n## Skill routing\n\n- vmware-pilot: multi-step workflows — design, plan, run, approve, roll back,\n cancel, and inspect state.\n- vmware-aiops: VM lifecycle. Pilot never calls it; you do, when pilot hands\n you a step.\n- vmware-monitor: read-only vCenter inventory, hosts, alarms, events.\n- vmware-nsx / vmware-nsx-security: networking and firewall.\n- vmware-storage, vmware-vks, vmware-aria, vmware-avi: their own domains.\n- A single-step request does not need a workflow. Call the skill directly.\n\n## The dispatch contract\n\n- Pilot is a dispatcher, not an executor. When run_workflow returns a step, YOU\n invoke that skill's MCP tool and report the result back. Pilot will not do it.\n- Never claim a step ran because pilot advanced its state. State advanced\n because you told pilot it did.\n- If you cannot invoke the tool a step names — it is not installed or is\n otherwise unavailable — say so and stop. Do not improvise a substitute.\n\n## Designing workflows\n\n- A step's tool must be a real tool on the named skill. get_skill_catalog is a\n curated design aid, not a whitelist: it lists a hand-picked subset, so a tool\n missing from the catalog may still exist. Confirm against the target skill's\n own SKILL.md before writing a step that names it.\n- Never invent a tool name to make a step read well. A workflow that names a\n tool which does not exist fails at run time, several steps in.\n- Order steps by dependency, not by narration. Gather state before changing it;\n put the approval gate before the first irreversible step, not after it.\n- Give every reversible step a rollback_tool and rollback_params. A step with\n no rollback cannot be undone by the rollback tool.\n- Nothing is ever rolled back automatically. After a failure, ask the user\n before undoing anything. On the MCP server the rollback tool cannot see the\n steps you performed (they stay not_executed), so undo them yourself: call each\n one's rollback_tool with its rollback_params, last step first.\n- get_tkc_kubeconfig and get_supervisor_kubeconfig return a live credential.\n Only fetch one when the user asks, write it to a file, and never print the\n token.\n- Run review_workflow before executing. Treat needs_revision as a stop.\n\n## Data fidelity\n\n- Never invent workflows, steps, templates, or state transitions. If a tool did\n not return it, it does not exist for this answer.\n- Preserve the exact workflow and step state values the tools return. Do not\n translate, normalise, or prettify them.\n- Report the steps in their defined order. Order is semantic in a workflow.\n- If a requested field was not returned, show it as \"not available\".\n- When a response is long, report every item it contains.\n\n## Analysis discipline\n\n- Separate observed data from interpretation. State which is which.\n- Do not claim a workflow succeeded, or that an estate is now in some state,\n on the basis of workflow state alone. Verify with the owning skill's read\n tools.\n- Avoid generic recommendations that are not directly supported by the results.\n```\n\n---\n\n## Known failure modes on small models\n\nObserved with Llama 3.3 70B FP8 (Goose, on-prem H100), and useful as a\nchecklist when evaluating any local model against these skills:\n\n| Symptom | Mitigation |\n|---|---|\n| Describes a tool call, or emits a JSON example, instead of executing it | The \"never describe a tool call\" rule above. Also check your harness is not echoing tool schemas into context — models imitate the nearest format they see. |\n| Long tool responses: omits items, or reports \"no data returned\" when data was present | Ask for explicit limits so responses stay small. Pilot's lists have no truncation envelope, so verify long results rather than trusting the summary. |\n| Adds generic recommendations unsupported by results | The \"analysis discipline\" rules. |\n| Drops requested fields or reorders results | State the required fields and ordering in the request itself. In a workflow, reordering the steps changes what the plan does. |\n| Multi-tool workflows take 30–50s end to end | Start from a built-in template with `plan_workflow` rather than designing from scratch; `get_workflow_status` returns state and audit log together. |\n\n### Workflow design failures — the pattern to watch here\n\nDesigning a plan is generative work, and it is where a small model's habits do\nthe most damage. These are specific to this skill:\n\n| Symptom | Mitigation |\n|---|---|\n| Writes a step naming a tool that does not exist — a plausible name assembled from the skill's naming pattern rather than its actual surface | The \"never invent a tool name\" rule. `get_skill_catalog` lists a curated subset, so absence from the catalog is not proof a tool is missing — and presence of a *plausible* name in the model's head is no proof it exists. Confirm against the target skill's SKILL.md. Nothing catches this until run time. |\n| Orders steps by narrative rather than dependency: changes state before gathering it, or verifies before acting | The \"order by dependency\" rule, then `review_workflow`. |\n| Places the approval gate after the irreversible step it was meant to guard | Refused structurally for destructive and unclassifiable steps (see the table above); for medium-risk writes, the \"order b\n\nArchive v1.11.0: 13 files, 47145 bytes\n\nFiles: evals/evals.json (2117b), references/agent-guardrails.md (10056b), references/capabilities.md (7482b), references/cli-reference.md (5668b), references/integration-patterns.md (15165b), references/setup-guide.md (6940b), references/templates.md (23080b), references/workflow-design.md (14154b), scripts/list_available_tools.py (9098b), scripts/validate_workflow.py (6500b), skill-card.md (2771b), SKILL.md (19296b), _meta.json (132b)\n\nArchive v1.10.1: 13 files, 46953 bytes\n\nFiles: evals/evals.json (2117b), references/agent-guardrails.md (10056b), references/capabilities.md (6926b), references/cli-reference.md (5668b), references/integration-patterns.md (15164b), references/setup-guide.md (6940b), references/templates.md (23080b), references/workflow-design.md (14154b), scripts/list_available_tools.py (9098b), scripts/validate_workflow.py (6500b), skill-card.md (2960b), SKILL.md (19294b), _meta.json (132b)\n\nArchive v1.10.0: 13 files, 46173 bytes\n\nFiles: evals/evals.json (2117b), references/agent-guardrails.md (10056b), references/capabilities.md (6926b), references/cli-reference.md (5668b), references/integration-patterns.md (15164b), references/setup-guide.md (6940b), references/templates.md (20610b), references/workflow-design.md (14154b), scripts/list_available_tools.py (9098b), scripts/validate_workflow.py (6500b), skill-card.md (3017b), SKILL.md (19294b), _meta.json (132b)\n\nArchive v1.9.0: 13 files, 46100 bytes\n\nFiles: evals/evals.json (2117b), references/agent-guardrails.md (10056b), references/capabilities.md (6926b), references/cli-reference.md (5666b), references/integration-patterns.md (15164b), references/setup-guide.md (6935b), references/templates.md (20610b), references/workflow-design.md (14154b), scripts/list_available_tools.py (9098b), scripts/validate_workflow.py (6500b), skill-card.md (2906b), SKILL.md (19292b), _meta.json (131b)\n\nArchive v1.8.12: 13 files, 41514 bytes\n\nFiles: evals/evals.json (2117b), references/agent-guardrails.md (9031b), references/capabilities.md (6373b), references/cli-reference.md (5122b), references/integration-patterns.md (13619b), references/setup-guide.md (6681b), references/templates.md (18582b), references/workflow-design.md (12755b), scripts/list_available_tools.py (8813b), scripts/validate_workflow.py (8113b), skill-card.md (2644b), SKILL.md (15916b), _meta.json (132b)\n\nArchive v1.8.11: 13 files, 41606 bytes\n\nFiles: evals/evals.json (2117b), references/agent-guardrails.md (9031b), references/capabilities.md (6373b), references/cli-reference.md (5122b), references/integration-patterns.md (13619b), references/setup-guide.md (6681b), references/templates.md (18582b), references/workflow-design.md (12755b), scripts/list_available_tools.py (8813b), scripts/validate_workflow.py (8113b), skill-card.md (2833b), SKILL.md (15916b), _meta.json (132b)\n\nArchive v1.8.10: 13 files, 41607 bytes\n\nFiles: evals/evals.json (2117b), references/agent-guardrails.md (9031b), references/capabilities.md (6373b), references/cli-reference.md (5122b), references/integration-patterns.md (13619b), references/setup-guide.md (6681b), references/templates.md (18582b), references/workflow-design.md (12755b), scripts/list_available_tools.py (8813b), scripts/validate_workflow.py (8113b), skill-card.md (2828b), SKILL.md (15916b), _meta.json (132b)\n\nArchive v1.8.9: 13 files, 41626 bytes\n\nFiles: evals/evals.json (2117b), references/agent-guardrails.md (9031b), references/capabilities.md (6373b), references/cli-reference.md (5122b), references/integration-patterns.md (13619b), references/setup-guide.md (6681b), references/templates.md (18582b), references/workflow-design.md (12755b), scripts/list_available_tools.py (8813b), scripts/validate_workflow.py (8113b), skill-card.md (2848b), SKILL.md (15916b), _meta.json (131b)","readmeExcerpt":"Skill: vmware-pilot Owner: zw008 Summary: Use this skill whenever the user wants to design, execute, or manage complex multi-step VMware workflows with human approval gates and explicit, best-effort rollback. Pilot is the orchestration brain — it breaks a goal into steps across companion VMware skills (aiops, monitor, nsx, nsx-security, aria, vks, storage, avi), adds approval gates before destructive operations, and ","codeSnippets":[],"executableExamples":[{"language":"bash","snippet":"uv tool install vmware-pilot==1.12.0\nvmware-pilot mcp # start the MCP server (stdio)"},{"language":"text","snippet":"User: \"I need to set up a new app environment with networking and VMs\"\n\nAI calls: get_skill_catalog() → see available tools\nAI calls: design_workflow(goal=\"...\") → create draft\nAI calls: update_draft(id, steps=[...]) → fill in steps\nUser reviews and confirms\nAI calls: confirm_draft(id, save_as_template=True)\nAI calls: run_workflow(id) → execute with approval gates"},{"language":"text","snippet":"AI calls: plan_workflow(\"clone_and_test\", {\n target_vm: \"db01\",\n change_spec: {memory_mb: 32768},\n target: \"vcenter-prod\"\n})\nAI calls: run_workflow(workflow_id)\n→ Clone → Apply → Monitor → [Approval Gate] → Commit → Cleanup"},{"language":"text","snippet":"AI calls: plan_workflow(\"plan_and_approve\", {\n operations: [\n {action: \"power_off\", vm_name: \"db01\"},\n {action: \"revert_snapshot\", vm_name: \"db01\", snapshot_name: \"baseline\"},\n {action: \"power_on\", vm_name: \"db01\"}\n ]\n})\n→ Create Plan → [Approval Gate] → Execute Plan\n→ If the apply fails, nothing is undone automatically: ask the user, then call\n vmware-aiops vm_rollback_plan(plan_id) yourself"},{"language":"text","snippet":"1. vmware-avi pool disable # drain traffic from pool member\n2. vmware-avi analytics # verify drain complete (0 active connections)\n3. vmware-aiops vm guest-exec --cmd \"apt-get upgrade -y\" # patch the server\n4. vmware-avi pool enable # restore traffic to pool member\n5. vmware-avi pool members # verify health status is green"},{"language":"text","snippet":"1. vmware-aiops deploy ova --name # deploy backend VM\n2. vmware-vks namespace create # create K8s namespace\n3. kubectl apply -f ingress.yaml # create Ingress with AKO annotations\n4. vmware-avi ako ingress check # validate AKO annotations are correct\n5. vmware-avi ako sync status # verify VS created on AVI Controller"}],"parameters":null,"dependencies":[],"permissions":[],"extractedFiles":[{"path":"SKILL.md","content":"---\nname: vmware-pilot\ndescription: >\n Use this skill whenever the user wants to design, execute, or manage complex multi-step VMware workflows with human approval gates and explicit, best-effort rollback.\n Pilot is the orchestration brain — it breaks a goal into steps across companion VMware skills (aiops, monitor, nsx, nsx-security, aria, vks, storage, avi), adds approval gates before destructive operations, and records per-step undo actions that run only when rollback is explicitly called, never automatically.\n Always use vmware-pilot for: \"clone and test before applying to production\", \"VMware incident response with checkpoints\", \"investigate alert root cause\", \"VMware rolling restart with health checks\", \"baseline capture and drift detection\", \"rolling maintenance with AVI drain\", or any VMware workflow needing approval gates or rollback.\n 15 built-in templates + custom YAML + AI-designed workflows.\n Do NOT use for single-step work — use vmware-aiops for one VM action, vmware-monitor for read-only queries, vmware-avi for load balancer queries.\ninstaller:\n kind: uv\n package: vmware-pilot\nallowed-tools: [Bash]\nmetadata: {\"openclaw\":{\"requires\":{\"anyBins\":[\"vmware-pilot\",\"uvx\"]},\"optional\":{\"env\":[\"VMWARE_AUDIT_APPROVED_BY\"]},\"homepage\":\"https://github.com/vmware-skills/VMware-Pilot\",\"emoji\":\"🧭\",\"os\":[\"macos\",\"linux\"]}}\ncompatibility: >\n vmware-policy auto-installed as Python dependency (provides @vmware_tool decorator and audit logging). All workflow operations audited to ~/.vmware/audit.db.\n No direct vCenter/NSX credentials: Pilot is an orchestration layer that delegates to companion skills (aiops, monitor, nsx, etc.) which handle their own auth.\n Approval gates: Workflows pause for human review before destructive steps; a custom workflow (YAML, create_workflow, or AI-designed) with a destructive or unclassifiable step not preceded by a gate is rejected, and force=True cannot override that. Rollback is never automatic: a failed step stops the workflow, and undo happens only when rollback is called; it is best-effort, and on the MCP server the calling agent performs each rollback_tool call itself.\n Pilot drives companion skills that change production (VM power, guest commands, network, storage, Kubernetes). Guest commands (vm_guest_exec, vm_guest_upload, …) and credential-returning steps (vks get_tkc_kubeconfig, get_supervisor_kubeconfig) are gated like destructive ones.\n State persistence: SQLite-backed workflow state (~/.vmware/workflows.db, owner-only 0600 in a 0700 directory) survives restarts; secret-named params are masked before they are written. No webhooks, no outbound network calls.\n Transitive dependencies: Only vmware-policy (audit/policy). No post-install scripts or background services.\n---\n\n# VMware Pilot\n\n> **Disclaimer**: This is a community-maintained open-source project and is **not affiliated with, endorsed by, or sponsored by VMware, Inc. or Broadcom Inc.** \"VMware\" is a trademark of Broadcom. Source code is "},{"path":"_meta.json","content":"{\n \"ownerId\": \"kn7b067awq2s97bn3d7p5qfhw5827pxc\",\n \"slug\": \"vmware-pilot\",\n \"version\": \"1.12.0\",\n \"publishedAt\": 1789790141850\n}"},{"path":"references/agent-guardrails.md","content":"# Operating vmware-pilot with a local / small model\n\nClaude-class models drive this skill without special instruction. Smaller and\nlocally-hosted models — Llama 3.3 70B, Qwen, Mistral, and similar, served\nthrough Goose, Ollama, or OpenShift AI — need explicit operating rules to call\ntools reliably.\n\nThis page exists because an operator wrote those rules by hand first. The\nguardrails below are adapted, with thanks, from the working configuration\n[@juanpf-ha](https://github.com/juanpf-ha) developed while running\nvmware-monitor and vmware-aria against a production vSphere estate with Llama\n3.3 70B FP8 on an on-prem H100\n([VMware-AIops#31](https://github.com/vmware-skills/VMware-AIops/issues/31)). The\ncross-skill rules are identical across this family; the parts below marked\nvmware-pilot are specific to this skill.\n\nvmware-pilot is the odd one out. It manages no infrastructure of its own — it\ndesigns multi-step workflows, tracks their state, and gates them on human\napproval. Two consequences follow, and both matter more on a small model than\non a large one: **authoring a workflow is itself the write operation**, and\n**pilot does not execute anything** — the calling agent does.\n\n> **Disclaimer**: This is a community-maintained open-source project and is\n> **not affiliated with, endorsed by, or sponsored by VMware, Inc. or Broadcom\n> Inc.** \"VMware\" and \"vSphere\" are trademarks of Broadcom.\n\n---\n\n## First: the rules you no longer need to write\n\nSeveral guardrails from the original configuration are now enforced by the\nskill itself. Prompt instructions are advisory — a model can ignore them.\nThese are structural, so it cannot.\n\n| Guardrail you would otherwise prompt for | Now enforced by |\n|---|---|\n| \"Do not execute steps yourself — hand them back for a human to run\" | **The dispatch contract.** Pilot never calls a companion skill's MCP tools; it returns a step description and the calling agent invokes the tool. This is architecture, not etiquette. |\n| \"Check the plan makes sense before running it\" | **`review_workflow`** performs a structural sanity check and returns `approved` or `needs_revision`. It is a read tool that inspects a definition without executing it. |\n| \"Put an approval gate before anything destructive\" | **Custom-workflow rejection.** In a custom workflow (YAML, `create_workflow`, or a draft), a destructive or unclassifiable step — or any step passing `confirm: True` — with no `require_approval` before it makes `create_workflow` / `confirm_draft` / `plan_workflow` refuse to save it and `run_workflow` refuse to run it — `force=True` does not override that. The refusal names the step and the gate to insert. |\n| \"Log every state change you make\" | **The `@vmware_tool` decorator.** Every workflow transition is recorded to `~/.vmware/audit.db`, and `get_workflow_status` returns the state plus its audit log. |\n\nThe one guardrail this skill does not hand you: pilot's list tools return bare\ncollections, not the family `{items, returned, limit,"},{"path":"references/capabilities.md","content":"# Capabilities — vmware-pilot\n\n## MCP Tools (13 — 4 read, 9 write)\n\n| # | Tool | Risk | Category | Description |\n|---|------|------|----------|-------------|\n| 1 | `get_skill_catalog` | low | Discovery | List all available skills and tools for workflow design |\n| 2 | `list_workflows` | low | Discovery | List built-in + custom templates and active workflows |\n| 3 | `design_workflow` | low | Design | Natural language goal → draft workflow for review |\n| 4 | `update_draft` | medium | Design | Edit draft workflow steps, name, or description |\n| 5 | `confirm_draft` | medium | Design | Finalize draft → state changes to PENDING |\n| 6 | `plan_workflow` | medium | Execute | Create workflow from built-in/custom template |\n| 7 | `create_workflow` | medium | Execute | Create custom workflow from step list (refused if a destructive step has no approval gate before it) |\n| 8 | `run_workflow` | medium | Execute | Execute workflow, pauses at approval gates |\n| 9 | `approve` | high | Control | Human approval to continue past approval gate |\n| 10 | `rollback` | high | Control | Explicit, best-effort undo of steps pilot recorded as succeeded, in reverse order — never automatic. Previews (`blast_radius`) unless `confirm=True` |\n| 11 | `get_workflow_status` | low | Control | Query workflow state, audit log, diff report |\n| 12 | `review_workflow` | low | Discovery | Sanity-check a planned workflow before anyone runs it |\n| 13 | `cancel_workflow` | high | Control | Cancel a workflow — moves it to the terminal CANCELLED state. Previews (`blast_radius`) unless `confirm=True` |\n\n---\n\n## Built-in Templates (15)\n\n| # | Template | Steps | Approval | Skills Used | Risk |\n|---|----------|-------|----------|-------------|------|\n| 1 | `clone_and_test` | 6-7 | Yes | aiops, monitor | Medium |\n| 2 | `incident_response` | 4 | Yes | monitor, aiops | Medium |\n| 3 | `plan_and_approve` | 3 | Yes | aiops | High |\n| 4 | `compliance_scan` | 1-3 | No | monitor, aria | Low |\n| 5 | `network_segment_setup` | 3-6 | Yes | nsx, nsx-security | Medium |\n| 6 | `vks_cluster_deploy` | 5 | Yes | vks | Medium |\n| 7 | `rolling_restart` | 2+3n | Yes | aiops, monitor | Medium |\n| 8 | `capacity_expansion` | 5 | Yes | aria, aiops, monitor | Medium |\n| 9 | `disaster_recovery` | 5 | Yes | aiops, monitor, nsx | High |\n| 10 | `patch_deployment` | 1+3n | Yes | aiops, monitor | Medium |\n| 11 | `storage_expansion` | 6 | Yes | storage | Medium |\n| 12 | `baseline_capture` | 1-5 | No | monitor, nsx, storage | Low |\n| 13 | `baseline_audit` | 1-5 | No | monitor, nsx, storage, aria | Low |\n| 14 | `baseline_remediate` | 3+n | Yes | varies | High |\n| 15 | `investigate_alert` | 4 (8 with `deep_dive`) | Checkpoint | monitor, aria | Low |\n\n---\n\n## Orchestrated Skills (13)\n\nPilot does not call VMware APIs directly. It delegates to these skills. Two different\nnumbers matter here, and they are not the same thing:\n\n- **Skill tools** — everything that skill exposes over MCP, all callable by the agent\n when it dispatches a step.\n"},{"path":"references/cli-reference.md","content":"# CLI Reference — vmware-pilot\n\nThe `vmware-pilot` CLI is a **launcher, not a second interface to workflows**. It starts the\nMCP server and reports its version — nothing else. Every workflow operation (design, plan,\nrun, approve, rollback, cancel) is performed via MCP tool calls through an AI agent or MCP\nclient.\n\n---\n\n## Commands\n\n| Command | Description |\n|---------|-------------|\n| `vmware-pilot mcp` | Start the MCP server on stdio transport |\n| `vmware-pilot version` | Print the installed version |\n| `vmware-pilot --help` | Show usage |\n\n## MCP Server Launch\n\n```bash\n# Recommended: installed entry point, never touches the network\nuv tool install vmware-pilot==1.12.0\nvmware-pilot mcp\n\n# Fallback: uvx re-resolves against PyPI each start and fails behind a\n# TLS-inspecting corporate proxy — set UV_NATIVE_TLS=true if you must use it\nuvx --from vmware-pilot==1.12.0 vmware-pilot-mcp\n```\n\nThe server runs on **stdio** transport and exposes 13 MCP tools (4 read, 9 write).\n\n---\n\n## MCP Tool Reference\n\n### Discovery Tools\n\n#### get_skill_catalog\n\nGet available skills and tools for workflow design.\n\n```\nget_skill_catalog()\n→ {aiops: {tools: {...}}, monitor: {...}, nsx: {...}, ...}\n```\n\n#### list_workflows\n\nList built-in and custom templates, plus active workflows.\n\n```\nlist_workflows()\n→ {templates: [...], active_workflows: [...]}\n```\n\n### Design Tools\n\n#### design_workflow\n\nCreate a draft workflow from natural language description.\n\n```\ndesign_workflow(\n goal=\"Migrate app01 to new network with firewall\",\n constraints=\"approval before destructive steps\"\n)\n→ {workflow_id: \"wf-...\", state: \"draft\", next_step: \"...\"}\n```\n\n#### update_draft\n\nEdit a draft workflow's name, description, or steps.\n\n```\nupdate_draft(\n workflow_id=\"wf-...\",\n name=\"app_migration\",\n steps=[{action: \"...\", skill: \"...\", tool: \"...\", params: {...}}]\n)\n→ {workflow_id: \"wf-...\", steps: [...]}\n```\n\n#### confirm_draft\n\nFinalize a draft workflow for execution (DRAFT -> PENDING).\n\n```\nconfirm_draft(\n workflow_id=\"wf-...\",\n save_as_template=True\n)\n→ {workflow_id: \"wf-...\", state: \"pending\"}\n```\n\n### Execution Tools\n\n#### plan_workflow\n\nCreate a workflow from a built-in or custom template.\n\n```\nplan_workflow(\n workflow_type=\"clone_and_test\",\n params={target_vm: \"db01\", change_spec: {memory_mb: 32768}}\n)\n→ {workflow_id: \"wf-...\", steps: [...]}\n```\n\nAvailable types: `clone_and_test`, `incident_response`, `plan_and_approve`, `compliance_scan`,\n`network_segment_setup`, `vks_cluster_deploy`, `rolling_restart`, `capacity_expansion`,\n`disaster_recovery`, `patch_deployment`, `storage_expansion`, `baseline_capture`,\n`baseline_audit`, `baseline_remediate`.\n\n#### create_workflow\n\nCreate a custom workflow directly from a step list. Refused — nothing saved —\nif any destructive or unclassifiable step has no `require_approval` step before\nit; the error names each step and the gate to insert.\n\n```\ncreate_workflow(\n name=\"quick_restart\",\n description=\"Restart with health check"}],"languages":[],"docsSourceLabel":"CLAWHUB","editorialOverview":null,"editorialQuality":{"score":100,"threshold":65,"status":"thin","wordCount":2161,"uniquenessScore":37,"reasons":["uniqueness-below-45"]}},"media":{"evidence":{"source":"no-media","verified":false,"confidence":"low","updatedAt":"2026-10-09T15:08:30.490Z","emptyReason":"No screenshots, media assets, or demo links are available."},"primaryImageUrl":null,"mediaAssetCount":0,"assets":[],"demoUrl":null},"ownerResources":{"evidence":{"source":"unclaimed","verified":false,"confidence":"low","updatedAt":"2026-10-09T15:08:30.490Z","emptyReason":"This page has not been claimed by the agent owner."},"hasCustomPage":false,"customPageUpdatedAt":null,"customLinks":[],"structuredLinks":{"docsUrl":null,"demoUrl":null,"supportUrl":null,"pricingUrl":null,"statusUrl":null},"customPage":null},"relatedAgents":{"evidence":{"source":"protocol-neighbors","verified":false,"confidence":"medium","updatedAt":"2026-10-09T17:29:18.576Z","emptyReason":null},"items":[{"id":"b917f68a-ebff-438e-84f8-3f4b2494c0bc","entityType":"agent","canonicalPath":"/agent/activepieces-activepieces","slug":"activepieces-activepieces","name":"activepieces","description":"AI Agents & MCPs & AI Workflow Automation • (~400 MCP servers for AI agents) • AI Automation / AI Agent with MCPs • AI Workflows & AI Agents • MCPs for AI Agents","url":"https://github.com/activepieces/activepieces","homepage":"https://www.activepieces.com","source":"GITHUB_REPOS","protocols":["OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-04-15T02:22:12.426Z","createdAt":"2026-02-25T03:38:12.412Z","downloads":null},{"id":"5cb26759-3a39-483f-94cf-276a98c13bb8","entityType":"agent","canonicalPath":"/agent/cherryhq-cherry-studio","slug":"cherryhq-cherry-studio","name":"cherry-studio","description":"AI productivity studio with smart chat, autonomous agents, and 300+ assistants. Unified access to frontier LLMs","url":"https://github.com/CherryHQ/cherry-studio","homepage":"https://cherry-ai.com","source":"GITHUB_REPOS","protocols":["MCP","OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-04-11T14:38:40.986Z","createdAt":"2026-02-25T03:38:19.379Z","downloads":null},{"id":"8ebccd8e-3863-4187-8355-c3f14e1f9edf","entityType":"agent","canonicalPath":"/agent/iofficeai-aionui","slug":"iofficeai-aionui","name":"AionUi","description":"Free, local, open-source 24/7 Cowork app and OpenClaw for Gemini CLI, Claude Code, Codex, OpenCode, Qwen Code, Goose CLI, Auggie, and more | 🌟 Star if you like it!","url":"https://github.com/iOfficeAI/AionUi","homepage":"https://www.aionui.com","source":"GITHUB_REPOS","protocols":["MCP","OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-04-10T18:48:31.762Z","createdAt":"2026-02-25T03:38:16.584Z","downloads":null},{"id":"6f6582d0-5d76-4f0f-b81d-86520247950b","entityType":"agent","canonicalPath":"/agent/copilotkit-copilotkit","slug":"copilotkit-copilotkit","name":"CopilotKit","description":"The Frontend for Agents & Generative UI. React + Angular","url":"https://github.com/CopilotKit/CopilotKit","homepage":"https://docs.copilotkit.ai","source":"GITHUB_REPOS","protocols":["OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-03-25T09:50:57.846Z","createdAt":"2026-02-25T03:39:14.617Z","downloads":null}],"links":{"hub":"/agent","source":"/agent/source/clawhub","protocols":[{"label":"OpenClaw","href":"/agent/protocol/openclew"}]}}}