# Zero-Host-Dependency Orchestration with Docker & Makefile Agent Skill

## The Chaos of Ambient Host Dependencies

How many times have you onboarded a new developer—or prompted an autonomous AI coding assistant (Claude Code, Gemini/Antigravity, Cursor, Codex)—only to encounter these classic roadblocks?

*   *"You need Node v22.1.0, but your machine has v18.14.0."*
    
*   *"The test suite failed because Chromium or Xdebug isn't installed on the host."*
    
*   *"The AI agent started executing random, ad-hoc npm/pip/composer scripts and created files with root permissions."*
    
*   *"The production Dockerfile is running as root and shipping a full Debian OS with compilers and shell access."*
    

The root cause is relying on **ambient host dependencies**. When your project assumes that runtimes, packages, linters, and databases are scattered across individual developer laptops, reproducibility disappears and AI agents struggle to execute commands reliably.

To eliminate this friction once and for all, I open-sourced [`docker-and-orchestration`](https://github.com/racastellanosm/agent-skills/tree/main/skills/docker-and-orchestration), a canonical agent skill adhering to the [Agent Skills Open Specification (`agentskills.io`)](https://agentskills.io) and distributed via [skills.sh](https://skills.sh).

* * *

## 🛡️ The Core Invariant: Zero Host Dependencies

The philosophy behind this skill is uncompromising:

> **The host machine requires ONLY Docker (with Compose) and GNU Make.**  
> 100% of runtimes (Bun, Node, PHP, Go, Python), package managers, linters, test runners, and database CLIs MUST execute inside isolated, reproducible containers.

![](https://cdn.hashnode.com/uploads/covers/5f86373176870f43aa09d042/0340e338-73a3-443e-9fc8-4a8b01c8dc8f.jpg align="center")

* * *

## 🏛️ The 3 Architectural Pillars

### 1\. Makefile as the Universal Orchestration Layer

Instead of having human engineers or AI agents remember complex, brittle shell commands, the `Makefile` acts as the single source of truth for all workflows:

```bash
make help             # Self-documenting, formatted command menu
make install          # Containerized dependency installation
make dev              # Hot-reloading development environment (docker-compose)
make test             # Ephemeral unit & integration test runners
make check            # Pre-commit pipeline (typecheck + lint + audit + test)
make build            # Multi-stage production container build
```

#### ⚡ The Ephemeral Runner Pattern

For static analysis, typechecking, and unit tests, the skill enforces ephemeral runners that spin up, execute, and destroy containers immediately with zero lingering resources:

```shell
DOCKER_RUN := $(COMPOSE_DEV) run --rm --no-deps

test: ## Runs unit tests inside ephemeral container
	$(DOCKER_RUN) api bun run test

lint: ## Runs linters inside ephemeral container
	$(DOCKER_RUN) api bun run lint
```

* * *

### 2\. Multi-Stage Hardened Containers (Base ➔ Test ➔ Distroless)

The skill guides agents to craft secure, 3-stage Dockerfiles:

1.  **Stage 1 (Base & Deps Builder):** Caches manifests (`package.json`, `bun.lock`, `go.mod`), enforces frozen lockfiles, and passes `--ignore-scripts` to block malicious supply-chain lifecycle hooks.
    
2.  **Stage 2 (Test & Dev Runner):** Equipped with test toolchains (e.g. Playwright, headless Chromium, Xdebug) and runs as a dedicated non-root user.
    
3.  **Stage 3 (Production Distroless / Scratch):** Copies *only* the compiled application binary or runtime bundle into a Distroless/Scratch image. Zero OS package managers, zero shell (`/bin/sh`), and strict non-root execution (`USER 1000:1000`).
    

* * *

### 3\. Split Docker Compose Topology

Never pollute production definitions with local development conveniences. The skill enforces a clean two-tier compose strategy:

*   `docker-compose.yml` **(Base):** Clean, production-aligned service declarations, networking, and environment configurations.
    
*   `docker-compose.dev.yml` **(Overrides):** Local hot-reload volume mounts (`./:/app`) and debugging ports (e.g., V8 inspector or Xdebug 9003).
    

The `Makefile` merges both files deterministically:

```shell
COMPOSE     := docker compose -f docker-compose.yml
COMPOSE_DEV := docker compose -f docker-compose.yml -f docker-compose.dev.yml
```

* * *

## 🔒 Built-in Security & Vulnerability Auditing

Security is treated as a first-class citizen with **Docker Scout** and supply-chain auditing built directly into the workflow:

*   **Non-root enforcement:** Containers never run as UID 0 in runtime.
    
*   **Supply-chain locking:** `--ignore-scripts` and frozen lockfiles are mandatory.
    
*   **Automated CVE Scanning:** A dedicated `make audit-image` target scans production images for Critical and High vulnerabilities before deployment:
    
    ```shell
    docker scout cves --only-severity critical,high <image-name>:latest
    ```
    

* * *

## 🚀 How It Works with QRSPI in Practice

When paired with the [`qrspi-methodology`](https://github.com/racastellanosm/agent-skills/tree/main/skills/qrspi-methodology) skill, AI coding assistants become unstoppable:

1.  You give a natural prompt: *"Build a key-value caching service with TTL from scratch."*
    
2.  **QRSPI** triggers to structure the 5-phase engineering protocol (interrogating requirements, mapping blast radius, establishing living ADRs, and pausing at each turn).
    
3.  **Docker & Orchestration** triggers to scaffold the entire infrastructure with zero host dependencies: a hardened multi-stage Dockerfile, split compose configuration, and an ergonomic Makefile.
    

* * *

## 📦 Universal Installation via `skills.sh`

Install the skill into your project or globally on your system in seconds:

```bash
# Add to current workspace
npx skills add racastellanosm/agent-skills --skill docker-and-orchestration

# Or install all engineering skills in the catalog
npx skills add racastellanosm/agent-skills

# Install globally for all projects on your machine
npx skills add racastellanosm/agent-skills -g
```

### 🤖 Multi-Harness Interoperability

Works out of the box with **Claude Code**, **Google Gemini & Antigravity**, **OpenAI Codex**, **Cursor**, **Cline**, and **OpenCode**.

* * *

## 💡 Explore the Code & Contribute

Both skills are 100% open-source under the MIT license:

*   🌟 **GitHub Repository:** [github.com/racastellanosm/agent-skills](https://github.com/racastellanosm/agent-skills)
    
*   📖 **Skill Documentation:** [skills/docker-and-orchestration](https://github.com/racastellanosm/agent-skills/tree/main/skills/docker-and-orchestration)
    
*   📦 **Registry:** [skills.sh/racastellanosm/agent-skills](https://skills.sh/racastellanosm/agent-skills)
    

How do you manage container orchestration and developer tooling in your team? Let me know in the comments below!