Kumoss
prerelease Prerelease stable Latest
↑↓ navigate · ↵ select · esc close
Kumoss
Kumoss
prerelease Prerelease stable Latest

Generate infrastructure

Turn a natural-language request into validated Terraform code, reviewed as a plan and report before you apply it.

Generate Infrastructure is the default mode in the Kumoss web application. It turns a natural-language request into validated Terraform code on a new branch, with a plan, a report, and optional compliance checks. This guide describes what happens during a generate round, what it produces, and its limits.

Prerequisites

  • The developer operation role, assigned per user and checked by the API on every request. See Roles and permissions for the complete role matrix.

  • A repository URL, the target cloud, a scope id, and request text, as covered in Make a request. The IaC path is optional.

Use case

Create or modify Terraform code from a description: "add a private storage bucket for application logs", "open port 443 on the web security group", "rename the staging subnet".

Workflow

  1. Filtering. A small-model chain with read-only workspace tools classifies the request. A change request proceeds. A question is answered in the conversation and the round ends uncompleted. An out-of-scope, prohibited, or ambiguous request is declined with an explanation and the round ends uncompleted.

  2. Prompt composition. The compositor selects the relevant resource prompts and abbreviations for the target cloud from Phoenix, in two passes (see Customize prompts).

  3. Generate and validate loop. The main model edits files in the workspace; changed files are uploaded as code-change artifacts and committed to the session branch. The target generator picks the Terraform targets for this round from the diff history. The IaC sidecar runs init, validate, and plan -out session.plan with those targets. Validation feedback is fed back to the model for up to orchestration.max_validation_iteration attempts (5 in the shipped config.yaml) before the round fails with Validation loop exceeded.

  4. Drift pre-check. Two detect-and-reconcile iterations run on the session targets. The first reads its drift out of the plan artifact the previous step left in the workspace rather than planning again. Drift that corresponds to the session’s own changes is filtered out; anything else is reconciled so that the plan reflects only intended changes. Operations covered by the cloud’s drift_exceptions rules are then dropped before anything is remediated, and logged.

  5. Report. The main model turns the plan into a JSON report with a change summary (create, update, delete, recreate), detailed changes, an impact banner (low, medium, high), and cost estimates.

  6. Compliance check (when orchestration.enable_compliance_checker is true). A small-model auditor checks the plan against the rules in the general-compliance-report prompt. The auditor judges the plan against the session’s first request, not the current round’s, so in a follow-up round scope_exceeded and scope_incomplete are measured against the original request.

  7. Lock decision. The session is locked when the compliance check fails or, with orchestration.block_on_high_impact, when the impact banner is high. A clean round clears an earlier lock. Notifications are sent for both conditions when the notifications sidecar is enabled.

  8. Pin. The validated workspace, including the plan file, becomes the session’s pinned plan, replacing any earlier pin.

What generate produces

  • Inspects existing IaC and state. Yes: the generator reads the repository, and plan runs against the configured backend state.

  • Targets. Generated by the target generator chain from the diff history; no manual target list is accepted.

  • Artifacts and reports. Code-change files, plan text, drift pre-check reports, a generate JSON report, a pushed branch, and a pull-request link once you create one.

  • Plan pinned. Yes.

Apply, pull requests, and locks

After reviewing the report you can create a pull request, merge it, and apply, as covered in Merge and apply. Apply and merge are refused with 409 while the lock is set; a reviewer with the appropriate panel role can unlock the session, or another generate round that passes cleanly clears the lock.

Example

Repository https://git.example.invalid/platform/demo-iac.git, cloud aws, scope 123456789012, IaC path envs/dev. Request: "Create a private S3 bucket named demo-platform-logs with versioning and default encryption for application logs." The round produces s3_logs.tf on branch Kumoss/2026-09-11_101500, a plan with one resource to create, a report with a low impact banner, and a passing compliance check. You create the pull request, merge it, and apply.

Limitations

  • Validation and plan run against the credentials in services/iac/.env; missing cloud credentials surface as engine errors in the session, not at startup.

  • Every cloud scope needs its seven guideline prompts in Phoenix; a missing one aborts the round with Prompt not found. See Guideline prompts for the list every cloud scope must provide.

  • A high impact or a failed compliance check does not stop the round, it locks the session; review the report before asking for an unlock.

Next steps