What the agent does
The agent reads the repository's conventions before it writes a rule. In a module like terraform-aws-modules/terraform-aws-vpc, versions.tf requires Terraform at or above 1.0 and the AWS provider at or above 6.28, variables.tf declares two hundred and thirty-six inputs, among them enable_flow_log defaulting to false, map_public_ip_on_launch defaulting to false, manage_default_security_group defaulting to true and enable_dns_hostnames defaulting to true, and examples/ holds thirteen directories from simple to complete, each a main.tf that calls the module with source = "../../" and a tags local carrying Example, GithubRepo and GithubOrg. examples/complete/main.tf sets manage_default_security_group = true, map_public_ip_on_launch = false and enable_nat_gateway = true; examples/simple/main.tf passes only name, cidr, azs, private_subnets and tags. .pre-commit-config.yaml runs terraform_fmt, terraform_docs, terraform_tflint with a fixed rule list, and terraform_validate through pre-commit-terraform, and .github/workflows/pre-commit.yml runs that configuration at the minimum and maximum Terraform versions through the clowdhaus composite actions. Nothing evaluates a policy, and there is no policy/ directory.
It writes policies against HCL, not against a plan, because the examples need AWS credentials to plan and CI has none. Conftest's HCL parser turns each main.tf into a document where a module call appears under module.vpc, so the agent writes policy/vpc.rego with a deny rule for each statement in the prompt: a module call that sets map_public_ip_on_launch to true, one that does not set enable_flow_log to true, one whose tags lack a required key, and a warn for a call that leaves manage_default_security_group at the default without saying so. Each rule's message names the file, the module block and the fix, so a failing check reads like a review comment. The package name, the input shape and the --parser hcl2 flag are documented in a short policy/README.md.
The policies get tests of their own. policy/vpc_test.rego holds a test_ rule per deny with a small inline input that should pass and one that should fail, run with conftest verify, so a later edit to a rule cannot silently stop denying. The agent then runs conftest test --parser hcl2 --policy policy examples/*/main.tf and reads the result: with enable_flow_log off by default, the simple example and others fail the flow-log rule today, which is the point, and the pull request lists them as the current state rather than editing the examples, since examples/README.md says they show configurations and are not best practice.
Then it puts the check where the repository already runs checks. A conftest job joins .github/workflows/pre-commit.yml beside the existing ones, installing the conftest release binary with a pinned version and running verify and then test over examples/, and a repo: local hook in .pre-commit-config.yaml runs the same test command on changed .tf files so a developer sees a denial before pushing. The workflow is linted with actionlint, pre-commit run --all-files is run to confirm the new hook does not fight terraform_fmt, and the pull request opens with the failing examples named so the team can decide whether to flip the rule to warn or fix the examples.
Start it with one API call
POST https://api.phoenix.so/o/{org}/sessions with this body:
{
"agent": "claude",
"input": "Add conftest policies to this Terraform repository. Read versions.tf, variables.tf, examples/README.md, every examples/*/main.tf, .pre-commit-config.yaml and .github/workflows/pre-commit.yml first. Write policy/vpc.rego against the HCL parser input with deny rules for a module call that sets map_public_ip_on_launch to true, one that does not set enable_flow_log to true, and one whose tags lack the Example, GithubRepo and GithubOrg keys, plus a warn for a call that leaves manage_default_security_group unset; make every message name the file, the block and the fix. Write policy/vpc_test.rego with a passing and a failing case per rule and a policy/README.md with the command to run. Run conftest verify and conftest test --parser hcl2 over examples/*/main.tf and record which examples fail today; do not edit the examples. Add a conftest job to .github/workflows/pre-commit.yml with a pinned binary version and a repo local pre-commit hook that runs the same test on changed .tf files. Run actionlint and pre-commit run --all-files, then open a pull request that lists each rule, its test cases and the examples that currently fail.",
"resources": [
{
"url": "https://github.com/your-org/your-app"
}
]
}- Get an API key. In the console, open Settings, then API keys, and create a key for your org. Send it in the Authorization header as a Bearer token.
- Send the request. POST the body in request.json to https://api.phoenix.so/o/{org}/sessions, with your repository as the resources URL. The run starts in its own cloud sandbox.
- Read what came back. Follow the run on its live stream or wait for the run.completed webhook, then read the result and its trajectory.
What comes back
What comes back is a pull request that adds policy/vpc.rego, policy/vpc_test.rego and policy/README.md, adds a job to .github/workflows/pre-commit.yml, and adds a local hook to .pre-commit-config.yaml. The description holds a table of rule, severity, message and the two test cases behind it, then a list of the examples that fail each rule today with the line that triggers it, and a note that the examples were left unchanged on purpose.
The run's record keeps the conftest verify and conftest test output, the actionlint result and the pre-commit run --all-files output, so a reviewer can see every policy test passed and read the real denials for simple and the other examples before deciding what to do with them.
Before merging, a reviewer decides per failing example whether to set enable_flow_log = true there or turn that rule into a warn, and confirms the pinned conftest version in the workflow matches the one the local hook installs.
Run it on every Linear issue labelled policy
In the console, add an automation to the Project with this prompt and a linear trigger on linear.issue.labeled, filtered to the policy label and the platform team. When someone labels an issue such as "every VPC must ship flow logs and the three cost tags", the trigger puts the issue after the prompt and the run turns the rules it states into deny rules with tests. Only label changes made by a person in your Rush org fire the trigger, and the automation starts at most max_runs_per_hour runs in an hour.
From your own server, the same body goes to POST /o/{org}/sessions with the repository in resources and the issue URL beside it, read through your Linear connection, and a request_id that is a UUID v5 of the issue id, so a retried call returns the run already started rather than opening a second pull request.
The use case this job follows, with its automation and trigger: Turn a Linear label into a PR.
Why run it on Rush?
Policy code is where a typo passes silently: a Rego rule that never matches because the HCL input nests module.vpc one level deeper than the author assumed denies nothing and the check stays green. The agent runs conftest verify with a failing case per rule and then runs the policies over the repository's own thirteen examples in its sandbox, so a rule that denies nothing is caught before it reaches CI.
The commands and their output stay with the run, so the pull request can quote the exact denials the examples produce today, and the team's only decision is what to do about them.
Frequently asked questions
Why test the HCL instead of a terraform plan?
Planning the examples needs AWS credentials, which the pre-commit workflow does not have and should not need for a policy check. Conftest's HCL parser reads main.tf directly, so the rules run on every push without touching an account; a plan-based check can be added later for resource-level rules.
Will the check fail CI as soon as it is merged?
Yes, for the examples the pull request names, because enable_flow_log defaults to false and several examples do not set it. The agent leaves the examples alone and lists the failures so the team chooses between fixing them and softening the rule to warn before merging.
How are the policies kept correct over time?
policy/vpc_test.rego has a passing and a failing input per rule, and the CI job runs conftest verify before conftest test. A rule edit that stops denying its failing case breaks the build.
Does this replace tflint or checkov?
No. terraform_tflint keeps its rule list in .pre-commit-config.yaml; conftest adds rules specific to this team, such as required tag keys and flow logs, that a generic linter does not know. The two run side by side in the same workflow.