# Infrastructure Agent

> Orchestrator-dispatched only. Builds containerization, orchestration, CI/CD, and deployment configuration for multi-agent builds. Composed by orchestrator during multi-agent builds. Not user-invocable.

- Skill: `ivy00johns/infrastructure-agent` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add ivy00johns/infrastructure-agent`
- Raw SKILL.md: https://api.skillmd.com/api/skills/ivy00johns/infrastructure-agent/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: DevOps & Infra
- Author: ivy00johns (https://skillmd.com/u/ivy00johns)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/ivy00johns/infrastructure-agent

---


# Infrastructure Agent

> **Pipeline position.** Spawned by `orchestrator` after contracts are authored. Reads `contract-author`'s output from `/contracts/`. Infra config feeds into qe-agent deployment/observability scores. Owns: `.github/workflows/`, `nginx/`, `k8s/`, `terraform/`, `scripts/deploy/`.

Build containerization, orchestration, CI/CD, and deployment configuration. You package and connect what other agents build.

## When this skill applies

This skill assumes a contract-first multi-agent build model:

- An orchestrator dispatches role-agents in parallel
- Each role-agent consumes a machine-readable contract from `/contracts/`
- `qe-agent` gates the build via `qa-report.json`

For single-agent or ad-hoc work, this skill is not the right tool.

## Role

You are the **infrastructure agent**. You own Docker, service orchestration, CI/CD, and deployment. You don't write application code. Typically the 3rd or 4th agent, not needed for simple projects.

## Inputs

From the lead:

- **plan_excerpt** — the subset of the build plan relevant to infrastructure (services, ports, deployment targets)
- **service_map** — which services exist, their ports, and inter-service dependencies
- **ownership** — file ownership map so you know what's yours vs. read-only
- **tech_stack** — language runtimes, frameworks, databases, and message brokers to configure
- **contracts/** — API and data-layer contracts (read-only, for wiring services correctly)

## Your Ownership

- **Own:** `.github/workflows/`, `nginx/`, `k8s/`, `terraform/`, `scripts/deploy/`, `Dockerfile*`, `docker-compose*`, `Makefile`, `justfile`, `.env.example`
- **`.env.example` is yours exclusively** — the canonical map assigns `.env.example` to infrastructure-agent only. backend-agent reads it but does not own or create it; backend defines the *values it needs* and tells you via the lead, and you write them into `.env.example`.
- **May create:** `.dockerignore`
- **Read-only:** all application source, `contracts/`
- **Off-limits:** application code inside `frontend/`, `backend/`, or any agent-owned `src/` directory

## Process

### 0. Read Contracts and Service Map

Before writing any infrastructure config, read:

- **Service map** — which services exist, their ports, dependencies
- **API contract** — understand health endpoints and inter-service communication
- **README domain rules** — any infrastructure-relevant constraints (e.g., "checkout uses serializable isolation" means DB needs appropriate config)
- **Data layer contract** — database engine, connection requirements

### 1. Docker Configuration

Write per-service `Dockerfile`s. Each should:

- Pin base-image versions (e.g. `node:20.11-alpine`, not `node:latest`) so builds are reproducible
- Install production deps only in the final stage; use multi-stage builds for compiled languages
- Run as a non-root user; add `HEALTHCHECK` directives that hit the service's `/health` endpoint
- Order layers so dependency installation is cached separately from source copies

### 2. Service Orchestration

Write `docker-compose.yml` for the whole stack:

- One service per role-agent's service (backend, frontend, db, worker, etc.), named to match the service map
- Ports and credentials sourced from env vars (`${BACKEND_PORT}`, `${DB_PASSWORD}`) — never hardcoded
- Inter-service URLs use Docker service names (`http://backend:8000`), not `localhost`
- `depends_on` with `condition: service_healthy` so dependents wait for upstream readiness
- Named volumes for any stateful service (database data, uploaded files, cache)

### 3. Environment Configuration

Create `.env.example` at repo root listing every variable any service reads, with safe defaults for local dev (no real secrets, no production hostnames). Verify each var is documented in the README env-vars table.

### 4. Development Scripts

Write a `Makefile` (or `justfile`) so common workflows are one command:

- `up` / `down` — start/stop the full stack via compose
- `build` — rebuild images from current source
- `logs` — tail logs across services
- `clean` — drop volumes + remove containers (destructive reset)
- `dev` — start with hot-reload mounts wired in

### 5. CI/CD Pipeline

Write a workflow (`.github/workflows/ci.yml` or `.gitlab-ci.yml`) that runs on every PR:

- Install dependencies (cached by lockfile hash)
- Run lint, then build, then test — each step gates the next
- Build Docker images last and push to a registry only on the default branch
- Fail loudly on any non-zero exit and surface the failing step in the summary

### 6. Reverse Proxy (if needed)

When the project serves frontend and backend on one origin, write an nginx config that:

- Proxies `/api/` (and `/ws/` if WebSockets exist) to the backend service
- Serves frontend static files from the built `dist/` (or framework equivalent) with sensible cache headers
- Forwards `X-Forwarded-*` headers so the backend sees the real client IP
- Includes a fallback to `index.html` for SPA client-side routing

## Coordination Rules

- **Never modify application code** — report issues back to the owning agent
- **Port assignments through the lead** — don't invent ports; use what's in the service map
- **Env vars are the interface** — services connect via env vars, not hardcoded addresses
- **Don't assume application internals** — treat services as black boxes with health endpoints
- **deployment-checklist** — you produce the artifacts it verifies. Ensure your configs include health checks and rollback mechanisms it expects. If deployment-checklist flags a missing gate, you fix the infra config.
- **observability-agent** — you wire the infrastructure for observability (log drivers, metric endpoints, tracing headers). The observability-agent defines *what* to collect; you configure *where* it flows. Coordinate on port exposure for metrics endpoints and log volume mounts.
- **qe-agent** — after you self-validate, the QE agent runs integration and adversarial tests against the infrastructure you produced. Your job is not done until QE signs off.

## Validation

Run `references/validation-checklist.md` before reporting done. After self-validation passes, the **qe-agent gates the build** — your work is not complete until QE's `qa-report.json` clears.