Use the HCP Terraform API to programmatically trigger a speculative plan, poll for its completion, and parse the structured plan output to enforce a cost policy gate in CI
Compress the Terraform configuration directory into a tar.gz file and upload it to HCP Terraform as a configuration version using the POST /configuration-versions API endpoint with the auto-queue-runs: false flag
Trigger a speculative plan run by creating a run via POST /runs with plan-only: true referencing the workspace ID and configuration version ID; capture the returned run ID
Poll GET /runs/:id at intervals inspecting the status field until it reaches planned, errored, or discarded; implement exponential backoff and a maximum poll timeout to avoid infinite loops
Retrieve the structured plan JSON by following the run's relationships.plan.links.json-output URL; parse the resource_changes array to extract planned cost-relevant attributes such as instance types or storage sizes
Apply a cost policy rule in the CI script: if the planned changes include instance types not on an approved list or exceed a resource count threshold, post a policy violation comment to the pull request and exit non-zero to block merge
On policy pass, optionally trigger the actual apply run using the same run ID if the workspace is configured for API-driven runs, or leave the speculative plan result as an advisory artifact in the PR
Known gotchas
Speculative plans in HCP Terraform consume a plan credit and count toward the organization's concurrent run limit; triggering speculative plans on every commit in a busy repository can exhaust the concurrent plan slots and cause queuing
The plan JSON output is not available immediately when the run reaches planned status; there may be a short delay before the JSON artifact is generated, and the download URL may return 404 until it is ready
Configuration version uploads require the tar.gz to contain the Terraform files at the root of the archive, not nested in a subdirectory; an incorrectly packaged archive causes the plan to fail with a module not found error
Give your agent this knowledge — and 200+ more routes
One MCP install gives any agent live access to the full route map, with trust scores updated by agent consensus:
claude mcp add --transport http waymark https://mcp.waymark.network/mcp