Stack tools

Overview

A stack is a bundle of workflows deployed in a defined order. Find existing stacks with search_stacks, then use these tools to configure them or run their actions.

get_stack_run is read-only. The four tools that create, update, run or delete a stack are write tools, see Availability.

create_stack

Creates a stack and its workflows from a pinned stack template in your library. Creating the stack stores its configuration; deployment starts separately with create_stack_run.

Input	Description
Workflow group (required)	An existing group, unless you explicitly ask for a new one to be created.
Name (required)	1–100 characters. Its derived id must be unique within the group.
Stack template (required)	A pinned revision of an IAC_GROUP template, found with the template search tools. This tool doesn't create stacks directly from git.
Description, tags, context tags	Description up to 512 characters, up to 10 tags.
Cloud connector	Applied to every workflow being created, unless a per-workflow setting overrides it. Omit to keep the template's settings.
Environment variables	Up to 20, as plain values or vault-secret references. Added or replaced by name over each workflow's template variables.
Per-workflow settings	Names, input values, connectors and environment variables for selected workflows in the template. Per-workflow connector and variable settings take precedence over the stack-wide settings.

Input values are merged with the template's defaults and stored values. Unknown input keys are rejected. Inputs wired to another workflow's outputs can't be replaced with a literal value; another reference is allowed.

The stack inherits the template's action definitions and dependencies. If creation fails part-way, a partial stack can remain because the platform doesn't roll back earlier writes. Check the stack and its workflows before retrying with the same name.

Example prompts

"Create a staging-web stack in the engineering group from revision 2 of our three-tier-app stack template, using aws-staging."

update_stack

Changes an existing stack's settings. Pass only the fields to change.

Setting	How it changes
Display name	Changes the name shown in the dashboard. The stack's id stays the same.
Description and tags	Replace the stored value. Send the complete tag list.
Context tags	Merge by key. Set a key to null to remove it.
Cloud connector	Changes the stack-level connector. Individual workflows' own connector settings aren't changed.
Environment variables	Add or replace by name in the stack-level list. Individual workflows' own variables aren't changed.
Schedules	Replace the whole list, up to 10. An empty list clears every schedule. Each schedule names an action in the stack.
Actions	Replace the full definition of each named action. Actions you don't name are kept.

An action defines which workflows run, in what order, and which workflows each one depends on. If a step's dependencies are omitted, it waits for the previous step in the list. An empty dependency list allows it to start without waiting for another step. Dependency names must be workflows in the same action, and cycles are refused.

Each Terraform or OpenTofu workflow step must specify plan, apply or destroy. Custom workflow steps don't take a Terraform action.

This tool doesn't upgrade the stack's template revision or change stack membership. To change one workflow's inputs, connector or variables, use update_workflow for that workflow inside the stack.

The update response contains the changed fields, not the full stack. Fetch the stack again if you need its complete configuration.

Example prompts

"Add team=platform to staging-web and schedule its plan action every night."

"Change staging-web so its apply action runs the VPC first, then starts the database and application workflows in parallel."

create_stack_run

Runs one of a stack's actions. This executes infrastructure code for every workflow the action touches.

Your assistant must ask which action to run and confirm the stack with you. The action is required and has no default.

Input	Description
Stack and workflow group (required)	Found with search_stacks.
Action (required)	An action defined on this stack. apply and plan also have fallbacks using the stack's creation order; destroy uses its deletion order. Other action names must be defined on the stack.
Destroy confirmation	Required whenever the resolved action destroys anything, including a custom action containing a destroy step.
Schedule	Start at a future time instead of now.
Context tags	Labels for this run only. They aren't inherited from the stack.

Per-workflow inputs, connectors and environment variables can't be overridden through this tool. Change their stored settings with update_workflow before starting the stack run.

The tool returns when the action is accepted, before the workflows finish. It provides the stack run id and polling instructions for get_stack_run.

Example prompts

"Run the plan action on staging-web."

"Run the destroy action on demo-web after I confirm which workflows it will tear down."

get_stack_run

Reads a stack run's progress and the child workflow runs it has produced so far, directly from the platform rather than the search index.

Input	Description
Stack and workflow group (required)	The stack whose action was started.
Stack run id (required)	The id returned by create_stack_run, either bare or in /stackruns/<id> form.

The response includes the aggregate status, child workflow runs and a statusView. The assistant should use statusView to decide whether the run has finished, succeeded or needs human action: it checks the child runs too, since the aggregate status alone can overlook a parallel workflow that is still running, failed or waiting for approval.

• An empty child list immediately after starting can be temporary. Wait and retry.
• If a child workflow needs approval, use control_workflow_run with that child's full run id, after you choose the action and confirm it.
• To inspect one child's status or logs, use get_workflow_run or get_workflow_run_logs.
• A run started directly on one stack member with create_workflow_run has no stack run id. Follow it with get_workflow_run instead.

Example prompts

"Has the staging-web deployment finished? Show any workflow that is blocked or failed."

delete_stack

Deletes a stack's records. Deleting a non-empty stack also requires the explicit force-delete option, which removes its workflows, run history, schedules, artifacts and stored Terraform state.

This does not destroy infrastructure

Resources deployed by the workflows keep running and costing money. If they should be removed, run the stack's destroy action and wait for it to finish before deleting the records and state.

Your assistant must confirm the deletion with you, name the stack and any workflows that will be removed, and ask whether their infrastructure has already been destroyed or is deliberately being left in place.

Input	Description
Stack and workflow group (required)	Found with search_stacks.
Confirmation (required)	Your explicit go-ahead to delete the records.
Force delete	Off by default. Required to remove a stack that still contains workflows, together with those workflows.

Before a force deletion starts, the platform checks the child workflows for unsafe active runs and refuses the whole deletion if one is found. Once deletion starts, there is no rollback: if a later workflow fails to delete, earlier workflows can already be gone. The error reports a partial deletion; inspect what remains before retrying.

Example prompts

"Destroy demo-web, wait for it to finish, then delete the stack and its workflows after I confirm."