terraform-review-agent: Instructions file for Codex

AGENTS.md

Project contract for Codex / AI coding assistants. Replace [PLACEHOLDERS] per project; everything else is fixed standard.

---

1. Project

• Name: terraform-review-agent
• Goal: A reusable GitHub Actions workflow that uses a LangGraph multi-agent system to review Terraform pull requests for security, cost, and style issues, posting a single severity-ranked comment.
• Trigger: GitHub pull_request events (opened, synchronize, reopened, ready_for_review) on Terraform-file changes, via a reusable workflow consumed by other repos. Users: PR authors and reviewers. Secondary: workflow_dispatch for manual re-runs.
• Framework: LangGraph

---

2. Stack (fixed — do not change without explicit instruction)

• Python 3.13 · uv package manager · .venv only (never system Python)
• Pydantic v2 for all state, tool I/O, and config schemas
• LangGraph or LangChain
• SQLite checkpointer (langgraph-checkpoint-sqlite) if keeping state is required
• LLM providers: OpenAI, Anthropic, Google only — selectable via config
• Docker (compose) for reproducibility · structlog logging · pytest · ruff · mypy --strict

---

3. Layout

Standard LangGraph src-layout (https://docs.langchain.com/oss/python/langgraph/application-structure):

[project]/
├── AGENTS.md, README.md, .env.example, .gitignore, .python-version
├── pyproject.toml, uv.lock, langgraph.json
├── Dockerfile, docker-compose.yml, Makefile
├── src/[package_name]/
│   ├── agent.py              # exposes compiled `agent` for langgraph.json
│   ├── config.py             # Pydantic Settings (env-driven)
│   ├── llm.py                # provider factory (OpenAI/Anthropic/Google)
│   ├── utils/{state,nodes,tools,prompts}.py
│   └── persistence/checkpointer.py
├── tests/{unit,integration}/
├── data/                     # SQLite, fixtures (gitignored if dynamic)
└── scripts/                  # thin wrappers only — no business logic