Imported from jacksparrow414/ansible-learning-lab (AGENTS.md). Install upstream with npx skills add jacksparrow414/ansible-learning-lab. Copyright stays with the author.

AGENTS.md

Guidance for AI agents and contributors working in this repository. Read this first at the start of every session.

Project Overview

Ansible learning lab: a production-grade reference project covering roles, Jinja2 templates, handlers, Vault encryption, dynamic inventory, and Molecule testing. All CI runs locally — there is no hosted CI pipeline.

Toolchain

• Dependency management: uv (migrated from Poetry — do not reintroduce poetry commands or poetry.lock).
• Python 3.14, pinned in .python-version; uv resolves it automatically (managed interpreters are fine).
• Non-packaged project ([tool.uv] package = false): uv sync only installs dependencies into .venv/.
• uv.lock is the lock file — commit it. Run uv lock after changing dependencies in pyproject.toml.
• Platform note: cryptography is constrained to <49 on macOS x86_64 because 49+ publishes no Intel Mac wheel. Do not remove that marker-scoped constraint without verifying wheel availability.

Setup

uv sync                      # create .venv and install all dependencies (incl. dev group)
source .venv/bin/activate    # optional; otherwise prefix commands with `uv run`

Common Commands

uv run ansible-lint                    # Ansible lint (production profile, strict)
uv run yamllint .                      # YAML lint
uv run pre-commit run --all-files      # all pre-commit hooks
uv run ./scripts/ci-local.sh           # lint + Molecule tests for every role

cd roles/<role> && uv run molecule test    # test one role (requires Docker)

ansible-playbook -i inventory/docker.yml playbooks/site.yml   # full deployment
python inventory/dynamic/docker_inventory.py --list           # dynamic inventory

Conventions

• Run Ansible commands from the project root — ansible.cfg (inventory path, roles path, vault settings) only applies there.
• Commit messages: Conventional Commits — feat:, fix:, docs:, chore: (optionally refactor:, test:, build:). Imperative, lowercase summary. Never add Co-Authored-By trailers or AI-tool attribution to commits.
• Pre-commit hooks (trailing whitespace, end-of-file, YAML check, ansible-lint, yamllint) run on every git commit; install once with uv run pre-commit install.
• YAML style: 2-space indent, --- document start, max line length 120, truthy values limited to true/false/yes/no (see .yamllint.yml; .venv/, .molecule/, .cache/ are excluded).
• ansible-lint runs with the production profile in strict mode — warnings fail the build.
• Variables: role defaults in roles/<role>/defaults/main.yml, group vars in group_vars/, host vars in host_vars/. Sensitive values go in group_vars/all/vault.yml (Ansible Vault).

Secrets

• vault_password_file is local-only and gitignored — never commit it. If it is missing, lint/syntax checks fail; create a local one (printf 'password\n' > vault_password_file && chmod 600 vault_password_file).

Testing & Verification

• Molecule tests and the Docker test environment (tests/docker-compose.yml, 3 nodes: web-01, web-02, db-01) require Docker Desktop running.
• Before committing changes, run uv run pre-commit run --all-files. With Docker available, run uv run ./scripts/ci-local.sh for the full suite.

Documentation Map

• README.md — user-facing setup and usage (authoritative).
• docs/superpowers/ — historical design spec and implementation plan from project inception. These reference the old Poetry workflow and are kept as history only; where they conflict with this file or the README, this file wins.