opencode-ansible: Agent-Native Infrastructure as Code with OpenCode

The Infrastructure Gap in Agentic Coding

AI coding agents have transformed how we write application code. They scaffold projects, implement features, fix bugs, and refactor with increasing reliability. But there's a domain where most agents still struggle: infrastructure management.

The reason is straightforward. Application codebases have well-understood conventions — TypeScript projects follow src/, frameworks dictate file locations, and linters enforce formatting. Infrastructure repositories, by contrast, are idiosyncratic. Every DevOps engineer has their own Ansible style, their own variable naming, their own role structure. An AI agent dropped into an unfamiliar Ansible repo has no way to infer whether variables go in defaults/main.yml or vars/main.yml, whether tasks use name: with a colon or without, or whether the convention is one role per playbook or many.

opencode-ansible solves this by providing a agent-native infrastructure skeleton — a public Ansible repository structured specifically for AI-first operations.

Architecture

The repository is organized around three layers of agent interaction:

Layer 1: The Agent Contract

Two files define how agents interact with the repository:

AGENTS.md — The agent context contract. It states the project overview, operating principles (declarative over imperative, idempotent operations, agent-friendly YAML), the complete role structure convention, task naming requirements with examples, and the "making changes" protocol that agents must follow. An agent entering the repository reads this file first.

SKILL.md — An OpenCode skill definition that loads automatically when the agent detects it's working in an Ansible repository. It provides capability documentation, quick commands, and links to available scripts.

Layer 2: The Execution Structure

opencode-ansible/
├── .opencode/agents/         # Three agent roles
│   ├── sysadmin.yaml         # Day-to-day operations
│   ├── deployer.yaml         # Application deployment
│   └── security.yaml         # Security posture
├── inventory/
│   ├── hosts.yml             # Host definitions
│   └── group_vars/           # Hierarchical variables
├── roles/                    # Reusable roles
│   ├── sysctl/               # Kernel tuning
│   ├── docker/               # Docker engine
│   └── ...                   # User-defined roles
├── playbooks/
│   ├── site.yml              # Master playbook
│   ├── bootstrap.yml         # Initial host setup
│   ├── security.yml          # Firewall + SSH hardening
│   ├── monitoring.yml        # Prometheus/node_exporter
│   └── docker.yml            # Docker deployment
├── role-skeletons/           # Scaffold templates
│   ├── config-deploy/        # Config file deployment
│   ├── docker-compose-service/ # Docker Compose services
│   ├── systemd-wrapper/      # Systemd service units
│   ├── pip-package/          # Python package installation
│   └── sysctl-tune/          # Kernel parameter tuning
├── scripts/
│   ├── new-role              # Scaffold new roles
│   └── validate              # Lint + syntax check
├── AGENTS.md
├── SKILL.md
├── Makefile
└── ansible.cfg