ai-instructions: Instructions file for GitHub Copilot

Ansible Role Governance

Dependencies

• For task-execution conventions (idempotency, variable passing, and changed_when/failed_when keys), defer to ansible-playbook-style.instructions.md.
• For playbook and task naming conventions, see ansible-playbook-style.instructions.md.

Naming Conventions

• Name role directories with lowercase snake_case.
• Name role task files with lowercase kebab-case or snake_case.
• Use one casing convention consistently within each role.
• Name variable keys with lowercase snake_case.

Rules

Directory ownership

• Keep each role self-contained with tasks, vars, handlers, templates, files, and meta directories as needed.
• Keep tasks/main.yml as the role entry point that orchestrates internal task files.
• Keep template rendering in templates/*.j2 and static artifacts in files/.
• Keep OS-specific task trees under tasks/<os_family>/ (for example tasks/debian/, tasks/ol9/, tasks/windows/).
• Keep reusable cross-role utilities as importable task files in a dedicated common role.
• Declare role dependencies and Galaxy collection requirements in meta/main.yml with required fields: role_name and namespace.

Role Metadata (meta/main.yml)

• Define galaxy_info with role_name, namespace, author, description, license, and min_ansible_version fields.
• Keep role_name lowercase without hyphens so it uniquely identifies the role.
• Keep namespace lowercase and matching ^[a-z][a-z0-9_-]+$; do not use dots.
• Do not use dot-separated namespace values (for example, local.proxmox).
• Run ansible-lint to validate meta/main.yml for Galaxy compliance before marking role complete.
• Do not assume default role name from directory; always explicitly declare role_name and namespace.

Variable boundaries

• Keep role defaults and vars scoped to the role.
• Use vars/main.yml for role-internal constants that must not be overridden by callers.
• Keep host- or environment-wide values in group_vars or role vars files.
• Reference group_vars values through named variables, not through direct lookup calls inside roles.