infra/AGENTS.md

AGENTS.md

Guidance for coding agents working in this repository. Project type: Ansible infrastructure + managed dotfiles.

Repository scope and layout

• Entry playbook: ansible/site.yml
• Inventory: ansible/inventory/hosts.yml
• Group vars: ansible/inventory/group_vars/*.yml
• Host vars: ansible/inventory/host_vars/*.yml
• Roles: ansible/roles/*/tasks/main.yml
• Dotfiles source of truth: dotfiles/
• Ansible config file: ansible.cfg

Current ansible.cfg defaults:

• inventory = ansible/inventory/hosts.yml
• roles_path = ansible/roles
• host_key_checking = False
• retry_files_enabled = False

Local instruction files (Cursor/Copilot)

Checked in this repository:

• .cursorrules: not present
• .cursor/rules/: not present
• .github/copilot-instructions.md: not present

If any of the files above appear later, treat them as higher-priority local instructions.

Build, lint, and test commands

There is no compile/build step in this repo. Validation is Ansible syntax checks, dry-runs, inventory checks, and linting.

Core apply run:

ansible-playbook ansible/site.yml

Safe dry-run with changes preview:

ansible-playbook ansible/site.yml --check --diff

Target a single host (useful for SSH-first rollout):

ansible-playbook ansible/site.yml --limit ikaros

Linting (if installed locally):

ansible-lint ansible/site.yml
ansible-lint ansible/roles
yamllint ansible/

Single-test equivalents (important)

There is no Molecule/pytest suite. Use one of these as a "single test" workflow.

Fast syntax-only validation:

ansible-playbook ansible/site.yml --syntax-check

Best default single-host safety check:

ansible-playbook ansible/site.yml --limit nymph --check --diff

Single-role smoke test using --start-at-task (dotfiles path):

ansible-playbook ansible/site.yml --limit ikaros --start-at-task "Copy common dotfiles" --check --diff

Single-role smoke test using --start-at-task (Void packages path):

ansible-playbook ansible/site.yml --limit ikaros --start-at-task "Install Void nonfree repository if needed" --check --diff

Notes:

• Current active stack in ansible/site.yml: dotfiles_common, packages_void, services_runit, profile_desktop_i3.
• Ubuntu/systemd/workstation/server roles exist in the repo but are not currently included by ansible/site.yml.
• Minimum dependencies: Python 3, Ansible, target host access (local or SSH). Setup: python3 -m pip install ansible.

Code style guidelines

Core principles

• Prefer declarative, idempotent, host-safe automation.
• Keep layering explicit: all -> OS -> profile -> host.
• Keep changes minimal, scoped, and reversible.
• Avoid speculative refactors unrelated to the requested task.

Modules, imports, and task structure

• Use FQCN modules (ansible.builtin.copy, community.general.xbps).
• Prefer dedicated modules over ansible.builtin.command and ansible.builtin.shell.
• Use command/shell only when no module exists; explain intent in task name.
• For command/shell, define changed_when and failed_when when defaults are unsafe.
• Keep ansible/site.yml orchestration-only; place implementation details in roles.
• Keep roles domain-focused (packages, services, profiles, dotfiles).

YAML formatting and file hygiene

• Start YAML documents with ---.
• Use 2-space indentation; never tabs.
• Keep key ordering stable and meaningful.
• Quote file modes as strings ("0644", "0755", "0600", "0700").
• Use multiline Jinja for long expressions.
• Avoid trailing whitespace and formatting-only churn.

Variables, types, and templating

• Use snake_case names for variables.
• Use semantically scoped names (common_packages, void_packages_base, profile_packages, host_packages).
• Keep booleans as booleans (true/false), not quoted strings.
• Keep lists/maps as YAML collections, not comma-separated strings.
• Guard optional values with default([]) and default({}).
• Build home-relative paths from {{ user_home }} consistently.

Naming conventions

• Role directory names: lowercase with underscores.
• Task names: imperative, outcome-based, and unique enough for --start-at-task.
• Keep inventory group names aligned with related var files.

Error handling and safety

• Guard OS/profile-specific behavior with when clauses.
• Prefer explicit loop inputs over implicit assumptions.
• Do not suppress failures unless there is a clear operational reason.
• Validate risky changes with --check --diff before full apply.
• Avoid destructive operations in user homes unless explicitly required.
• Keep tasks non-interactive and automation-safe.

Dotfiles and shell script style

• Prefer POSIX sh; use Bash only when Bash features are required.
• Bash scripts must use #!/usr/bin/env bash.
• Quote expansions ("$var") unless intentional word splitting is required.
• Preserve executable bits for copied scripts (mode: preserve where appropriate).

Agent workflow expectations

• Do not modify unrelated files.
• Read inventory, vars, and relevant roles before editing.
• Keep AGENTS and README aligned when workflows/commands change.
• When adding roles or domains, also add validation and targeting guidance.
• Prefer --limit <host> validation before broader runs.

Pre-merge checklist

Run before proposing/finalizing changes:

• ansible-playbook ansible/site.yml --syntax-check
• ansible-playbook ansible/site.yml --check --diff --limit <host>
• ansible-inventory --graph
• If available: ansible-lint ansible/site.yml and yamllint ansible/