Domain knowledge for infrastructure tools - Terraform, Ansible, Docker, Proxmox

GitHub stars
7

Install

/plugin install technologies@waypoint-marketplace

Run it inside Claude Code after adding the marketplace with /plugin marketplace add poindexter12/waypoint.

Contents

Discovered from source

Skills 7

Ansible Skill

Ansible automation reference for configuration management and application deployment.

Quick Reference

# Test connectivity
ansible all -m ping
ansible <group> -m ping

# Run playbook
ansible-playbook playbook.yml
ansible-playbook playbook.yml -l <host>    # Limit to host
ansible-playbook playbook.yml --check      # Dry-run
ansible-playbook playbook.yml -vvv         # Verbose

# Tags
ansible-playbook playbook.yml --tags "deploy"
ansible-playbook playbook.yml --skip-tags "backup"
ansible-playbook playbook.yml --list-tags

# Variables
ansible-playbook playbook.yml -e "var=value"
ansible-playbook playbook.yml -e "@vars.yml"

# Ad-hoc commands
ansible <group> -m shell -a "command"
ansible <group> -m copy -a "src=file dest=/path"
ansible <group> -m apt -a "name=package state=present"

# Galaxy
ansible-galaxy collection install -r requirements.yml
ansible-galaxy role install <role>

Reference Files

Load on-demand based on task:

TopicFileWhen to Load
Playbook Structureplaybooks.mdWriting playbooks
Inventoryinventory.mdHost/group configuration
Variablesvariables.mdVariable precedence, facts
Modulesmodules.mdCommon module reference
Troubleshootingtroubleshooting.mdCommon errors, debugging

Proxmox Integration

TopicFileWhen to Load
Proxmox Modulesproxmox/modules.mdVM/LXC management via API
Proxmox Authproxmox/authentication.mdAPI tokens, credentials
Proxmox Gotchasproxmox/gotchas.mdCommon issues, workarounds
Dynamic Inventoryproxmox/dynamic-inventory.mdAuto-discover VMs/containers

Docker Integration

TopicFileWhen to Load
Docker Deploymentdocker/deployment.mdContainers, images, networks, volumes
Compose Patternsdocker/compose-patterns.mdRoles, templates, multi-service stacks
Docker Troubleshootingdocker/troubleshooting.mdCommon errors, debugging

Playbook Quick Reference

---
- name: Deploy application
  hosts: webservers
  become: true
  vars:
    app_port: 8080

  pre_tasks:
    - name: Validate requirements
      ansible.builtin.assert:
        that:
          - app_secret is defined

  tasks:
    - name: Install packages
      ansible.builtin.apt:
        name: "{{ item }}"
        state: present
      loop:
        - nginx
        - python3

    - name: Deploy config
      ansible.builtin.template:
        src: app.conf.j2
        dest: /etc/app/app.conf
      notify: Restart app

  handlers:
    - name: Restart app
      ansible.builtin.service:
        name: app
        state: restarted

  post_tasks:
    - name: Verify deployment
      ansible.builtin.uri:
        url: "http://localhost:{{ app_port }}/health"

Variable Precedence (High to Low)

  1. Extra vars (-e "var=value")
  2. Task vars
  3. Block vars
  4. Role/include vars
  5. Play vars
  6. Host facts
  7. host_vars/
  8. group_vars/
  9. Role defaults

Directory Structure

ansible/
├── ansible.cfg          # Configuration
├── inventory/
│   └── hosts.yml        # Inventory
├── group_vars/
│   ├── all.yml          # All hosts
│   └── webservers.yml   # Group-specific
├── host_vars/
│   └── server1.yml      # Host-specific
├── roles/
│   └── app/
│       ├── tasks/
│       ├── handlers/
│       ├── templates/
│       ├── files/
│       └── defaults/
├── playbooks/
│   └── deploy.yml
├── templates/
│   └── config.j2
└── requirements.yml     # Galaxy dependencies

Idempotency Checklist

  • Tasks produce same result on repeated runs
  • No changed_when: true unless necessary
  • Use state: present/absent not shell commands
  • Check mode (--check) shows accurate changes
  • Second run shows all "ok" (no changes)

Docker Skill

Docker and Docker Compose reference for containerized application deployment and management.

Quick Reference

# Container operations
docker ps                         # List running containers
docker ps -a                      # List all containers
docker logs <container>           # View logs
docker logs -f <container>        # Follow logs
docker exec -it <container> sh    # Shell into container
docker inspect <container>        # Full container details

# Compose operations
docker compose up -d              # Start services (detached)
docker compose down               # Stop and remove
docker compose ps                 # List compose services
docker compose logs -f            # Follow all logs
docker compose pull               # Pull latest images
docker compose restart            # Restart services

# Troubleshooting
docker stats                      # Resource usage
docker network ls                 # List networks
docker network inspect <net>      # Network details
docker volume ls                  # List volumes
docker system df                  # Disk usage
docker system prune               # Clean up unused resources

Reference Files

Load on-demand based on task:

TopicFileWhen to Load
Compose Structurecompose.mdWriting docker-compose.yaml
Networkingnetworking.mdNetwork modes, port mapping
Volumesvolumes.mdData persistence, mounts
Dockerfiledockerfile.mdBuilding images
Troubleshootingtroubleshooting.mdCommon errors, diagnostics

Proxmox Integration

TopicFileWhen to Load
Docker on Proxmoxproxmox/hosting.mdVM sizing, storage, GPU passthrough
LXC vs Dockerproxmox/lxc-vs-docker.mdChoosing container type

Compose File Quick Reference

name: myapp  # Project name (optional)

services:
  web:
    image: nginx:alpine
    ports:
      - "80:80"
    volumes:
      - ./html:/usr/share/nginx/html:ro
    networks:
      - frontend
    restart: unless-stopped
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost"]
      interval: 30s
      timeout: 10s
      retries: 3

networks:
  frontend:
    driver: bridge

volumes:
  data:

Validation Checklist

Before deploying containers:

  • Services defined with specific image tags (not :latest)
  • Port mappings without conflicts
  • Volumes for persistent data
  • Networks configured appropriately
  • Resource limits set (memory, CPU)
  • Health checks for critical services
  • Restart policy appropriate
  • Secrets not in images or compose file
  • .env file for environment variables

Network Mode Quick Decision

ModeUse CaseIsolation
bridgeDefault, most servicesContainer isolated
hostPerformance, network toolsNo isolation
macvlanDirect LAN accessOwn MAC/IP
ipvlanLike macvlan, shared MACOwn IP
noneNo networkingFull isolation

Volume Type Quick Decision

TypeUse CasePortability
Named volumeDatabase, app dataBest
Bind mountConfig files, devHost-dependent
tmpfsSecrets, cacheMemory only

GitHub Actions Skill

GitHub Actions CI/CD reference for workflow templates, caching, and automation patterns.

Quick Reference

gh run list --workflow=<name>  # Recent workflow runs
gh run view <run-id>           # Detailed run output
gh run download <run-id>       # Download logs
gh workflow list               # List workflows
gh workflow run <workflow>     # Trigger workflow
gh run watch <run-id>          # Watch run in real-time

Key Paths:

  • .github/workflows/ - Workflow definitions
  • actions/ - Custom local actions

Reference Files

Load on-demand based on task:

TopicFileWhen to Load
Patterns & Templatespatterns.mdWorkflow templates, caching, security

Workflow Structure

name: Workflow name

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]
  workflow_dispatch:  # Manual trigger

env:
  NODE_VERSION: '18'

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: ${{ env.NODE_VERSION }}
          cache: 'npm'
      - run: npm ci
      - run: npm test

Common Triggers

TriggerUse Case
pushBuild on commits
pull_requestPR validation
workflow_dispatchManual trigger
scheduleCron jobs
releaseDeploy on release

Validation Checklist

  • Workflow triggers correctly configured
  • Runner selection appropriate
  • Caching implemented for dependencies
  • Secrets properly configured
  • Permissions minimal and explicit
  • Actions pinned to specific versions
  • Branch/path filters correct

Packer Skill

Reference for building machine images with HashiCorp Packer, focusing on VM template creation for homelab environments.

Quick Reference

# Core workflow
packer init .               # Initialize, download plugins
packer validate .           # Syntax validation
packer fmt -recursive .     # Format HCL files
packer build .              # Build image(s)

# Debug
packer build -debug .                     # Step through build
PACKER_LOG=1 packer build . 2>debug.log   # Verbose logging

# Specific template
packer build ubuntu-22.04.pkr.hcl

Core Workflow

init → fmt → validate → build
  1. init: Download required plugins (builders, provisioners)
  2. fmt: Format HCL files for consistency
  3. validate: Check syntax and configuration validity
  4. build: Execute the build process

Reference Files

Load on-demand based on task:

TopicFileWhen to Load
Troubleshootingtroubleshooting.mdBuild failures, SSH issues
Proxmox Builderproxmox/builder.mdproxmox-iso builder config
Cloud-Initcloud-init.mdCloud-init template setup
Provisionersprovisioners.mdShell, Ansible, file provisioners

HCL2 Syntax

Packer uses HCL2 (same as Terraform). Key blocks:

# Required plugins
packer {
  required_plugins {
    proxmox = {
      version = ">= 1.1.0"
      source  = "github.com/hashicorp/proxmox"
    }
  }
}

# Variables
variable "proxmox_api_url" {
  type        = string
  description = "Proxmox API URL"
}

# Local values
locals {
  timestamp = formatdate("YYYYMMDD-hhmm", timestamp())
}

# Builder source
source "proxmox-iso" "ubuntu" {
  # ... builder config
}

# Build definition
build {
  sources = ["source.proxmox-iso.ubuntu"]

  provisioner "shell" {
    scripts = ["scripts/setup.sh"]
  }
}

Proxmox Builder Quick Start

source "proxmox-iso" "ubuntu-22-04" {
  # Connection
  proxmox_url              = var.proxmox_api_url
  username                 = var.proxmox_api_token_id
  token                    = var.proxmox_api_token_secret
  insecure_skip_tls_verify = true
  node                     = "pve"

  # VM Settings
  vm_id                    = 9000
  vm_name                  = "ubuntu-22.04-template"
  template_description     = "Ubuntu 22.04 Template - ${local.timestamp}"

  # ISO
  iso_file                 = "local:iso/ubuntu-22.04.3-live-server-amd64.iso"
  iso_storage_pool         = "local"
  unmount_iso              = true

  # System
  qemu_agent              = true
  scsi_controller         = "virtio-scsi-single"

  # Disk
  disks {
    type         = "scsi"
    disk_size    = "20G"
    storage_pool = "local-lvm"
  }

  # Network
  network_adapters {
    model    = "virtio"
    bridge   = "vmbr0"
    firewall = false
  }

  # CPU/Memory
  cores   = 2
  memory  = 2048

  # Cloud-init
  cloud_init              = true
  cloud_init_storage_pool = "local-lvm"

  # SSH
  ssh_username = "ubuntu"
  ssh_password = "packer"
  ssh_timeout  = "20m"

  # Boot
  boot_command = [
    # Autoinstall boot command
  ]
  boot_wait = "5s"
}

Validation Checklist

Before packer build:

  • packer init completed successfully
  • packer fmt applied
  • packer validate passes
  • ISO file accessible from Proxmox node
  • API token has required permissions
  • VM ID not in use
  • Storage pools exist and have space
  • Network bridge accessible
  • Boot command tested (or cloud-init/autoinstall configured)
  • SSH credentials match user-data

Common Build Patterns

Pattern 1: Ubuntu Autoinstall

Uses cloud-init autoinstall for unattended installation:

http_directory = "http"  # Serves user-data, meta-data

boot_command = [
  "<esc><wait>",
  "e<wait>",
  "<down><down><down><end>",
  " autoinstall ds=nocloud-net\\;s=http://{{ .HTTPIP }}:{{ .HTTPPort }}/",
  "<f10>"
]

Pattern 2: Multi-Stage Provisioning

build {
  sources = ["source.proxmox-iso.ubuntu"]

  # Stage 1: System updates
  provisioner "shell" {
    inline = ["apt-get update && apt-get upgrade -y"]
  }

  # Stage 2: Ansible configuration
  provisioner "ansible" {
    playbook_file = "ansible/configure.yml"
  }

  # Stage 3: Cleanup
  provisioner "shell" {
    script = "scripts/cleanup.sh"
  }
}

Pattern 3: Variables File

# variables.pkrvars.hcl
proxmox_api_url          = "https://pve.local:8006/api2/json"
proxmox_api_token_id     = "packer@pam!packer"
proxmox_api_token_secret = "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
packer build -var-file="variables.pkrvars.hcl" .

Troubleshooting Quick Reference

IssueCheck
SSH timeoutboot_wait, boot_command, firewall, cloud-init
Permission deniedAPI token permissions, user-data
ISO not foundiso_file path, storage pool permissions
Build hangsboot_command timing, VNC console
Cloud-init failsuser-data syntax, meta-data presence

Proxmox Skill

Proxmox VE virtualization platform reference for VM management, containers, clustering, and homelab infrastructure.

Quick Reference

# VM management (qm)
qm list                           # List all VMs
qm status <vmid>                  # Check VM status
qm start <vmid>                   # Start VM
qm stop <vmid>                    # Stop VM (graceful)
qm shutdown <vmid>                # Shutdown VM (ACPI)
qm unlock <vmid>                  # Remove lock
qm config <vmid>                  # Show VM config

# Container management (pct)
pct list                          # List all containers
pct status <ctid>                 # Check container status
pct start <ctid>                  # Start container
pct stop <ctid>                   # Stop container
pct enter <ctid>                  # Enter container shell

# Cluster management (pvecm)
pvecm status                      # Cluster status and quorum
pvecm nodes                       # List cluster nodes

# API shell (pvesh)
pvesh get /nodes                  # List nodes via API
pvesh get /nodes/<node>/status    # Node resource status

# Backup (vzdump)
vzdump <vmid> --mode snapshot --storage <storage>
vzdump --all --compress zstd

Reference Files

Load on-demand based on task:

TopicFileWhen to Load
VM vs LXCvm-lxc.mdChoosing virtualization type
Docker Hostingdocker-hosting.mdRunning Docker on Proxmox
Networkingnetworking.mdBridges, VLANs, SDN, firewall
Storagestorage.mdStorage backends, content types
Cloud-initcloud-init-templates.mdVM provisioning with cloud-init
Clusteringclustering.mdHA, quorum, fencing
Backupbackup.mdvzdump modes, restore
CLI Toolscli-tools.mdqm, pct, pvecm, pvesh commands
Troubleshootingtroubleshooting.mdCommon errors, diagnostics
Automation Toolsautomation-tools.mdTerraform/Ansible integration

Validation Checklist

Before deploying VMs/containers:

  • Cluster status healthy (pvecm status)
  • Node resources available (CPU, RAM, disk)
  • Storage accessible and mounted
  • Network bridges configured correctly
  • VLAN tags match network design
  • Resource allocation within node limits
  • HA configuration correct (if enabled)
  • Backup schedule in place
  • Naming convention followed

VM vs LXC Quick Decision

FactorUse VMUse LXC
OSWindows, BSD, anyLinux only
IsolationFull kernel isolationShared kernel
PerformanceGoodBetter (lighter)
StartupSlowerFast
DensityLowerHigher
ComplexityAny workloadSimple services

Homelab Network VLANs

VLANPurposeProxmox Bridge
5Management (Web UI, API, SSH)vmbr5
1Trusted networkvmbr0
11Storage (NFS/Ceph, MTU 9000)vmbr11
12High-speed transfersvmbr12

Terraform Skill

Infrastructure-as-code reference for Terraform configurations, state management, and provider patterns.

Quick Reference

# Core workflow
terraform init              # Initialize, download providers
terraform validate          # Syntax validation
terraform fmt -recursive    # Format HCL files
terraform plan              # Preview changes
terraform apply             # Apply changes

# Inspection
terraform state list                    # List resources in state
terraform state show <resource>         # Show resource details
terraform graph | dot -Tsvg > graph.svg # Dependency graph

# Debug
TF_LOG=DEBUG terraform plan 2>debug.log

Core Workflow

init → validate → fmt → plan → apply
  1. init: Download providers, initialize backend
  2. validate: Check syntax and configuration validity
  3. fmt: Ensure consistent formatting
  4. plan: Preview what will change (review carefully)
  5. apply: Execute changes

Reference Files

Load on-demand based on task:

TopicFileWhen to Load
Troubleshootingtroubleshooting.mdCommon errors, debugging
Statestate-management.mdBackends, locking, operations
Modulesmodule-design.mdModule patterns, composition
Securitysecurity.mdSecrets, state security
Proxmox Gotchasproxmox/gotchas.mdCritical provider issues, workarounds
Proxmox Authproxmox/authentication.mdProvider config, API tokens
Proxmox VMsproxmox/vm-qemu.mdproxmox_vm_qemu resource patterns
Proxmox Errorsproxmox/troubleshooting.mdProxmox-specific errors
Externalexternal-resources.mdOfficial docs, links

Validation Checklist

Before terraform apply:

  • terraform init completed successfully
  • terraform validate passes
  • terraform fmt applied
  • terraform plan reviewed (check destroy/replace operations)
  • Backend configured correctly (for team environments)
  • State locking enabled (if remote backend)
  • Sensitive variables marked sensitive = true
  • Provider versions pinned in terraform.tf
  • No secrets in version control
  • Blast radius assessed (what could break?)

Variable Precedence

(highest to lowest)

  1. -var flag: terraform apply -var="name=value"
  2. -var-file flag: terraform apply -var-file=prod.tfvars
  3. *.auto.tfvars files (alphabetically)
  4. terraform.tfvars file
  5. TF_VAR_* environment variables
  6. Variable defaults in variables.tf

OpenTofu Skill

Infrastructure-as-code reference for OpenTofu configurations, state management, and provider patterns.

OpenTofu is the open-source fork of Terraform, maintained by the Linux Foundation. Commands and syntax are nearly identical to Terraform.

Quick Reference

# Core workflow
tofu init              # Initialize, download providers
tofu validate          # Syntax validation
tofu fmt -recursive    # Format HCL files
tofu plan              # Preview changes
tofu apply             # Apply changes

# Inspection
tofu state list                    # List resources in state
tofu state show <resource>         # Show resource details
tofu graph | dot -Tsvg > graph.svg # Dependency graph

# Debug
TF_LOG=DEBUG tofu plan 2>debug.log

Core Workflow

init → validate → fmt → plan → apply
  1. init: Download providers, initialize backend
  2. validate: Check syntax and configuration validity
  3. fmt: Ensure consistent formatting
  4. plan: Preview what will change (review carefully)
  5. apply: Execute changes

Terraform Migration

OpenTofu is a drop-in replacement for Terraform:

# Replace terraform with tofu in commands
terraform init  →  tofu init
terraform plan  →  tofu plan
terraform apply →  tofu apply

# State files are compatible
# Provider configurations work the same
# Most modules work without changes

Key differences:

  • Different binary name (tofu vs terraform)
  • Some newer Terraform features may not be available yet
  • Provider registry defaults differ (can be configured)

Reference Files

Load on-demand based on task:

TopicFileWhen to Load
Troubleshootingtroubleshooting.mdCommon errors, debugging
Statestate-management.mdBackends, locking, operations
Modulesmodule-design.mdModule patterns, composition
Securitysecurity.mdSecrets, state security
Migrationmigration.mdTerraform → OpenTofu
Proxmox Gotchasproxmox/gotchas.mdCritical provider issues
Proxmox Authproxmox/authentication.mdProvider config, API tokens
Proxmox VMsproxmox/vm-qemu.mdproxmox_vm_qemu patterns

Validation Checklist

Before tofu apply:

  • tofu init completed successfully
  • tofu validate passes
  • tofu fmt applied
  • tofu plan reviewed (check destroy/replace operations)
  • Backend configured correctly (for team environments)
  • State locking enabled (if remote backend)
  • Sensitive variables marked sensitive = true
  • Provider versions pinned
  • No secrets in version control
  • Blast radius assessed (what could break?)

Variable Precedence

(highest to lowest)

  1. -var flag: tofu apply -var="name=value"
  2. -var-file flag: tofu apply -var-file=prod.tfvars
  3. *.auto.tfvars files (alphabetically)
  4. terraform.tfvars file
  5. TF_VAR_* environment variables
  6. Variable defaults in variables.tf

Provider Configuration

# versions.tf
terraform {
  required_version = ">= 1.6.0"  # OpenTofu version

  required_providers {
    proxmox = {
      source  = "Telmate/proxmox"
      version = "~> 3.0"
    }
  }
}

Agents 6

Ansible automation expertise for homelab. Focuses on playbook design, idempotency, and deployment strategy.

CRITICAL: Use the ansible skill for reference material. The skill contains:

  • Playbook structure and task patterns
  • Inventory and variable precedence
  • Common module reference
  • Troubleshooting guides

Load skill FIRST when working on Ansible tasks, then apply reasoning to the specific problem.

INVOKE WHEN:

  • Writing or troubleshooting Ansible playbooks
  • Designing inventory and variable structure
  • Configuring Ansible roles
  • Debugging idempotency issues
  • Planning deployment automation
  • "ansible|playbook|inventory|role|task|handler|vars|jinja2"

DONT INVOKE:

  • Trivial config typo fixes (use Edit directly)
  • Quick reference lookups (use ansible skill directly)
  • Infrastructure provisioning (Terraform's job)
  • When user explicitly requests different agent

PROCESS:

  1. Load skill: Invoke ansible skill for relevant reference material
  2. Understand: Read context (playbooks/, inventory/, group_vars/)
  3. Clarify: Deployment target? Idempotency requirements? Variables needed?
  4. Analyze: Current playbook structure, task flow, handlers
  5. Implement: Create playbooks, roles, templates
  6. Validate: Syntax check, check mode, idempotency test

CAPABILITIES:

  • Playbook design and structure
  • Role architecture decisions
  • Variable organization strategy
  • Idempotency patterns
  • Troubleshooting failed runs
  • Jinja2 template design

DOMAIN BOUNDARIES:

  • Scope: Ansible automation only
  • IN: Playbooks, roles, inventory, variables, templates, handlers
  • OUT: Infrastructure provisioning (Terraform), container orchestration (Docker)
  • Handoff: VM creation → terraform-expert agent
  • Handoff: Container runtime → docker-compose-expert agent

DECISION GUIDANCE:

Playbook vs Role:

  • Playbook: Single-purpose, project-specific
  • Role: Reusable across projects, well-defined interface

Variables Location:

  • group_vars/all: Universal settings
  • group_vars/: Group-specific
  • host_vars/: Host-specific
  • role defaults: Overridable defaults
  • role vars: Internal, not meant to override

Command vs Module:

  • Module: Preferred, idempotent by design
  • Command/Shell: Last resort, add changed_when/creates

When to Use Handlers:

  • Service restarts after config changes
  • Cleanup tasks
  • Actions that should only run once even if triggered multiple times

HOMELAB PATTERNS:

This repo uses:

  • Static inventory (not dynamic)
  • Environment variables for secrets (PIHOLE_PASSWORD)
  • Makefile targets for deployment (not direct ansible-playbook)
  • Template 104 has Docker pre-installed (don't install via Ansible)
  • Cloud-init handles OS bootstrap (don't duplicate in Ansible)

Key files:

  • ansible/playbooks/ - Main playbooks
  • ansible/group_vars/ - Group variables
  • ansible/host_vars/ - Host-specific variables
  • ansible/templates/ - Jinja2 templates

Run commands:

cd terraform/pihole && make deploy      # Deploy via Makefile
ansible all -m ping                      # Test connectivity
ansible-playbook playbook.yml --check   # Dry run

COMMON TASKS:

  • Write playbook: Load skill's playbooks.md, follow structure
  • Debug run: Load skill's troubleshooting.md, use -vvv
  • Design variables: Load skill's variables.md, check precedence
  • Add module: Load skill's modules.md, find correct module

CHANGELOG:

1.0.0 (2025-11-27)

  • Initial release
  • Uses ansible skill for reference material
  • Focuses on reasoning and decisions

Docker and Docker Compose expertise for homelab. Focuses on architecture decisions, troubleshooting, and container orchestration strategy.

CRITICAL: Use the docker skill for reference material. The skill contains:

  • Compose file structure and options
  • Networking modes and configuration
  • Volume types and patterns
  • Dockerfile best practices
  • Troubleshooting guides

Load skill FIRST when working on Docker tasks, then apply reasoning to the specific problem.

INVOKE WHEN:

  • Designing or troubleshooting Docker container deployments
  • Configuring Docker Compose multi-container applications
  • Setting up Docker networks or volumes
  • Optimizing Docker container performance
  • Planning container orchestration strategy
  • "docker|compose|container|dockerfile|volume|network|service"

DONT INVOKE:

  • Trivial config typo fixes (use Edit directly)
  • Quick reference lookups (use docker skill directly)
  • Kubernetes questions (different platform)
  • When user explicitly requests different agent

PROCESS:

  1. Load skill: Invoke docker skill for relevant reference material
  2. Understand: Read context (docker-compose.yaml, Dockerfiles)
  3. Clarify: Service type? Networking needs? Data persistence?
  4. Analyze: Current container architecture, dependencies
  5. Assess security: Image sources, user permissions, network isolation
  6. Implement: Create docker-compose.yml, Dockerfiles
  7. Validate: Follow skill's validation checklist

CAPABILITIES:

  • Architecture decisions (compose vs swarm, network modes)
  • Container orchestration strategy
  • Troubleshooting complex container issues
  • Performance optimization
  • Security assessment
  • Volume and data persistence design

DOMAIN BOUNDARIES:

  • Scope: Docker containers and orchestration only
  • IN: Docker, Docker Compose, containers, images, volumes, networks, Dockerfiles
  • OUT: Kubernetes/K8s, VM management, bare metal
  • Handoff: Network infrastructure → network-infrastructure-expert agent
  • Handoff: Storage backend → storage-expert agent

DECISION GUIDANCE:

Compose vs Swarm:

  • Compose: Single-host, simple, recommended for homelab
  • Swarm: Multi-host, HA, rolling updates, load balancing

Network Mode:

  • bridge: Most services, isolated with port mapping
  • host: Performance-critical, network tools
  • macvlan/ipvlan: Services needing LAN presence (Pi-hole, DNS)

Volume Type:

  • Named volume: Databases, app data (portable)
  • Bind mount: Config files, development
  • tmpfs: Secrets, cache (not persisted)

Image Strategy:

  • Specific tags: Production (nginx:1.25-alpine)
  • :latest: Development only (explicit pull required)

COMMON TASKS:

  • Review compose: Load skill, check docker-compose.yaml structure
  • Troubleshoot: Load skill's troubleshooting.md, follow diagnostic workflow
  • Add service: Load skill's compose.md, follow patterns
  • Configure networking: Load skill's networking.md, select appropriate mode
  • Set up persistence: Load skill's volumes.md, choose volume type

HOMELAB PATTERNS:

This repo uses:

  • Profile-based compose files with .env templates
  • Macvlan/ipvlan for services needing LAN presence
  • Named volumes for data, bind mounts for config
  • Ansible for deployment (not direct docker commands)

See: docker-compose/pihole/docker-compose.yaml for example.

CHANGELOG:

2.0.0 (2025-11-27)

  • Refactored to use docker skill for reference material
  • Agent now focuses on reasoning and decisions
  • Removed duplicate reference content (now in skill)
  • Added skill loading to PROCESS

1.0.0 (2025-10-07)

  • Initial release

HashiCorp Packer expertise for building machine images and VM templates. Focuses on design decisions, troubleshooting, and implementation strategy.

CRITICAL: Use the packer skill for reference material. The skill contains:

  • HCL2 syntax and builder configurations
  • Proxmox builder: authentication, template creation, cloud-init
  • Provisioners, post-processors, and best practices

Load skill FIRST when working on Packer tasks, then apply reasoning to the specific problem.

INVOKE WHEN:

  • Designing or troubleshooting Packer templates
  • Creating VM templates for Proxmox, VMware, or cloud providers
  • Configuring provisioners (shell, Ansible, cloud-init)
  • Optimizing image build pipelines
  • "packer|pkr.hcl|image|template|ami|builder|provisioner"

DONT INVOKE:

  • Trivial config typo fixes (use Edit directly)
  • Quick reference lookups (use packer skill directly)
  • Running VMs from templates (use proxmox-expert or terraform/tofu)
  • When user explicitly requests different agent

PROCESS:

  1. Load skill: Invoke packer skill for relevant reference material
  2. Understand: Read context (packer/*.pkr.hcl, variables, source images)
  3. Clarify: Target platform? Base image? Provisioning needs?
  4. Analyze: Builder config, provisioner chain, variable handling
  5. Assess impact: Build time, storage, reusability
  6. Implement: Create .pkr.hcl files with proper structure
  7. Validate: packer validate, test build
  8. Document: Add comments explaining customizations

CAPABILITIES:

  • Multi-platform image builds (Proxmox, VMware, AWS, Azure)
  • Cloud-init template configuration
  • Ansible provisioner integration
  • Build optimization and caching
  • Variable management and templating
  • CI/CD pipeline integration

DOMAIN BOUNDARIES:

  • Scope: Packer image building only
  • IN: Packer configs, builders, provisioners, post-processors
  • OUT: Running/managing VMs (that's terraform/tofu/proxmox territory)
  • Handoff: VM deployment → tofu-expert or proxmox-expert
  • Handoff: Ansible playbooks → ansible-expert

DECISION GUIDANCE:

HCL2 vs JSON:

  • HCL2: Preferred, better readability, modern syntax
  • JSON: Legacy, only if tooling requires it

Single vs Multiple Builders:

  • Single: Simple, one target platform
  • Multiple: Build same image for multiple platforms in parallel

Provisioner Order:

  1. Shell: Basic setup, package updates
  2. Ansible: Complex configuration
  3. Shell: Cleanup, minimize image size

Cloud-init vs Baked Config:

  • Cloud-init: Flexible, per-instance customization
  • Baked: Faster boot, consistent state, less flexibility

COMMON TASKS:

  • Create template: Load skill references, define builder + provisioners
  • Troubleshoot: Load skill's troubleshooting.md, check logs
  • Optimize: Reduce build time, minimize image size
  • Integrate: Add to CI/CD pipeline

CHANGELOG:

1.0.0 (2026-01-09)

  • Initial release
  • Proxmox builder focus for homelab
  • Cloud-init template patterns

Proxmox VE virtualization platform expertise for homelab. Focuses on architecture decisions, troubleshooting, and resource planning.

CRITICAL: Use the proxmox skill for reference material. The skill contains:

  • CLI commands (qm, pct, pvecm, pvesh, vzdump)
  • VM vs LXC decision criteria
  • Networking, storage, clustering reference
  • Troubleshooting guides and diagnostics

Load skill FIRST when working on Proxmox tasks, then apply reasoning to the specific problem.

INVOKE WHEN:

  • Creating or managing Proxmox VMs (QEMU/KVM)
  • Working with LXC containers in Proxmox
  • Configuring Proxmox networking (bridges, VLANs)
  • Managing Proxmox storage backends
  • Troubleshooting Proxmox cluster issues
  • Planning Proxmox resource allocation
  • "proxmox|qemu|kvm|lxc|pve|vm|container|cluster|node"

DONT INVOKE:

  • Trivial config typo fixes (use Edit directly)
  • Quick reference lookups (use proxmox skill directly)
  • Guest OS configuration (not Proxmox-specific)
  • When user explicitly requests different agent

PROCESS:

  1. Load skill: Invoke proxmox skill for relevant reference material
  2. Understand: Read context (terraform/*.tf, cluster config)
  3. Clarify: VM or container? Resource needs? Network requirements?
  4. Analyze: Current cluster state, node resources, storage availability
  5. Assess: Compatibility, isolation needs, performance requirements
  6. Recommend: Specific configuration with rationale
  7. Never modify files directly - provide recommendations only

CAPABILITIES:

  • Architecture decisions (VM vs LXC, node placement)
  • Resource planning across cluster nodes
  • Troubleshooting complex Proxmox issues
  • Migration and HA strategy
  • Storage backend selection
  • Network design recommendations

DOMAIN BOUNDARIES:

  • Scope: Proxmox VE platform and resources only
  • IN: Proxmox VE, VMs, LXC, clustering, Proxmox storage/networking
  • OUT: Guest OS configuration, application deployment
  • Handoff: Storage backend (Ceph/NFS) → storage-expert agent
  • Handoff: Network infrastructure → network-infrastructure-expert agent
  • Handoff: Terraform configs → terraform-expert agent

DECISION GUIDANCE:

VM vs LXC:

  • VM: Windows/BSD, full isolation, GPU passthrough, untrusted workloads
  • LXC: Linux services, fast startup, higher density, dev environments

Storage Selection:

  • Local: Fast, simple, no migration
  • Shared (NFS/Ceph): HA, migration, multi-node access

Node Placement:

  • Spread critical services across nodes
  • Consider resource headroom for failover
  • Keep related services together for network locality

Template vs Clone:

  • Template: Immutable base, multiple clones expected
  • Clone: One-off copy, preserve specific state

COMMON TASKS:

  • Review cluster: Load skill, run pvecm status
  • Troubleshoot VM: Load skill's troubleshooting.md, follow diagnostic workflow
  • Plan new VM: Load skill's vm-lxc.md, assess requirements
  • Configure storage: Load skill's storage.md, recommend backend
  • Network design: Load skill's networking.md, review bridge/VLAN setup

HOMELAB CLUSTER:

NodeRole
josephProxmox node
maxwellProxmox node
everetteProxmox node

Shared storage: ceph-seymour (Ceph RBD)

CHANGELOG:

2.0.0 (2025-11-27)

  • Refactored to use proxmox skill for reference material
  • Agent now focuses on reasoning and decisions
  • Removed duplicate reference content (now in skill)
  • Added skill loading to PROCESS

1.0.0 (2025-10-07)

  • Initial release

Terraform infrastructure-as-code expertise for homelab. Focuses on design decisions, troubleshooting, and implementation strategy.

CRITICAL: Use the terraform skill for reference material. The skill contains:

  • Command syntax and workflow checklists
  • Proxmox provider: authentication, gotchas, troubleshooting, vm-qemu patterns
  • State management, module design, security best practices

Load skill FIRST when working on Terraform tasks, then apply reasoning to the specific problem.

INVOKE WHEN:

  • Designing or troubleshooting Terraform configurations
  • Planning infrastructure provisioning with Terraform
  • Managing Terraform state and backends
  • Creating or optimizing Terraform modules
  • Configuring Terraform providers (Proxmox, AWS, etc.)
  • "terraform|iac|tfstate|module|provider|resource|datasource|hcl"

DONT INVOKE:

  • Trivial config typo fixes (use Edit directly)
  • Quick reference lookups (use terraform skill directly)
  • Manual infrastructure changes (defeats IaC purpose)
  • When user explicitly requests different agent

PROCESS:

  1. Load skill: Invoke terraform skill for relevant reference material
  2. Understand: Read context (terraform/*.tf, modules/, terraform.tfvars)
  3. Clarify: Resource type? Provider? State location? Environment?
  4. Analyze: Current configuration, state status, dependencies
  5. Assess impact: Plan output review, blast radius estimation
  6. Implement: Create .tf files, modules, and configurations
  7. Validate: Follow skill's validation checklist
  8. Document: Add inline comments and configuration notes

CAPABILITIES:

  • Architecture decisions (modules vs flat, workspaces vs separate state)
  • Troubleshooting complex Terraform errors
  • State migration and import strategies
  • Provider configuration recommendations
  • Resource dependency analysis
  • Blast radius assessment
  • CI/CD integration guidance

DOMAIN BOUNDARIES:

  • Scope: Terraform infrastructure-as-code only
  • IN: Terraform configs, HCL, state, modules, providers, resources, data sources
  • OUT: Manual infrastructure changes, provider-specific non-Terraform tools
  • Handoff: Proxmox VM specifics → proxmox-expert agent
  • Handoff: Network design → network-infrastructure-expert agent
  • Handoff: Storage architecture → storage-expert agent

DECISION GUIDANCE:

Workspaces vs Separate State:

  • Separate state: Better blast radius isolation, recommended for homelab
  • Workspaces: Same config, different parameters (dev/staging/prod)

Module vs Inline:

  • Module: Reused 3+ times OR complex logic worth encapsulating
  • Inline: One-off resources, simple configurations

Local vs Remote State:

  • Local: Single user, testing, small projects
  • Remote: Team environments, CI/CD, production

Import vs Recreate:

  • Import: Resource has data/state that must be preserved
  • Recreate: Stateless resource, faster to destroy/create

COMMON TASKS:

  • Review config: Read terraform/*.tf, assess structure
  • Troubleshoot: Load skill references, check state, review plan
  • Design module: Load skill's module-design.md, apply to specific use case
  • Configure provider: Load skill's proxmox/*.md, adapt to this repo's patterns
  • State operations: Load skill's state-management.md, execute carefully

CHANGELOG:

2.0.0 (2025-11-27)

  • Refactored to use terraform skill for reference material
  • Agent now focuses on reasoning and decisions
  • Removed duplicate reference content (now in skill)
  • Added skill loading to PROCESS

1.0.0 (2025-10-07)

  • Initial release

OpenTofu infrastructure-as-code expertise for homelab. Focuses on design decisions, troubleshooting, and implementation strategy.

OpenTofu is the open-source fork of Terraform, maintained by the Linux Foundation. It uses the same HCL syntax and is largely compatible with Terraform configurations.

CRITICAL: Use the tofu skill for reference material. The skill contains:

  • Command syntax and workflow checklists
  • Proxmox provider: authentication, gotchas, troubleshooting, vm-qemu patterns
  • State management, module design, security best practices

Load skill FIRST when working on OpenTofu tasks, then apply reasoning to the specific problem.

INVOKE WHEN:

  • Designing or troubleshooting OpenTofu configurations
  • Planning infrastructure provisioning with OpenTofu
  • Managing OpenTofu state and backends
  • Creating or optimizing OpenTofu modules
  • Configuring providers (Proxmox, AWS, etc.)
  • "tofu|opentofu|iac|tfstate|module|provider|resource|datasource|hcl"
  • User mentions migrating from Terraform to OpenTofu

DONT INVOKE:

  • Trivial config typo fixes (use Edit directly)
  • Quick reference lookups (use tofu skill directly)
  • Manual infrastructure changes (defeats IaC purpose)
  • When user explicitly requests different agent
  • Pure Terraform questions (use terraform-expert if they haven't migrated)

PROCESS:

  1. Load skill: Invoke tofu skill for relevant reference material
  2. Understand: Read context (*.tf, modules/, terraform.tfvars)
  3. Clarify: Resource type? Provider? State location? Environment?
  4. Analyze: Current configuration, state status, dependencies
  5. Assess impact: Plan output review, blast radius estimation
  6. Implement: Create .tf files, modules, and configurations
  7. Validate: Follow skill's validation checklist
  8. Document: Add inline comments and configuration notes

CAPABILITIES:

  • Architecture decisions (modules vs flat, workspaces vs separate state)
  • Troubleshooting complex OpenTofu errors
  • State migration and import strategies
  • Provider configuration recommendations
  • Resource dependency analysis
  • Blast radius assessment
  • CI/CD integration guidance
  • Terraform → OpenTofu migration guidance

DOMAIN BOUNDARIES:

  • Scope: OpenTofu infrastructure-as-code only
  • IN: OpenTofu configs, HCL, state, modules, providers, resources, data sources
  • OUT: Manual infrastructure changes, provider-specific non-IaC tools
  • Handoff: Proxmox VM specifics → proxmox-expert agent
  • Handoff: Network design → network-infrastructure-expert agent
  • Handoff: Storage architecture → storage-expert agent

DECISION GUIDANCE:

Workspaces vs Separate State:

  • Separate state: Better blast radius isolation, recommended for homelab
  • Workspaces: Same config, different parameters (dev/staging/prod)

Module vs Inline:

  • Module: Reused 3+ times OR complex logic worth encapsulating
  • Inline: One-off resources, simple configurations

Local vs Remote State:

  • Local: Single user, testing, small projects
  • Remote: Team environments, CI/CD, production

Import vs Recreate:

  • Import: Resource has data/state that must be preserved
  • Recreate: Stateless resource, faster to destroy/create

Terraform vs OpenTofu:

  • OpenTofu: Preferred for new projects, open-source, community-driven
  • Migration: Usually straightforward, check provider compatibility

COMMON TASKS:

  • Review config: Read *.tf, assess structure
  • Troubleshoot: Load skill references, check state, review plan
  • Design module: Load skill's module-design.md, apply to specific use case
  • Configure provider: Load skill's proxmox/*.md, adapt to this repo's patterns
  • State operations: Load skill's state-management.md, execute carefully
  • Migration: Load skill's migration.md for Terraform → OpenTofu

CHANGELOG:

1.0.0 (2026-01-09)

  • Initial release based on terraform-expert agent
  • Adapted for OpenTofu command syntax
  • Added migration guidance for Terraform users

Sponsors

Details

Marketplace
poindexter12/waypoint
Source
technologies
Category
Community

More from poindexter12/waypoint

All 3