scaffold-stack

You are helping the user create a new stackql-deploy stack for provisioning cloud infrastructure.

Input: $@

Follow these steps in order.

Step 1 - Understand the requirements

Parse the user's input to determine:

• Which cloud provider(s) are involved (google, aws, azure, etc.)
• What resources need to be provisioned
• Any specific configuration requirements mentioned

If the input is vague, ask clarifying questions:

• Which cloud provider?
• What region/zone?
• What specific resources? (e.g., VPC, subnets, compute instances, storage buckets)
• Any naming conventions or project/subscription context?

Step 2 - Check StackQL is installed and providers are available

command -v stackql

If not found, delegate to /stackql-skills:install-stackql.

Check if the required provider is pulled:

stackql exec "SHOW PROVIDERS;" --output json

If not, delegate to /stackql-skills:pull-provider <provider>.

Step 3 - Discover resource schemas

For each resource the user wants to provision, get the schema:

stackql exec "DESCRIBE <provider>.<service>.<resource>;" --output json
stackql exec "SHOW METHODS IN <provider>.<service>.<resource>;" --output json

Use this to understand:

• What fields are available for INSERT (createorupdate methods)
• What fields are required
• What identifiers are needed for SELECT (to verify deployment)

Step 4 - Determine stack directory

Ask the user where to create the stack, or use a sensible default:

<stack-name>/
  stackql_manifest.yml
  resources/
    <resource1>.iql
    <resource2>.iql
    ...

Step 5 - Generate the stackql_manifest.yml

Create the manifest file following the stackql-deploy format:

version: 2
name: <stack-name>
description: <description>
providers:
  - <provider>
globals:
  - name: global_tags
    value:
      managed_by: stackql-deploy
      environment: "{{ environment }}"

resources:
  - name: <resource-name>
    description: <resource description>
    props:
      - name: <prop-name>
        value: <value or "{{ var }}">
    exports:
      - <exported-field>

Key manifest conventions:

• Use Jinja2 template syntax ({{ var }}) for parameterized values
• Group related resources logically
• Define exports for values that downstream resources need
• Use globals for shared configuration like tags and environment

Step 6 - Generate .iql resource files

For each resource in the manifest, create the corresponding .iql files. Each resource typically needs:

resources/<resource-name>.iql - Contains the StackQL queries for build, test, and teardown:

/*+ build */
INSERT INTO <provider>.<service>.<resource> (
  <field1>,
  <field2>,
  ...
)
SELECT
  '{{ prop1 }}',
  '{{ prop2 }}',
  ...
;

/*+ test */
SELECT count(*) as count
FROM <provider>.<service>.<resource>
WHERE <identifier> = '{{ resource_name }}'
AND <required_param> = '{{ param }}';

/*+ teardown */
DELETE FROM <provider>.<service>.<resource>
WHERE <identifier> = '{{ resource_name }}'
AND <required_param> = '{{ param }}';

Use the schema from Step 3 to populate the correct field names and required parameters.

Step 7 - Generate a variables file (optional)

If the stack uses template variables, create an example variables file:

vars/dev.jsonnet or vars/dev.json:

{
  "environment": "dev",
  "project": "my-project",
  "region": "us-central1"
}

Step 8 - Report

Summarize what was created:

• List all files generated
• Explain the stack structure
• Provide the commands to deploy:

To deploy this stack:

pip install stackql-deploy  # if not installed
stackql-deploy build <stack-name> dev --env-file vars/dev.json

To test the deployment:

stackql-deploy test <stack-name> dev --env-file vars/dev.json

To tear down:

stackql-deploy teardown <stack-name> dev --env-file vars/dev.json

Suggest reviewing the generated files and customizing values before deploying.