Ship with an agent
How a coding agent reads AGENTS.md and writes an app's infra/ folder and deploy workflow from these modules.
Kaizen apps go from code to a running AWS deployment without an engineer writing Terraform by hand. The repository ships AGENTS.md, a playbook for a coding agent. An engineer points the agent at it from the app's repository, answers four questions, and reviews a pull request that holds the whole infrastructure stack.
What the agent produces
infra/
provider.tf # Terraform version, AWS provider, S3 state backend with the app's own key
locals.tf # every name and size for the stack, no variables
main.tf # data lookups, module calls, secrets, migration task
outputs.tf # alb_dns, plus subnet and security group IDs for migrations
.github/workflows/
terraform.yml # plan on every pull request, apply on merge to mainHow it works
Point the agent at the playbook. From the app repository, tell the agent to follow AGENTS.md in terraform-modules. The playbook covers the two Kaizen prototype accounts, kaizen-ext and kaizen-int, which already have a shared VPC, a state bucket, and a wildcard certificate.
Answer the interview. The agent inspects the repository first, then asks you to confirm four things, each with its own recommendation: the app name, the AWS account, whether the app needs Postgres and migrations, and the Dockerfile and container port.
The agent reads before it writes. It reads the module docs, copies the layout of the reference app juniper, and looks up the latest release tag with git ls-remote. Every module source pins that tag. It never uses ?ref=main.
The agent writes the stack. main.tf looks up the shared VPC by tag, then calls ecr, alb, ecs-cluster, ecs-service, and, when the app needs a database, rds-postgres. It composes the database URL into an SSM SecureString and adds a task definition for migrations. Prototype accounts get small, low cost settings: one task, a db.t4g.micro database, and no Multi-AZ.
The agent adds CI. It copies a GitHub Actions workflow that plans on every pull request, posts the plan as a comment, and applies on merge. The workflow signs in to AWS with GitHub OIDC, so the repository holds no AWS keys.
You run the manual steps. The agent prints, and does not run, the steps that touch real systems: store the database password in SSM, confirm the repository can read the module fetch secrets, open the pull request, add the Cloudflare DNS record, and push the first image.
The agent never deploys
The playbook forbids the agent from running terraform apply, terraform destroy, or any AWS command that changes state. Infrastructure goes live when a person merges the pull request.
What the generated code looks like
The service block wires four modules together in about twenty lines. This excerpt is trimmed from examples/full-stack-app/main.tf, the generic version of what the agent writes.
module "ecs_service" {
source = "git::ssh://git@github.com/the-kaizen-labs/terraform-modules.git//ecs-service?ref=v1.7.0"
environment = local.environment
app_name = local.app_name
cluster_name = module.ecs_cluster.cluster_name
vpc_id = data.aws_vpc.main.id
private_subnet_ids = data.aws_subnets.private.ids
container_image = "${module.ecr.repository_url}:latest"
container_port = local.container_port
target_group_arn = module.alb.target_group_arn
alb_security_group_id = module.alb.alb_security_group_id
container_secrets = [
{ name = "DATABASE_URL", valueFrom = aws_ssm_parameter.database_url.arn },
]
ssm_parameter_arns = [aws_ssm_parameter.database_url.arn]
tags = local.tags
}